@viamrobotics/motion-tools 1.25.0 → 1.25.1

package/dist/FrameConfigUpdater.svelte.js

@@ -1,4 +1,4 @@
-import { traits } from './ecs';
+import { hierarchy, traits } from './ecs';
 export class FrameConfigUpdater {
     updateFrame;
     removeFrame;
@@ -19,7 +19,7 @@ export class FrameConfigUpdater {
             change.z = z;
         entity.set(traits.EditedPose, change);
         const name = entity.get(traits.Name);
-        const parent = entity.get(traits.Parent) ?? 'world';
+        const parent = hierarchy.getParentName(entity) ?? 'world';
         const updatedPose = entity.get(traits.EditedPose);
         if (name && updatedPose) {
             this.updateFrame(name, parent, updatedPose);
@@ -41,7 +41,7 @@ export class FrameConfigUpdater {
             change.theta = theta;
         entity.set(traits.EditedPose, change);
         const name = entity.get(traits.Name);
-        const parent = entity.get(traits.Parent) ?? 'world';
+        const parent = hierarchy.getParentName(entity) ?? 'world';
         const updatedPose = entity.get(traits.EditedPose);
         if (name && updatedPose) {
             this.updateFrame(name, parent, updatedPose);
@@ -49,7 +49,7 @@ export class FrameConfigUpdater {
     };
     updateGeometry = (entity, geometry) => {
         const name = entity.get(traits.Name);
-        const parent = entity.get(traits.Parent) ?? 'world';
+        const parent = hierarchy.getParentName(entity) ?? 'world';
         const pose = entity.get(traits.EditedPose);
         if (geometry?.type === 'box') {
             const { x, y, z } = geometry;
@@ -109,7 +109,7 @@ export class FrameConfigUpdater {
     };
     setGeometryType = (entity, type) => {
         const name = entity.get(traits.Name);
-        const parent = entity.get(traits.Parent) ?? 'world';
+        const parent = hierarchy.getParentName(entity) ?? 'world';
         const pose = entity.get(traits.EditedPose);
         if (!name || !pose)
             return;

package/dist/components/BatchedArrows.svelte

@@ -5,7 +5,7 @@
 	import { Portal } from '@threlte/extras'
 	import { Color, Vector3 } from 'three'
 
-	import { traits, useWorld } from '../ecs'
+	import { hierarchy, traits, useWorld } from '../ecs'
 	import { BatchedArrow } from '../three/BatchedArrow'
 
 	const arrowBatchMap = $state<Record<string, BatchedArrow>>({
@@ -20,7 +20,7 @@
 	const color = new Color()
 
 	const onAdd = (entity: Entity) => {
-		const parent = entity.get(traits.Parent) ?? 'world'
+		const parent = hierarchy.getParentName(entity) ?? 'world'
 
 		arrowBatchMap[parent] ??= new BatchedArrow()
 		const batched = arrowBatchMap[parent]
@@ -40,7 +40,7 @@
 	const onPoseChange = (entity: Entity) => {
 		if (!entity.has(traits.Arrow)) return
 
-		const parent = entity.get(traits.Parent) ?? 'world'
+		const parent = hierarchy.getParentName(entity) ?? 'world'
 		const batch = arrowBatchMap[parent]
 		const instanceID = entity.get(traits.Instance)?.instanceID
 		const pose = entity.get(traits.Pose)
@@ -57,7 +57,7 @@
 	const onColorChange = (entity: Entity) => {
 		if (!entity.has(traits.Arrow)) return
 
-		const parent = entity.get(traits.Parent) ?? 'world'
+		const parent = hierarchy.getParentName(entity) ?? 'world'
 		const batch = arrowBatchMap[parent]
 		const instanceID = entity.get(traits.Instance)?.instanceID
 		const colorRGB = entity.get(traits.Color)

package/dist/components/Entities/Arrows/Arrows.svelte

@@ -8,7 +8,7 @@
 
 	import AxesHelper from '../../AxesHelper.svelte'
 	import { useEntityEvents } from '../hooks/useEntityEvents.svelte'
-	import { traits, useTrait } from '../../../ecs'
+	import { traits, useParentName, useTrait } from '../../../ecs'
 	import { useFocusedEntity, useSelectedEntity } from '../../../hooks/useSelection.svelte'
 	import { meshBoundsRaycast, raycast } from '../../../three/InstancedArrows/raycast'
 
@@ -19,7 +19,7 @@
 
 	let { entity, arrows }: Props = $props()
 
-	const parent = useTrait(() => entity, traits.Parent)
+	const parent = useParentName(() => entity)
 	const invisible = useTrait(() => entity, traits.Invisible)
 	const showAxesHelper = useTrait(() => entity, traits.ShowAxesHelper)
 

package/dist/components/Entities/Frame.svelte

@@ -20,7 +20,7 @@ Renders a Viam Frame object
 
 	import { asColor } from '../../buffer'
 	import { colors, resourceColors } from '../../color'
-	import { traits, useTrait } from '../../ecs'
+	import { traits, useParentName, useTrait } from '../../ecs'
 	import { useResourceByName } from '../../hooks/useResourceByName.svelte'
 	import { poseToObject3d } from '../../transform'
 
@@ -39,7 +39,7 @@ Renders a Viam Frame object
 	const resourceByName = useResourceByName()
 
 	const name = useTrait(() => entity, traits.Name)
-	const parent = useTrait(() => entity, traits.Parent)
+	const parent = useParentName(() => entity)
 	const entityColors = useTrait(() => entity, traits.Colors)
 	const entityColor = useTrait(() => entity, traits.Color)
 	const entityPose = useTrait(() => entity, traits.Pose)

package/dist/components/Entities/GLTF.svelte

@@ -19,7 +19,7 @@
 	import { Portal, PortalTarget, type ThrelteGltf, useGltfAnimations } from '@threlte/extras'
 	import { Group, type Object3D } from 'three'
 
-	import { traits, useTrait } from '../../ecs'
+	import { traits, useParentName, useTrait } from '../../ecs'
 	import { poseToObject3d } from '../../transform'
 
 	import AxesHelper from '../AxesHelper.svelte'
@@ -35,7 +35,7 @@
 	const { gltf, actions } = useGltfAnimations()
 
 	const name = useTrait(() => entity, traits.Name)
-	const parent = useTrait(() => entity, traits.Parent)
+	const parent = useParentName(() => entity)
 	const pose = useTrait(() => entity, traits.Pose)
 	const gltfTrait = useTrait(() => entity, traits.GLTF)
 	const scale = useTrait(() => entity, traits.Scale)

package/dist/components/Entities/Geometry.svelte

@@ -10,7 +10,7 @@ Renders a Viam Geometry object
 	import { T, useThrelte } from '@threlte/core'
 	import { Portal } from '@threlte/extras'
 
-	import { traits, useTrait } from '../../ecs'
+	import { traits, useParentName, useTrait } from '../../ecs'
 	import { use3DModels } from '../../hooks/use3DModels.svelte'
 	import { useSettings } from '../../hooks/useSettings.svelte'
 	import { poseToObject3d } from '../../transform'
@@ -31,7 +31,7 @@ Renders a Viam Geometry object
 	const models = use3DModels()
 
 	const name = useTrait(() => entity, traits.Name)
-	const parent = useTrait(() => entity, traits.Parent)
+	const parent = useParentName(() => entity)
 	const center = useTrait(() => entity, traits.Center)
 	const invisible = useTrait(() => entity, traits.Invisible)
 

package/dist/components/Entities/Line.svelte

@@ -7,7 +7,7 @@
 	import { Line2, LineMaterial } from 'three/examples/jsm/Addons.js'
 
 	import { isVertexColors, STRIDE } from '../../buffer'
-	import { traits, useTrait } from '../../ecs'
+	import { traits, useParentName, useTrait } from '../../ecs'
 	import { poseToObject3d } from '../../transform'
 
 	import AxesHelper from '../AxesHelper.svelte'
@@ -24,7 +24,7 @@
 
 	const { invalidate } = useThrelte()
 	const name = useTrait(() => entity, traits.Name)
-	const parent = useTrait(() => entity, traits.Parent)
+	const parent = useParentName(() => entity)
 	const pose = useTrait(() => entity, traits.Pose)
 	const color = useTrait(() => entity, traits.Color)
 	const colors = useTrait(() => entity, traits.Colors)

package/dist/components/Entities/Points.svelte

@@ -7,7 +7,7 @@
 	import { OrthographicCamera, Points, PointsMaterial } from 'three'
 
 	import { asColor, isSingleColor } from '../../buffer'
-	import { traits, useTrait } from '../../ecs'
+	import { traits, useParentName, useTrait } from '../../ecs'
 	import { useSettings } from '../../hooks/useSettings.svelte'
 	import { poseToObject3d } from '../../transform'
 
@@ -24,7 +24,7 @@
 	const { camera } = useThrelte()
 	const settings = useSettings()
 
-	const parent = useTrait(() => entity, traits.Parent)
+	const parent = useParentName(() => entity)
 	const pose = useTrait(() => entity, traits.Pose)
 	const geometry = useTrait(() => entity, traits.BufferGeometry)
 	const entityColor = useTrait(() => entity, traits.Color)

package/dist/components/Entities/Pose.svelte

@@ -3,7 +3,7 @@
 	import type { Entity } from 'koota'
 	import type { Snippet } from 'svelte'
 
-	import { traits, useTrait } from '../../ecs'
+	import { traits, useParentName, useTrait } from '../../ecs'
 	import { usePartConfig } from '../../hooks/usePartConfig.svelte'
 	import { usePose } from '../../hooks/usePose.svelte'
 	import { composeRenderedPose } from '../../transform'
@@ -16,7 +16,7 @@
 
 	const partConfig = usePartConfig()
 	const name = useTrait(() => entity, traits.Name)
-	const parent = useTrait(() => entity, traits.Parent)
+	const parent = useParentName(() => entity)
 	const editedPose = useTrait(() => entity, traits.EditedPose)
 	const entityPose = useTrait(() => entity, traits.Pose)
 

package/dist/components/SceneProviders.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte'
 
+	import { provideHierarchy } from '../ecs'
 	import { provide3DModels } from '../hooks/use3DModels.svelte'
 	import { provideArmClient } from '../hooks/useArmClient.svelte'
 	import { provideArmKinematics } from '../hooks/useArmKinematics.svelte'
@@ -41,6 +42,7 @@
 	provideTransformControls()
 	provideLogs()
 
+	provideHierarchy()
 	provideOrigin()
 	provideDrawAPI()
 	provideRelationships()

package/dist/components/Snapshot.svelte

@@ -23,7 +23,7 @@ Renders a Snapshot protobuf by spawning its transforms and drawings as entities
 	import { useCameraControls } from '../hooks/useControls.svelte'
 	import { useRelationships } from '../hooks/useRelationships.svelte'
 	import { useSettings } from '../hooks/useSettings.svelte'
-	import { applySceneMetadata, type SnapshotEntity, spawnSnapshotEntities } from '../snapshot'
+	import { applySceneMetadata, reconcileSnapshotEntities, type SnapshotEntity } from '../snapshot'
 
 	interface Props {
 		snapshot: SnapshotProto
@@ -36,17 +36,24 @@ Renders a Snapshot protobuf by spawning its transforms and drawings as entities
 	const cameraControls = useCameraControls()
 	const relationships = useRelationships()
 
-	let entities: SnapshotEntity[] = []
+	let entitiesByUuid = new Map<string, SnapshotEntity>()
+	let unkeyedEntities: SnapshotEntity[] = []
 
 	$effect(() => {
-		world.id.toString()
-		snapshot.uuid.toString()
+		void snapshot
 
 		untrack(() => {
-			entities = spawnSnapshotEntities(world, snapshot)
-			for (const spawned of entities) {
-				relationships.apply(spawned.entity, spawned.relationships)
-				const uuid = spawned.entity.get(traits.UUID)
+			for (const entry of unkeyedEntities) {
+				if (world.has(entry.entity)) entry.entity.destroy()
+			}
+
+			const result = reconcileSnapshotEntities(world, snapshot, entitiesByUuid)
+			entitiesByUuid = result.current
+			unkeyedEntities = result.unkeyed
+
+			for (const entry of [...result.spawned, ...result.updated]) {
+				relationships.apply(entry.entity, entry.relationships)
+				const uuid = entry.entity.get(traits.UUID)
 				if (uuid) relationships.flush(uuid)
 			}
 		})
@@ -83,8 +90,11 @@ Renders a Snapshot protobuf by spawning its transforms and drawings as entities
 	})
 
 	onDestroy(() => {
-		for (const spawned of entities) {
-			if (world.has(spawned.entity)) spawned.entity.destroy()
+		for (const entry of entitiesByUuid.values()) {
+			if (world.has(entry.entity)) entry.entity.destroy()
+		}
+		for (const entry of unkeyedEntities) {
+			if (world.has(entry.entity)) entry.entity.destroy()
 		}
 	})
 </script>

package/dist/components/overlay/Details.svelte

@@ -38,7 +38,7 @@
 	} from 'svelte-tweakpane-ui'
 
 	import AddRelationship from './AddRelationship.svelte'
-	import { relations, traits, useTrait, useWorld } from '../../ecs'
+	import { hierarchy, relations, traits, useParentName, useTrait, useWorld } from '../../ecs'
 	import { FrameConfigUpdater } from '../../FrameConfigUpdater.svelte'
 	import { useConfigFrames } from '../../hooks/useConfigFrames.svelte'
 	import { useCameraControls } from '../../hooks/useControls.svelte'
@@ -79,7 +79,7 @@
 	const worldOrientation = $state({ x: 0, y: 0, z: 1, th: 0 })
 	const linkedEntities = useLinkedEntities()
 	const name = useTrait(() => entity, traits.Name)
-	const parent = useTrait(() => entity, traits.Parent)
+	const parent = useParentName(() => entity)
 	const localPose = useTrait(() => entity, traits.EditedPose)
 	const box = useTrait(() => entity, traits.Box)
 	const sphere = useTrait(() => entity, traits.Sphere)
@@ -220,7 +220,7 @@
 		if (event.detail.origin !== 'internal' || !entity) return
 		const value = event.detail.value as string
 		if (value === parent.current) return
-		traits.setParentTrait(entity, value)
+		hierarchy.setParent(entity, value)
 		detailConfigUpdater.setFrameParent(entity, value)
 	}
 

package/dist/components/overlay/__tests__/__fixtures__/entity.js

@@ -1,6 +1,6 @@
-import { traits } from '../../../../ecs';
+import { hierarchy, traits } from '../../../../ecs';
 export const createEntityFixture = (world) => {
-    return world.spawn(traits.Parent('parent_frame'), traits.Name('Test Object'), traits.Pose({
+    return world.spawn(...hierarchy.parentTraits('parent_frame'), traits.Name('Test Object'), traits.Pose({
         x: 10,
         y: 20,
         z: 30,

package/dist/components/overlay/left-pane/buildTree.js

@@ -1,4 +1,4 @@
-import { traits } from '../../../ecs';
+import { hierarchy, traits } from '../../../ecs';
 function sortNodes(nodes) {
     nodes.sort((a, b) => a.entity.get(traits.Name)?.localeCompare(b.entity.get(traits.Name) ?? '') ?? 0);
 }
@@ -10,7 +10,7 @@ export const buildTreeNodes = (entities) => {
     const rootNodes = [];
     const childNodes = [];
     for (const entity of entities) {
-        const parent = entity.get(traits.Parent);
+        const parent = hierarchy.getParentName(entity);
         const name = entity.get(traits.Name) ?? '';
         const node = { entity };
         nodeMap[name] = node;
@@ -22,7 +22,7 @@ export const buildTreeNodes = (entities) => {
         }
     }
     for (const node of childNodes) {
-        const parent = node.entity.get(traits.Parent);
+        const parent = hierarchy.getParentName(node.entity);
         if (parent) {
             const parentNode = nodeMap[parent];
             node.parent = parentNode;

package/dist/draw.js

@@ -3,7 +3,7 @@ import { NURBSCurve } from 'three/addons/curves/NURBSCurve.js';
 import { UuidTool } from 'uuid-tool';
 import { createBufferGeometry, preAllocateBufferGeometry, updateBufferGeometry, writeBufferGeometryRange, } from './attribute';
 import { asFloat32Array, asOpacity, asRGB, inMeters, isSingleColor, isVertexColors, STRIDE, } from './buffer';
-import { relations, traits } from './ecs';
+import { hierarchy, relations, traits } from './ecs';
 import { parsePcdInWorker } from './loaders/pcd';
 import { metadataFromStruct } from './metadata';
 import { createPose } from './transform';
@@ -55,7 +55,7 @@ export const drawTransform = (world, { referenceFrame, poseInObserverFrame, phys
     }
     if (removable)
         entityTraits.push(traits.Removable);
-    entityTraits.push(...traits.getParentTrait(poseInObserverFrame?.referenceFrame));
+    entityTraits.push(...hierarchy.parentTraits(poseInObserverFrame?.referenceFrame));
     const parsedMetadata = metadataFromStruct(metadata?.fields);
     if (parsedMetadata.showAxesHelper)
         entityTraits.push(traits.ShowAxesHelper);
@@ -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, ...traits.getParentTrait(poseInObserverFrame?.referenceFrame), ...uuidTraits);
+    const entity = world.spawn(traits.Name(referenceFrame), traits.Pose(createPose(poseInObserverFrame?.pose)), api, ...hierarchy.parentTraits(poseInObserverFrame?.referenceFrame), ...uuidTraits);
     if (removable)
         entity.add(traits.Removable);
     if (metadata?.showAxesHelper)
@@ -100,7 +100,7 @@ export const drawDrawing = (world, drawing, api, { removable = true } = {}) => {
 };
 export const updateTransform = (entity, { poseInObserverFrame, physicalObject, metadata }, { removable = true } = {}) => {
     entity.set(traits.Pose, createPose(poseInObserverFrame?.pose));
-    traits.setParentTrait(entity, poseInObserverFrame?.referenceFrame);
+    hierarchy.setParent(entity, poseInObserverFrame?.referenceFrame);
     if (physicalObject) {
         traits.updateGeometryTrait(entity, physicalObject);
         const center = physicalObject.center;
@@ -145,7 +145,7 @@ export const updateDrawing = (world, entity, drawing, { removable = true } = {})
     if (!world.has(entity))
         return { entity, relationships: metadata?.relationships };
     entity.set(traits.Pose, createPose(poseInObserverFrame?.pose));
-    traits.setParentTrait(entity, poseInObserverFrame?.referenceFrame);
+    hierarchy.setParent(entity, poseInObserverFrame?.referenceFrame);
     if (metadata?.showAxesHelper)
         entity.add(traits.ShowAxesHelper);
     if (!metadata?.showAxesHelper)
@@ -163,7 +163,7 @@ export const updateDrawing = (world, entity, drawing, { removable = true } = {})
 };
 export const updateModel = (world, entity, drawing, api, { removable = true } = {}) => {
     if (world.has(entity))
-        entity.destroy();
+        hierarchy.destroyEntityTree(world, entity);
     return drawDrawing(world, drawing, api, { removable });
 };
 const applyShape = (entity, { physicalObject, metadata }) => {
@@ -272,7 +272,7 @@ const drawModel = (world, model, api, { removable = true }) => {
         traits.Name(referenceFrame),
         traits.Pose(createPose(poseInObserverFrame?.pose)),
         api,
-        ...traits.getParentTrait(poseInObserverFrame?.referenceFrame),
+        ...hierarchy.parentTraits(poseInObserverFrame?.referenceFrame),
     ];
     const uuidStr = uuidBytesToString(uuid);
     if (uuidStr)
@@ -288,7 +288,6 @@ const drawModel = (world, model, api, { removable = true }) => {
     for (const asset of assets) {
         const subEntityTraits = [
             traits.Name(`${referenceFrame} model ${i++}`),
-            traits.Parent(referenceFrame),
             relations.ChildOf(root),
             api,
         ];

package/dist/ecs/hierarchy.d.ts

@@ -0,0 +1,36 @@
+import { type ConfigurableTrait, type Entity, type QueryResult, type Trait, type World } from 'koota';
+/**
+ * Trait list for `world.spawn(...)`. Always emits `Orphan(name)` for non-root
+ * parents; the hierarchy resolver (`provideHierarchy`) swaps it to
+ * `ChildOf(parentEntity)` once a frame with that name exists. Returns `[]`
+ * for the world root (`undefined`, `''`, or `'world'`).
+ */
+export declare const parentTraits: (name: string | undefined) => ConfigurableTrait[];
+/**
+ * Set or clear an entity's parent. Strips any existing `ChildOf` or `Orphan`,
+ * then writes `Orphan(name)` (the resolver converts it to `ChildOf` on the
+ * next reactive flush). Pass `undefined` or `'world'` to detach to root.
+ */
+export declare const setParent: (entity: Entity, name: string | undefined) => void;
+/** The parent entity, or `undefined` at the world root or while orphaned. */
+export declare const getParentEntity: (entity: Entity) => Entity | undefined;
+/**
+ * The parent's name string. Reads through `ChildOf` first, falls back to
+ * `Orphan(name)` while the parent isn't present. Returns `undefined` for
+ * world-root entities.
+ */
+export declare const getParentName: (entity: Entity) => string | undefined;
+/**
+ * Destroy an entity and every `ChildOf` descendant, depth-first. Use for
+ * sub-trees whose lifetimes are tied together (e.g. a model root and its
+ * GLTF assets). General frame removal should use `entity.destroy()` so
+ * children survive as orphans.
+ */
+export declare const destroyEntityTree: (world: World, entity: Entity) => void;
+/**
+ * Synchronously resolve every `Orphan` whose desired parent now exists in
+ * the world. Called by `provideHierarchy` when the orphan/named query sets
+ * change or when a `Name` is renamed; also exposed for tests so they can
+ * drive resolution without mounting a component.
+ */
+export declare const resolveOrphans: (named: QueryResult<[Trait<() => string>]>, orphans: QueryResult<[Trait<() => string>]>) => void;

package/dist/ecs/hierarchy.js

@@ -0,0 +1,80 @@
+import {} from 'koota';
+import { ChildOf } from './relations';
+import { Name, Orphan } from './traits';
+/**
+ * Trait list for `world.spawn(...)`. Always emits `Orphan(name)` for non-root
+ * parents; the hierarchy resolver (`provideHierarchy`) swaps it to
+ * `ChildOf(parentEntity)` once a frame with that name exists. Returns `[]`
+ * for the world root (`undefined`, `''`, or `'world'`).
+ */
+export const parentTraits = (name) => {
+    if (!name || name === 'world')
+        return [];
+    return [Orphan(name)];
+};
+/**
+ * Set or clear an entity's parent. Strips any existing `ChildOf` or `Orphan`,
+ * then writes `Orphan(name)` (the resolver converts it to `ChildOf` on the
+ * next reactive flush). Pass `undefined` or `'world'` to detach to root.
+ */
+export const setParent = (entity, name) => {
+    const target = entity.targetFor(ChildOf);
+    if (target)
+        entity.remove(ChildOf(target));
+    entity.remove(Orphan);
+    if (!name || name === 'world')
+        return;
+    entity.add(Orphan(name));
+};
+/** The parent entity, or `undefined` at the world root or while orphaned. */
+export const getParentEntity = (entity) => entity.targetFor(ChildOf);
+/**
+ * The parent's name string. Reads through `ChildOf` first, falls back to
+ * `Orphan(name)` while the parent isn't present. Returns `undefined` for
+ * world-root entities.
+ */
+export const getParentName = (entity) => {
+    const parent = entity.targetFor(ChildOf);
+    if (parent && parent.isAlive())
+        return parent.get(Name);
+    const orphanFor = entity.get(Orphan);
+    return orphanFor || undefined;
+};
+/**
+ * Destroy an entity and every `ChildOf` descendant, depth-first. Use for
+ * sub-trees whose lifetimes are tied together (e.g. a model root and its
+ * GLTF assets). General frame removal should use `entity.destroy()` so
+ * children survive as orphans.
+ */
+export const destroyEntityTree = (world, entity) => {
+    if (!entity.isAlive())
+        return;
+    for (const child of world.query(ChildOf(entity))) {
+        destroyEntityTree(world, child);
+    }
+    entity.destroy();
+};
+/**
+ * Synchronously resolve every `Orphan` whose desired parent now exists in
+ * the world. Called by `provideHierarchy` when the orphan/named query sets
+ * change or when a `Name` is renamed; also exposed for tests so they can
+ * drive resolution without mounting a component.
+ */
+export const resolveOrphans = (named, orphans) => {
+    const index = new Map();
+    for (const entity of named) {
+        const name = entity.get(Name);
+        if (name)
+            index.set(name, entity);
+    }
+    for (const orphan of orphans) {
+        const wantedName = orphan.get(Orphan);
+        if (!wantedName)
+            continue;
+        const parent = index.get(wantedName);
+        if (!parent)
+            continue;
+        orphan.remove(Orphan);
+        orphan.add(ChildOf(parent));
+    }
+};

package/dist/ecs/index.d.ts

@@ -1,5 +1,9 @@
 export { provideWorld, useWorld } from './useWorld';
 export { useQuery } from './useQuery.svelte';
 export { useTrait } from './useTrait.svelte';
+export { useTarget } from './useTarget.svelte';
+export { useParentName } from './useParentName.svelte';
+export { provideHierarchy } from './provideHierarchy.svelte';
 export * as traits from './traits';
 export * as relations from './relations';
+export * as hierarchy from './hierarchy';

package/dist/ecs/index.js

@@ -1,5 +1,9 @@
 export { provideWorld, useWorld } from './useWorld';
 export { useQuery } from './useQuery.svelte';
 export { useTrait } from './useTrait.svelte';
+export { useTarget } from './useTarget.svelte';
+export { useParentName } from './useParentName.svelte';
+export { provideHierarchy } from './provideHierarchy.svelte';
 export * as traits from './traits';
 export * as relations from './relations';
+export * as hierarchy from './hierarchy';

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

@@ -0,0 +1,17 @@
+/**
+ * Mounts the hierarchy resolver: each tick, any entity with `Orphan(name)`
+ * whose desired parent is now in the world is converted to
+ * `ChildOf(parentEntity)`. Call once at the top of the app, alongside the
+ * other `provide*` hooks.
+ *
+ * Reactive on:
+ *   - `useQuery(Orphan)` membership — new orphans appear or resolve away
+ *   - `useQuery(Name)` membership — new candidate parents appear/disappear
+ *   - `world.onChange(Name)` — an existing entity is renamed into a name
+ *     that some orphan is waiting for
+ *
+ * Children whose `ChildOf` parent is destroyed are *not* automatically
+ * re-orphaned. Call `hierarchy.setParent` on the affected children
+ * explicitly if you need them to reattach to a same-named replacement.
+ */
+export declare const provideHierarchy: () => void;

package/dist/ecs/provideHierarchy.svelte.js

@@ -0,0 +1,31 @@
+import { resolveOrphans } from './hierarchy';
+import { Name, Orphan } from './traits';
+import { useQuery } from './useQuery.svelte';
+import { useWorld } from './useWorld';
+/**
+ * Mounts the hierarchy resolver: each tick, any entity with `Orphan(name)`
+ * whose desired parent is now in the world is converted to
+ * `ChildOf(parentEntity)`. Call once at the top of the app, alongside the
+ * other `provide*` hooks.
+ *
+ * Reactive on:
+ *   - `useQuery(Orphan)` membership — new orphans appear or resolve away
+ *   - `useQuery(Name)` membership — new candidate parents appear/disappear
+ *   - `world.onChange(Name)` — an existing entity is renamed into a name
+ *     that some orphan is waiting for
+ *
+ * Children whose `ChildOf` parent is destroyed are *not* automatically
+ * re-orphaned. Call `hierarchy.setParent` on the affected children
+ * explicitly if you need them to reattach to a same-named replacement.
+ */
+export const provideHierarchy = () => {
+    const world = useWorld();
+    const orphans = useQuery(Orphan);
+    const named = useQuery(Name);
+    $effect(() => {
+        resolveOrphans(named.current, orphans.current);
+    });
+    $effect(() => {
+        return world.onChange(Name, () => resolveOrphans(named.current, orphans.current));
+    });
+};

package/dist/ecs/relations.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Parent → child hierarchy relation. `exclusive: true` because each entity has
+ * at most one parent. Cascade-on-orphan is intentionally OFF: when a parent is
+ * destroyed, children survive and gain an `Orphan(parentName)` trait so they
+ * reattach if a frame with that name reappears. Sub-trees that should be torn
+ * down together (e.g. model roots + assets) call `destroyEntityTree` instead.
+ */
 export declare const ChildOf: import("koota").Relation<import("koota").Trait<Record<string, never>>>;
 export declare const SubEntityLinkType: {
     readonly HoverLink: "HoverLink";

package/dist/ecs/relations.js

@@ -1,5 +1,12 @@
 import { relation } from 'koota';
-export const ChildOf = relation({ exclusive: true, autoDestroy: 'orphan' });
+/**
+ * Parent → child hierarchy relation. `exclusive: true` because each entity has
+ * at most one parent. Cascade-on-orphan is intentionally OFF: when a parent is
+ * destroyed, children survive and gain an `Orphan(parentName)` trait so they
+ * reattach if a frame with that name reappears. Sub-trees that should be torn
+ * down together (e.g. model roots + assets) call `destroyEntityTree` instead.
+ */
+export const ChildOf = relation({ exclusive: true });
 export const SubEntityLinkType = {
     HoverLink: 'HoverLink',
 };

package/dist/ecs/traits.d.ts

@@ -1,10 +1,17 @@
 import type { GLTF as ThreeGltf } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import { Geometry as ViamGeometry } from '@viamrobotics/sdk';
-import { type ConfigurableTrait, type Entity } from 'koota';
+import { type Entity } from 'koota';
 import { BufferGeometry as ThreeBufferGeometry } from 'three';
 export declare const Name: import("koota").Trait<() => string>;
-export declare const Parent: import("koota").Trait<() => string>;
 export declare const UUID: import("koota").Trait<() => string>;
+/**
+ * Set on an entity whose desired parent (by name) doesn't yet exist in the
+ * world. Replaced with `relations.ChildOf(parentEntity)` once a frame with
+ * the matching `Name` is added. Managed by the hierarchy module — call sites
+ * should use `hierarchy.setParent` / `hierarchy.parentTraits` rather than
+ * adding this trait directly.
+ */
+export declare const Orphan: import("koota").Trait<() => string>;
 export declare const Pose: import("koota").Trait<{
     x: number;
     y: number;
@@ -223,6 +230,4 @@ export declare const Geometry: (geometry: ViamGeometry) => import("koota").Trait
 }>, Partial<{
     r: number;
 }>] | [import("koota").Trait<() => ThreeBufferGeometry<import("three").NormalBufferAttributes, import("three").BufferGeometryEventMap>>, ThreeBufferGeometry<import("three").NormalBufferAttributes, import("three").BufferGeometryEventMap>];
-export declare const getParentTrait: (parent: string | undefined) => ConfigurableTrait[];
-export declare const setParentTrait: (entity: Entity, parent: string | undefined) => void;
 export declare const updateGeometryTrait: (entity: Entity, geometry?: ViamGeometry) => void;

package/dist/ecs/traits.js

@@ -7,8 +7,15 @@ import { createBox, createCapsule, createSphere } from '../geometry';
 import { parsePcdInWorker } from '../loaders/pcd';
 import { parsePlyInput } from '../ply';
 export const Name = trait(() => '');
-export const Parent = trait(() => 'world');
 export const UUID = trait(() => '');
+/**
+ * Set on an entity whose desired parent (by name) doesn't yet exist in the
+ * world. Replaced with `relations.ChildOf(parentEntity)` once a frame with
+ * the matching `Name` is added. Managed by the hierarchy module — call sites
+ * should use `hierarchy.setParent` / `hierarchy.parentTraits` rather than
+ * 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 });
@@ -161,19 +168,6 @@ export const Geometry = (geometry) => {
     }
     return ReferenceFrame;
 };
-export const getParentTrait = (parent) => !parent || parent === 'world' ? [] : [Parent(parent)];
-export const setParentTrait = (entity, parent) => {
-    if (!parent || parent === 'world') {
-        entity.remove(Parent);
-        return;
-    }
-    if (entity.has(Parent)) {
-        entity.set(Parent, parent);
-    }
-    else {
-        entity.add(Parent(parent));
-    }
-};
 export const updateGeometryTrait = (entity, geometry) => {
     if (!geometry) {
         entity.remove(Box, Capsule, Sphere, BufferGeometry);

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

@@ -0,0 +1,11 @@
+import type { Entity } from 'koota';
+/**
+ * Reactive view of an entity's parent name — the string consumed by Threlte
+ * `<Portal id={...}>` and other lookups that key off the parent's `Name`.
+ *
+ * Reads through `ChildOf` to the parent's `Name` when the parent is alive,
+ * else falls back to `Orphan(parentName)`.
+ */
+export declare const useParentName: (target: () => Entity | undefined) => {
+    readonly current: string | undefined;
+};

package/dist/ecs/useParentName.svelte.js

@@ -0,0 +1,21 @@
+import { ChildOf } from './relations';
+import { Name, Orphan } from './traits';
+import { useTarget } from './useTarget.svelte';
+import { useTrait } from './useTrait.svelte';
+/**
+ * Reactive view of an entity's parent name — the string consumed by Threlte
+ * `<Portal id={...}>` and other lookups that key off the parent's `Name`.
+ *
+ * Reads through `ChildOf` to the parent's `Name` when the parent is alive,
+ * else falls back to `Orphan(parentName)`.
+ */
+export const useParentName = (target) => {
+    const parent = useTarget(target, ChildOf);
+    const parentName = useTrait(() => parent.current, Name);
+    const orphan = useTrait(target, Orphan);
+    return {
+        get current() {
+            return parentName.current || orphan.current || undefined;
+        },
+    };
+};

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

@@ -0,0 +1,10 @@
+import { type Entity, type Relation, type Trait, type World } from 'koota';
+/**
+ * Reactive view of an entity's target for an exclusive relation. Mirrors the
+ * forthcoming `useTarget` from the upstream `@koota/svelte` package — kept
+ * here until that package is published. See:
+ * https://github.com/michealparks/koota/tree/svelte/packages/svelte
+ */
+export declare const useTarget: <T extends Trait>(target: () => Entity | World | undefined | null, relation: Relation<T>) => {
+    readonly current: Entity | undefined;
+};

package/dist/ecs/useTarget.svelte.js

@@ -0,0 +1,42 @@
+import { $internal as internal } from 'koota';
+import { isWorld } from './useTrait.svelte';
+import { useWorld } from './useWorld';
+/**
+ * Reactive view of an entity's target for an exclusive relation. Mirrors the
+ * forthcoming `useTarget` from the upstream `@koota/svelte` package — kept
+ * here until that package is published. See:
+ * https://github.com/michealparks/koota/tree/svelte/packages/svelte
+ */
+export const useTarget = (target, relation) => {
+    const contextWorld = useWorld();
+    const targetEntity = $derived(target());
+    const world = $derived(isWorld(targetEntity) ? targetEntity : contextWorld);
+    const entity = $derived(isWorld(targetEntity) ? targetEntity[internal].worldEntity : targetEntity);
+    let value = $derived(entity?.targetFor(relation));
+    $effect(() => {
+        if (!entity)
+            return;
+        const onAddUnsub = world.onAdd(relation, (e) => {
+            if (e === entity)
+                value = entity.targetFor(relation);
+        });
+        const onRemoveUnsub = world.onRemove(relation, (e) => {
+            if (e === entity)
+                value = undefined;
+        });
+        const onChangeUnsub = world.onChange(relation, (e) => {
+            if (e === entity)
+                value = entity.targetFor(relation);
+        });
+        return () => {
+            onAddUnsub();
+            onRemoveUnsub();
+            onChangeUnsub();
+        };
+    });
+    return {
+        get current() {
+            return value;
+        },
+    };
+};

package/dist/editing/FrameEditSession.js

@@ -1,4 +1,4 @@
-import { traits } from '../ecs';
+import { hierarchy, traits } from '../ecs';
 import { isFinitePose } from '../transform';
 const captureGeometry = (entity) => {
     const box = entity.get(traits.Box);
@@ -76,7 +76,7 @@ export class FrameEditSession {
                 continue;
             this.snapshots.set(entity, {
                 name,
-                parent: entity.get(traits.Parent) ?? 'world',
+                parent: hierarchy.getParentName(entity) ?? 'world',
                 editedPose: { ...editedPose },
                 geometry: captureGeometry(entity),
             });
@@ -97,7 +97,7 @@ export class FrameEditSession {
             return;
         const next = { ...current, ...pose };
         entity.set(traits.EditedPose, next);
-        this.updateFrame(snap.name, entity.get(traits.Parent) ?? 'world', next, liveGeometry(entity));
+        this.updateFrame(snap.name, hierarchy.getParentName(entity) ?? 'world', next, liveGeometry(entity));
     };
     stageGeometry = (entity, geometry) => {
         const snap = this.snapshots.get(entity);
@@ -118,14 +118,14 @@ export class FrameEditSession {
         }
         const editedPose = entity.get(traits.EditedPose);
         if (editedPose) {
-            this.updateFrame(snap.name, entity.get(traits.Parent) ?? 'world', editedPose, geometry);
+            this.updateFrame(snap.name, hierarchy.getParentName(entity) ?? 'world', editedPose, geometry);
         }
     };
     stageParent = (entity, parent) => {
         const snap = this.snapshots.get(entity);
         if (!snap || this.#closed)
             return;
-        traits.setParentTrait(entity, parent === 'world' ? undefined : parent);
+        hierarchy.setParent(entity, parent === 'world' ? undefined : parent);
         const editedPose = entity.get(traits.EditedPose);
         if (editedPose) {
             this.updateFrame(snap.name, parent, editedPose, liveGeometry(entity));
@@ -164,7 +164,7 @@ export class FrameEditSession {
         for (const [entity, snap] of this.snapshots) {
             if (entity.isAlive()) {
                 entity.set(traits.EditedPose, snap.editedPose);
-                traits.setParentTrait(entity, snap.parent === 'world' ? undefined : snap.parent);
+                hierarchy.setParent(entity, snap.parent === 'world' ? undefined : snap.parent);
                 restoreGeometryTrait(entity, snap.geometry);
             }
             this.updateFrame(snap.name, snap.parent, snap.editedPose, snapshotToFrameGeometry(snap.geometry));

package/dist/hooks/useDrawAPI.svelte.js

@@ -8,7 +8,7 @@ import { UuidTool } from 'uuid-tool';
 import { createBufferGeometry, updateBufferGeometry } from '../attribute';
 import { ColorFormat } from '../buf/draw/v1/metadata_pb';
 import { asRGB, STRIDE } from '../buffer';
-import { traits, useWorld } from '../ecs';
+import { hierarchy, traits, useWorld } from '../ecs';
 import { createBox, createCapsule, createSphere } from '../geometry';
 import { parsePlyInput } from '../ply';
 import { createPose, createPoseFromFrame } from '../transform';
@@ -127,7 +127,7 @@ export const provideDrawAPI = () => {
             const existing = entities.get(name);
             if (existing) {
                 existing.set(traits.Pose, pose);
-                traits.setParentTrait(existing, parent);
+                hierarchy.setParent(existing, parent);
                 continue;
             }
             const geometryTrait = () => {
@@ -142,7 +142,7 @@ export const provideDrawAPI = () => {
                 }
                 return traits.ReferenceFrame;
             };
-            const entityTraits = [...traits.getParentTrait(parent)];
+            const entityTraits = [...hierarchy.parentTraits(parent)];
             if (frame.geometry) {
                 entityTraits.push(geometryTrait());
             }
@@ -178,7 +178,7 @@ export const provideDrawAPI = () => {
         };
         const entityTraits = [
             traits.Name(data.label ?? ++geometryIndex),
-            ...traits.getParentTrait(parent),
+            ...hierarchy.parentTraits(parent),
             traits.Pose(pose),
             traits.Color(colorUtil.set(color)),
             geometryTrait(),

package/dist/hooks/useFrames.svelte.js

@@ -3,7 +3,7 @@ import { createRobotQuery, useConnectionStatus, useMachineStatus, useRobotClient
 import {} from 'koota';
 import { getContext, setContext, untrack } from 'svelte';
 import { resourceNameToColor, subtypeToColor } from '../color';
-import { traits, useWorld } from '../ecs';
+import { hierarchy, traits, useWorld } from '../ecs';
 import { createPose } from '../transform';
 import { useConfigFrames } from './useConfigFrames.svelte';
 import { useEnvironment } from './useEnvironment.svelte';
@@ -169,7 +169,7 @@ export const provideFrames = (partID) => {
                     if (editSession.current?.owns(existing)) {
                         continue;
                     }
-                    traits.setParentTrait(existing, parent);
+                    hierarchy.setParent(existing, parent);
                     if (color) {
                         existing.set(traits.Color, color);
                     }
@@ -202,7 +202,7 @@ export const provideFrames = (partID) => {
                     traits.FramesAPI,
                     traits.Transformable,
                     traits.ShowAxesHelper,
-                    ...traits.getParentTrait(parent),
+                    ...hierarchy.parentTraits(parent),
                 ];
                 if (color) {
                     entityTraits.push(traits.Color(color));

package/dist/hooks/useGeometries.svelte.js

@@ -5,7 +5,7 @@ import { getContext, setContext, untrack } from 'svelte';
 import { Color } from 'three';
 import { resourceColors } from '../color';
 import { RefetchRates } from '../components/overlay/RefreshRate.svelte';
-import { traits, useWorld } from '../ecs';
+import { hierarchy, traits, useWorld } from '../ecs';
 import { updateGeometryTrait } from '../ecs/traits';
 import { createPose } from '../transform';
 import { useEnvironment } from './useEnvironment.svelte';
@@ -90,12 +90,13 @@ export const provideGeometries = (partID) => {
                         const center = createPose(geometry.center);
                         const existing = entities.get(entityKey);
                         if (existing) {
+                            hierarchy.setParent(existing, name);
                             existing.set(traits.Center, center);
                             updateGeometryTrait(existing, geometry);
                             continue;
                         }
                         const entityTraits = [
-                            traits.Parent(name),
+                            ...hierarchy.parentTraits(name),
                             traits.Name(label),
                             traits.Center(center),
                             traits.GeometriesAPI,

package/dist/hooks/usePointcloudObjects.svelte.js

@@ -4,7 +4,7 @@ import { getContext, setContext, untrack } from 'svelte';
 import { createBufferGeometry, updateBufferGeometry } from '../attribute';
 import { ColorFormat } from '../buf/draw/v1/metadata_pb';
 import { RefetchRates } from '../components/overlay/RefreshRate.svelte';
-import { traits, useWorld } from '../ecs';
+import { hierarchy, traits, useWorld } from '../ecs';
 import { parsePcdInWorker } from '../lib';
 import { createPose } from '../transform';
 import { useEnvironment } from './useEnvironment.svelte';
@@ -160,13 +160,14 @@ export const providePointcloudObjects = (partID) => {
                             const center = createPose(geometry.center);
                             const existing = entities.get(geometryLabel);
                             if (existing) {
+                                hierarchy.setParent(existing, geometriesInFrame.referenceFrame);
                                 existing.set(traits.Center, center);
                                 traits.updateGeometryTrait(existing, geometry);
                             }
                             else {
                                 const entityTraits = [
                                     traits.Name(geometryLabel),
-                                    ...traits.getParentTrait(geometriesInFrame.referenceFrame),
+                                    ...hierarchy.parentTraits(geometriesInFrame.referenceFrame),
                                     traits.Center(center),
                                     traits.GeometriesAPI,
                                     traits.Geometry(geometry),

package/dist/hooks/usePointclouds.svelte.js

@@ -4,7 +4,7 @@ import { getContext, setContext, untrack } from 'svelte';
 import { createBufferGeometry, updateBufferGeometry } from '../attribute';
 import { ColorFormat } from '../buf/draw/v1/metadata_pb';
 import { RefetchRates } from '../components/overlay/RefreshRate.svelte';
-import { traits, useWorld } from '../ecs';
+import { hierarchy, traits, useWorld } from '../ecs';
 import { parsePcdInWorker } from '../loaders/pcd';
 import { useEnvironment } from './useEnvironment.svelte';
 import { useLogs } from './useLogs.svelte';
@@ -108,6 +108,7 @@ export const providePointclouds = (partID) => {
                         colorFormat: ColorFormat.RGB,
                     };
                     if (existing) {
+                        hierarchy.setParent(existing, name);
                         const geometry = existing.get(traits.BufferGeometry);
                         if (geometry) {
                             updateBufferGeometry(geometry, positions, metadata);
@@ -115,7 +116,7 @@ export const providePointclouds = (partID) => {
                         }
                     }
                     const geometry = createBufferGeometry(positions, metadata);
-                    const entity = world.spawn(traits.Parent(name), traits.Name(`${name} pointcloud`), traits.BufferGeometry(geometry), traits.Points);
+                    const entity = world.spawn(...hierarchy.parentTraits(name), traits.Name(`${name} pointcloud`), traits.BufferGeometry(geometry), traits.Points);
                     entities.set(queryKey, entity);
                 })
                     .catch((error) => {

package/dist/snapshot.d.ts

@@ -24,3 +24,10 @@ export declare const applySceneMetadata: (settings: Settings, metadata: SceneMet
  * @returns The spawned entities
  */
 export declare const spawnSnapshotEntities: (world: World, snapshot: Snapshot) => SnapshotEntity[];
+export interface ReconcileResult {
+    current: Map<string, SnapshotEntity>;
+    unkeyed: SnapshotEntity[];
+    spawned: SnapshotEntity[];
+    updated: SnapshotEntity[];
+}
+export declare const reconcileSnapshotEntities: (world: World, snapshot: Snapshot, prev: Map<string, SnapshotEntity>) => ReconcileResult;

package/dist/snapshot.js

@@ -1,7 +1,7 @@
 import { RenderArmModels } from './buf/draw/v1/scene_pb';
 import { traits } from './ecs';
 import { rgbToHex } from './color';
-import { drawDrawing, drawTransform } from './draw';
+import { drawDrawing, drawTransform, updateDrawing, updateModel, updateTransform, uuidBytesToString, } from './draw';
 /**
  * Merges scene-level metadata (grid, camera, point/line settings) into the
  * current viewer settings. Millimeter values from the proto are converted
@@ -73,6 +73,79 @@ export const spawnSnapshotEntities = (world, snapshot) => {
     }
     return entities;
 };
+export const reconcileSnapshotEntities = (world, snapshot, prev) => {
+    const options = { removable: true, showAxesHelper: false };
+    const next = new Map(prev);
+    const seen = new Set();
+    const unkeyed = [];
+    const spawned = [];
+    const updated = [];
+    for (const transform of snapshot.transforms) {
+        const uuidStr = uuidBytesToString(transform.uuid);
+        if (!uuidStr) {
+            const result = drawTransform(world, transform, traits.SnapshotAPI, options);
+            const entry = { entity: result.entity, relationships: result.relationships };
+            unkeyed.push(entry);
+            spawned.push(entry);
+            continue;
+        }
+        const existing = next.get(uuidStr);
+        if (existing && world.has(existing.entity)) {
+            const result = updateTransform(existing.entity, transform, options);
+            const entry = { entity: result.entity, relationships: result.relationships };
+            next.set(uuidStr, entry);
+            updated.push(entry);
+        }
+        else {
+            const result = drawTransform(world, transform, traits.SnapshotAPI, options);
+            const entry = { entity: result.entity, relationships: result.relationships };
+            next.set(uuidStr, entry);
+            spawned.push(entry);
+        }
+        seen.add(uuidStr);
+    }
+    for (const drawing of snapshot.drawings) {
+        const uuidStr = uuidBytesToString(drawing.uuid);
+        if (!uuidStr) {
+            const result = drawDrawing(world, drawing, traits.SnapshotAPI, options);
+            const entry = { entity: result.entity, relationships: result.relationships };
+            unkeyed.push(entry);
+            spawned.push(entry);
+            continue;
+        }
+        const existing = next.get(uuidStr);
+        const isModel = drawing.physicalObject?.geometryType.case === 'model';
+        if (existing && world.has(existing.entity)) {
+            if (isModel) {
+                const result = updateModel(world, existing.entity, drawing, traits.SnapshotAPI, options);
+                const entry = { entity: result.entity, relationships: result.relationships };
+                next.set(uuidStr, entry);
+                spawned.push(entry);
+            }
+            else {
+                const result = updateDrawing(world, existing.entity, drawing, options);
+                const entry = { entity: result.entity, relationships: result.relationships };
+                next.set(uuidStr, entry);
+                updated.push(entry);
+            }
+        }
+        else {
+            const result = drawDrawing(world, drawing, traits.SnapshotAPI, options);
+            const entry = { entity: result.entity, relationships: result.relationships };
+            next.set(uuidStr, entry);
+            spawned.push(entry);
+        }
+        seen.add(uuidStr);
+    }
+    for (const [uuid, entry] of prev) {
+        if (seen.has(uuid))
+            continue;
+        if (world.has(entry.entity))
+            entry.entity.destroy();
+        next.delete(uuid);
+    }
+    return { current: next, unkeyed, spawned, updated };
+};
 const getRenderArmModels = (renderArmModels) => {
     switch (renderArmModels) {
         case RenderArmModels.COLLIDERS: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viamrobotics/motion-tools",
-  "version": "1.25.0",
+  "version": "1.25.1",
   "description": "Motion visualization with Viam",
   "license": "Apache-2.0",
   "type": "module",