@viamrobotics/motion-tools 1.19.1 → 1.22.0

package/dist/hooks/useDrawService.svelte.js

@@ -5,13 +5,17 @@ import { useThrelte } from '@threlte/core';
 import {} from 'koota';
 import { getContext, setContext } from 'svelte';
 import { UuidTool } from 'uuid-tool';
+import { writeBufferGeometryRange } from '../attribute';
 import { DrawService } from '../buf/draw/v1/service_connect';
-import { EntityChangeType, StreamEntityChangesResponse } from '../buf/draw/v1/service_pb';
-import { drawDrawing, drawTransform, updateDrawing, updateTransform, } from '../draw';
+import { CreateRelationshipRequest, DeleteRelationshipRequest, EntityChangeType, StreamEntityChangesResponse, } from '../buf/draw/v1/service_pb';
+import { asFloat32Array, inMeters, STRIDE } from '../buffer';
+import { drawDrawing, drawTransform, updateDrawing, updateModel, updateTransform, uuidStringToBytes, } from '../draw';
 import { traits, useWorld } from '../ecs';
 import { useCameraControls } from './useControls.svelte';
 import { useDrawConnectionConfig } from './useDrawConnectionConfig.svelte';
+import { useRelationships } from './useRelationships.svelte';
 const DRAW_SERVICE_KEY = Symbol('draw-service-context');
+const FLOAT32_SIZE = 4;
 const ConnectionStatus = {
     CONNECTED: 'connected',
     DISCONNECTED: 'disconnected',
@@ -22,6 +26,7 @@ export function provideDrawService() {
     const world = useWorld();
     const cameraControls = useCameraControls();
     const drawConnectionConfig = useDrawConnectionConfig();
+    const relationships = useRelationships();
     let connectionStatus = $state(ConnectionStatus.DISCONNECTED);
     const url = $derived(drawConnectionConfig.current?.backendIP
         ? `http://${drawConnectionConfig.current.backendIP}:3030`
@@ -30,6 +35,9 @@ export function provideDrawService() {
     const drawingEntities = new Map();
     let pendingEvents = [];
     let flushScheduled = false;
+    let activeClient;
+    let activeSignal;
+    const activeChunkPulls = new Set();
     const destroyTransform = (uuidStr) => {
         const entity = transformEntities.get(uuidStr);
         if (!entity)
@@ -39,13 +47,11 @@ export function provideDrawService() {
         transformEntities.delete(uuidStr);
     };
     const destroyDrawing = (uuidStr) => {
-        const entities = drawingEntities.get(uuidStr);
-        if (!entities)
+        const entity = drawingEntities.get(uuidStr);
+        if (!entity)
             return;
-        for (const entity of entities) {
-            if (world.has(entity))
-                entity.destroy();
-        }
+        if (world.has(entity))
+            entity.destroy();
         drawingEntities.delete(uuidStr);
     };
     const processEvent = (event) => {
@@ -62,7 +68,9 @@ export function provideDrawService() {
         if (changeType === EntityChangeType.ADDED) {
             if (!transformEntities.has(uuid)) {
                 const spawned = drawTransform(world, transform, traits.DrawServiceAPI);
-                transformEntities.set(uuid, spawned);
+                relationships.apply(spawned.entity, spawned.relationships);
+                transformEntities.set(uuid, spawned.entity);
+                relationships.flush(uuid);
             }
         }
         else if (changeType === EntityChangeType.REMOVED) {
@@ -71,11 +79,76 @@ export function provideDrawService() {
         else if (changeType === EntityChangeType.UPDATED) {
             const existing = transformEntities.get(uuid);
             if (existing) {
-                updateTransform(existing, transform);
+                const updated = updateTransform(existing, transform);
+                relationships.apply(updated.entity, updated.relationships);
             }
             else {
                 const spawned = drawTransform(world, transform, traits.DrawServiceAPI);
-                transformEntities.set(uuid, spawned);
+                relationships.apply(spawned.entity, spawned.relationships);
+                transformEntities.set(uuid, spawned.entity);
+                relationships.flush(uuid);
+            }
+        }
+    };
+    const isChunkedDrawing = (drawing) => {
+        return drawing.metadata?.chunks !== undefined && drawing.metadata.chunks.total > 0;
+    };
+    const getChunkInfo = (drawing) => {
+        const meta = drawing.metadata?.chunks;
+        if (!meta || meta.total === 0)
+            return undefined;
+        const shape = drawing.physicalObject?.geometryType;
+        if (shape?.case === 'points') {
+            const chunkElements = shape.value.positions.length / (STRIDE.POSITIONS * FLOAT32_SIZE);
+            return {
+                total: meta.total,
+                firstEnd: chunkElements,
+            };
+        }
+        return undefined;
+    };
+    const pullChunks = async (client, uuid, uuidBytes, entity, totalElements, firstChunkEnd, signal) => {
+        if (activeChunkPulls.has(uuid))
+            return;
+        activeChunkPulls.add(uuid);
+        try {
+            let nextStart = firstChunkEnd;
+            while (!signal.aborted) {
+                const response = await client.getEntityChunk({ uuid: uuidBytes, start: nextStart }, { signal });
+                // done with no payload is the server's "past end" sentinel (startByte >= posLen), not the final real chunk
+                if (response.done && !response.entity.value)
+                    break;
+                const drawing = response.entity.case === 'drawing' ? response.entity.value : undefined;
+                if (!drawing)
+                    break;
+                const shape = drawing.physicalObject?.geometryType;
+                if (shape?.case !== 'points')
+                    break;
+                const buffer = entity.get(traits.BufferGeometry);
+                if (!buffer)
+                    break;
+                const positions = asFloat32Array(shape.value.positions, inMeters);
+                const metadata = drawing.metadata;
+                if (!metadata)
+                    break;
+                writeBufferGeometryRange(buffer, positions, response.start, metadata);
+                const chunkElements = positions.length / 3;
+                nextStart = response.start + chunkElements;
+                entity.set(traits.ChunkProgress, { loaded: nextStart, total: totalElements });
+                invalidate();
+                if (response.done)
+                    break;
+            }
+        }
+        catch (error) {
+            if (!signal.aborted) {
+                console.error(`Chunk pull failed for entity ${uuid}:`, error);
+            }
+        }
+        finally {
+            activeChunkPulls.delete(uuid);
+            if (world.has(entity)) {
+                entity.remove(traits.ChunkProgress);
             }
         }
     };
@@ -83,7 +156,17 @@ export function provideDrawService() {
         if (changeType === EntityChangeType.ADDED) {
             if (!drawingEntities.has(uuid)) {
                 const spawned = drawDrawing(world, drawing, traits.DrawServiceAPI);
-                drawingEntities.set(uuid, spawned);
+                relationships.apply(spawned.entity, spawned.relationships);
+                drawingEntities.set(uuid, spawned.entity);
+                relationships.flush(uuid);
+                if (isChunkedDrawing(drawing) && activeClient && activeSignal) {
+                    const chunk = getChunkInfo(drawing);
+                    if (chunk) {
+                        spawned.entity.add(traits.ChunkProgress({ loaded: chunk.firstEnd, total: chunk.total }));
+                        const uuidBytes = drawing.uuid ?? new Uint8Array();
+                        void pullChunks(activeClient, uuid, uuidBytes, spawned.entity, chunk.total, chunk.firstEnd, activeSignal);
+                    }
+                }
             }
         }
         else if (changeType === EntityChangeType.REMOVED) {
@@ -92,12 +175,18 @@ export function provideDrawService() {
         else if (changeType === EntityChangeType.UPDATED) {
             const existing = drawingEntities.get(uuid);
             if (existing) {
-                const next = updateDrawing(world, existing, drawing, traits.DrawServiceAPI);
-                drawingEntities.set(uuid, next);
+                const isModel = drawing.physicalObject?.geometryType?.case === 'model';
+                const result = isModel
+                    ? updateModel(world, existing, drawing, traits.DrawServiceAPI)
+                    : updateDrawing(world, existing, drawing);
+                relationships.apply(result.entity, result.relationships);
+                drawingEntities.set(uuid, result.entity);
             }
             else {
                 const spawned = drawDrawing(world, drawing, traits.DrawServiceAPI);
-                drawingEntities.set(uuid, spawned);
+                relationships.apply(spawned.entity, spawned.relationships);
+                drawingEntities.set(uuid, spawned.entity);
+                relationships.flush(uuid);
             }
         }
     };
@@ -201,38 +290,68 @@ export function provideDrawService() {
             }
         }
     };
+    const createRelationship = async (sourceUuid, targetUuid, type, indexMapping) => {
+        if (!activeClient)
+            return;
+        const rel = {
+            targetUuid: uuidStringToBytes(targetUuid),
+            type,
+        };
+        if (indexMapping !== undefined) {
+            rel.indexMapping = indexMapping;
+        }
+        await activeClient.createRelationship(new CreateRelationshipRequest({
+            sourceUuid: uuidStringToBytes(sourceUuid),
+            relationship: rel,
+        }));
+    };
+    const deleteRelationship = async (sourceUuid, targetUuid) => {
+        if (!activeClient)
+            return;
+        await activeClient.deleteRelationship(new DeleteRelationshipRequest({
+            sourceUuid: uuidStringToBytes(sourceUuid),
+            targetUuid: uuidStringToBytes(targetUuid),
+        }));
+    };
     $effect(() => {
         if (!url) {
             connectionStatus = ConnectionStatus.DISCONNECTED;
+            activeClient = undefined;
             return;
         }
         const controller = new AbortController();
         connectionStatus = ConnectionStatus.CONNECTING;
         const transport = createConnectTransport({ baseUrl: url });
         const client = createClient(DrawService, transport);
+        activeClient = client;
+        activeSignal = controller.signal;
         void streamEntityChanges(client, controller.signal);
         void streamSceneChanges(client, controller.signal);
         return () => {
             controller.abort();
+            activeClient = undefined;
+            activeSignal = undefined;
             connectionStatus = ConnectionStatus.DISCONNECTED;
+            activeClient = undefined;
             for (const entity of transformEntities.values()) {
                 if (world.has(entity))
                     entity.destroy();
             }
             transformEntities.clear();
-            for (const entities of drawingEntities.values()) {
-                for (const entity of entities) {
-                    if (world.has(entity))
-                        entity.destroy();
-                }
+            for (const entity of drawingEntities.values()) {
+                if (world.has(entity))
+                    entity.destroy();
             }
             drawingEntities.clear();
+            relationships.clear();
         };
     });
     setContext(DRAW_SERVICE_KEY, {
         get connectionStatus() {
             return connectionStatus;
         },
+        createRelationship,
+        deleteRelationship,
     });
 }
 export function useDrawService() {

package/dist/hooks/useFrameEditSession.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { Entity } from 'koota';
+import { FrameEditSession } from '../editing/FrameEditSession';
+interface FrameEditSessionContext {
+    /** The currently-active session, or undefined when no gesture is in flight. */
+    current: FrameEditSession | undefined;
+    /**
+     * Open a new session over the given entities. If a previous session is still
+     * active (e.g. selection changed mid-drag and onMouseUp never fired), it is
+     * aborted first so its snapshot is restored.
+     */
+    begin: (entities: Entity[]) => FrameEditSession;
+}
+export declare const provideFrameEditSession: (partID: () => string) => void;
+export declare const useFrameEditSession: () => FrameEditSessionContext;
+export {};

package/dist/hooks/useFrameEditSession.svelte.js

@@ -0,0 +1,36 @@
+import { getContext, setContext } from 'svelte';
+import { FrameEditSession } from '../editing/FrameEditSession';
+import { usePartConfig } from './usePartConfig.svelte';
+const key = Symbol('frame-edit-session-context');
+export const provideFrameEditSession = (partID) => {
+    const partConfig = usePartConfig();
+    let active = $state(undefined);
+    const begin = (entities) => {
+        active?.abort();
+        const session = new FrameEditSession(entities, partConfig.updateFrame, partConfig.deleteFrame, () => {
+            if (active === session)
+                active = undefined;
+        });
+        active = session;
+        return session;
+    };
+    // Drop any in-flight session when the partID changes — its snapshots reference
+    // entities from the old world that useFrames will destroy, and aborting it
+    // after the swap would write old frame names into the new part's config.
+    let lastPartID;
+    $effect.pre(() => {
+        const id = partID();
+        if (lastPartID !== undefined && lastPartID !== id) {
+            active?.abort();
+            active = undefined;
+        }
+        lastPartID = id;
+    });
+    setContext(key, {
+        get current() {
+            return active;
+        },
+        begin,
+    });
+};
+export const useFrameEditSession = () => getContext(key);

package/dist/hooks/useFrames.svelte.js

@@ -7,6 +7,7 @@ import { traits, useWorld } from '../ecs';
 import { createPose } from '../transform';
 import { useConfigFrames } from './useConfigFrames.svelte';
 import { useEnvironment } from './useEnvironment.svelte';
+import { useFrameEditSession } from './useFrameEditSession.svelte';
 import { useLogs } from './useLogs.svelte';
 import { usePartConfig } from './usePartConfig.svelte';
 import { useResourceByName } from './useResourceByName.svelte';
@@ -14,6 +15,7 @@ const key = Symbol('frames-context');
 export const provideFrames = (partID) => {
     const configFrames = useConfigFrames();
     const partConfig = usePartConfig();
+    const editSession = useFrameEditSession();
     const environment = useEnvironment();
     const world = useWorld();
     const resourceByName = useResourceByName();
@@ -23,6 +25,16 @@ export const provideFrames = (partID) => {
     const logs = useLogs();
     const pendingSaveKey = $derived(`viam-pending-save-revision:${partID()}`);
     let didRecentlyEdit = $state(false);
+    let lastPartID;
+    $effect.pre(() => {
+        const id = partID();
+        if (lastPartID !== undefined && lastPartID !== id) {
+            // Stale across parts: keeps the configFrames-priority merge branch
+            // active when switching to a new part that hasn't been edited.
+            didRecentlyEdit = false;
+        }
+        lastPartID = id;
+    });
     const isEditMode = $derived(environment.current.viewerMode === 'edit');
     const query = createRobotQuery(client, 'frameSystemConfig', () => ({
         refetchOnWindowFocus: false,
@@ -73,7 +85,7 @@ export const provideFrames = (partID) => {
     });
     const current = $derived(Object.values(frames));
     const entities = new Map();
-    $effect.pre(() => {
+    $effect(() => {
         if (revision) {
             untrack(() => query.refetch());
         }
@@ -145,6 +157,13 @@ export const provideFrames = (partID) => {
                     subtypeToColor(currentComponentSubtypeByName[frame.referenceFrame]);
                 const existing = entities.get(entityKey);
                 if (existing) {
+                    // Active edit session owns the entity's traits for the duration of
+                    // the user's gesture. Skip the entire re-sync — re-setting Parent
+                    // would re-evaluate the <Portal> id and re-mount the group,
+                    // detaching the gizmo's drag target mid-stroke.
+                    if (editSession.current?.owns(existing)) {
+                        continue;
+                    }
                     traits.setParentTrait(existing, parent);
                     if (color) {
                         existing.set(traits.Color, color);
@@ -153,14 +172,30 @@ export const provideFrames = (partID) => {
                         existing.set(traits.Center, center);
                     }
                     traits.updateGeometryTrait(existing, frame.physicalObject);
-                    existing.set(traits.EditedPose, pose);
+                    if (!isEditMode && !partConfig.hasPendingSave) {
+                        existing.set(traits.Pose, pose);
+                    }
+                    if (!existing.has(traits.LivePose)) {
+                        existing.add(traits.LivePose(pose));
+                    }
+                    // Skip the EditedPose overwrite while in edit mode. The merged
+                    // `frames` source can differ from query.data once didRecentlyEdit
+                    // flips (fragment overrides, round-trip drift), and writing those
+                    // values would shift entities whose parents the user is portaling
+                    // into — the gizmo's drag target moves underneath it. Once we're
+                    // back in monitor mode, the next sync resumes the overwrite.
+                    if (!isEditMode) {
+                        existing.set(traits.EditedPose, pose);
+                    }
                     continue;
                 }
                 const entityTraits = [
                     traits.Name(name),
                     traits.Pose(pose),
                     traits.EditedPose(pose),
+                    traits.LivePose(pose),
                     traits.FramesAPI,
+                    traits.Transformable,
                     traits.ShowAxesHelper,
                     ...traits.getParentTrait(parent),
                 ];

package/dist/hooks/usePartConfig.svelte.js

@@ -273,7 +273,17 @@ const useStandalonePartConfig = (partID) => {
         }
         return results;
     });
+    let lastPartID;
     $effect.pre(() => {
+        const id = partID();
+        if (lastPartID !== undefined && lastPartID !== id) {
+            // Part changed: drop any in-memory edits/pending-save state from the
+            // previous part. `current` is left for the existing sync below to
+            // repopulate once the new part's networkPartConfig arrives.
+            isDirty = false;
+            hasPendingSave = false;
+        }
+        lastPartID = id;
         if (!networkPartConfig || isDirty) {
             return;
         }

package/dist/hooks/useRelationships.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { Entity } from 'koota';
+import type { Relationship } from '../metadata';
+export declare const provideRelationships: () => {
+    apply(entity: Entity, relationships: Relationship[] | undefined): void;
+    flush(targetUuid: string): void;
+    clear(): void;
+};
+export declare const useRelationships: () => {
+    apply(entity: Entity, relationships: Relationship[] | undefined): void;
+    flush(targetUuid: string): void;
+    clear(): void;
+};

package/dist/hooks/useRelationships.svelte.js

@@ -0,0 +1,78 @@
+import { getContext, setContext } from 'svelte';
+import { uuidBytesToString } from '../draw';
+import { relations, traits, useQuery } from '../ecs';
+const RELATIONSHIPS_CONTEXT_KEY = Symbol('relationships');
+export const provideRelationships = () => {
+    const uuids = useQuery(traits.UUID);
+    const pending = new Map();
+    const addPending = (targetUuid, relationship) => {
+        const next = pending.get(targetUuid) ?? [];
+        next.push(relationship);
+        pending.set(targetUuid, next);
+    };
+    return setContext(RELATIONSHIPS_CONTEXT_KEY, {
+        apply(entity, relationships) {
+            const desired = relationships ?? [];
+            const currentTargets = entity.targetsFor(relations.SubEntityLink);
+            const desiredByUuid = new Map();
+            for (const rel of desired) {
+                const targetUUID = uuidBytesToString(rel.targetUuid);
+                if (!targetUUID)
+                    continue;
+                desiredByUuid.set(targetUUID, rel);
+            }
+            for (const target of currentTargets) {
+                if (!target.isAlive())
+                    continue;
+                const targetUuid = target.get(traits.UUID);
+                if (!targetUuid || !desiredByUuid.has(targetUuid)) {
+                    entity.remove(relations.SubEntityLink(target));
+                }
+            }
+            for (const [uuid, relationship] of desiredByUuid) {
+                const targetEntity = uuids.current.find((e) => e.get(traits.UUID) === uuid);
+                if (!targetEntity) {
+                    addPending(uuid, {
+                        entity: entity,
+                        type: relationship.type,
+                        indexMapping: relationship.indexMapping,
+                    });
+                    continue;
+                }
+                const existing = entity.get(relations.SubEntityLink(targetEntity));
+                if (existing &&
+                    existing.type === relationship.type &&
+                    existing.indexMapping === (relationship.indexMapping ?? 'index')) {
+                    continue;
+                }
+                entity.add(relations.SubEntityLink(targetEntity, {
+                    type: relationship.type,
+                    indexMapping: relationship.indexMapping ?? 'index',
+                }));
+            }
+        },
+        flush(targetUuid) {
+            const relationship = pending.get(targetUuid);
+            if (!relationship)
+                return;
+            pending.delete(targetUuid);
+            const targetEntity = uuids.current.find((e) => e.get(traits.UUID) === targetUuid);
+            if (!targetEntity)
+                return;
+            for (const { entity, type, indexMapping } of relationship) {
+                if (!entity.isAlive())
+                    continue;
+                entity.add(relations.SubEntityLink(targetEntity, {
+                    type,
+                    indexMapping: indexMapping ?? 'index',
+                }));
+            }
+        },
+        clear() {
+            pending.clear();
+        },
+    });
+};
+export const useRelationships = () => {
+    return getContext(RELATIONSHIPS_CONTEXT_KEY);
+};

package/dist/hooks/useSettings.svelte.d.ts

@@ -9,9 +9,8 @@ export interface Settings {
     };
     disabledCameras: Record<string, boolean>;
     disabledVisionServices: Record<string, boolean>;
-    transforming: boolean;
     snapping: boolean;
-    transformMode: 'translate' | 'rotate' | 'scale';
+    transformMode: 'none' | 'translate' | 'rotate' | 'scale';
     grid: boolean;
     gridCellSize: number;
     gridSectionSize: number;

package/dist/hooks/useSettings.svelte.js

@@ -15,9 +15,8 @@ const defaults = () => ({
     },
     disabledCameras: {},
     disabledVisionServices: {},
-    transforming: false,
     snapping: false,
-    transformMode: 'translate',
+    transformMode: 'none',
     grid: true,
     gridCellSize: 0.5,
     gridSectionSize: 10,

package/dist/hooks/useWorldState.svelte.js

@@ -9,6 +9,7 @@ import { isPointCloud } from '../geometry';
 import { metadataFromStruct } from '../metadata';
 import { createPose } from '../transform';
 import { usePartID } from './usePartID.svelte';
+import { useRelationships } from './useRelationships.svelte';
 export const provideWorldStates = () => {
     const partID = usePartID();
     const resourceNames = useResourceNames(() => partID.current, 'world_state_store');
@@ -83,6 +84,7 @@ const decodeWorldStateChunk = (response, fallbackStart) => {
 const createWorldState = (client) => {
     const { invalidate } = useThrelte();
     const world = useWorld();
+    const relationships = useRelationships();
     const entities = new Map();
     const chunkLoader = createChunkLoader({
         world,
@@ -105,10 +107,12 @@ const createWorldState = (client) => {
         if (entities.has(transform.uuidString)) {
             return;
         }
-        const entity = drawTransform(world, transform, traits.WorldStateStoreAPI, { removable: false });
-        entities.set(transform.uuidString, entity);
+        const spawned = drawTransform(world, transform, traits.WorldStateStoreAPI, { removable: false });
+        entities.set(transform.uuidString, spawned.entity);
+        relationships.apply(spawned.entity, spawned.relationships);
         const parsedMetadata = metadataFromStruct(transform.metadata?.fields);
-        chunkLoader.start(transform.uuidString, entity, parsedMetadata);
+        chunkLoader.start(transform.uuidString, spawned.entity, parsedMetadata);
+        relationships.flush(transform.uuidString);
         if (isPointCloud(transform.physicalObject?.geometryType))
             invalidate();
     };
@@ -140,9 +144,11 @@ const createWorldState = (client) => {
             }
         }
         if (metadataDirty) {
-            updateMetadata(entity, metadataFromStruct(transform.metadata?.fields), {
+            const parsedMetadata = metadataFromStruct(transform.metadata?.fields);
+            updateMetadata(entity, parsedMetadata, {
                 pointCloud: isPointCloud(transform.physicalObject?.geometryType),
             });
+            relationships.apply(entity, parsedMetadata.relationships);
         }
     };
     let initialized = false;

package/dist/metadata.d.ts

@@ -1,7 +1,11 @@
 import type { PlainMessage, Struct } from '@viamrobotics/sdk';
-import { Metadata as MetadataProto } from './buf/draw/v1/metadata_pb';
-/** Metadata for a `Drawing` or `Transform`. */
-export type Metadata = PlainMessage<MetadataProto>;
+import { Metadata as MetadataProto, type Relationship as RelationshipProto } from './buf/draw/v1/metadata_pb';
+/** Metadata for a `Drawing` or `Transform`. Relationships default to empty. */
+export type Metadata = Omit<PlainMessage<MetadataProto>, 'relationships'> & {
+    relationships?: PlainMessage<MetadataProto>['relationships'];
+};
+/** Plain-object representation of a Relationship, usable outside proto classes. */
+export type Relationship = PlainMessage<RelationshipProto>;
 /** Type guard that checks whether a string is a recognised metadata wire key. */
 export declare const isMetadataField: (key: string) => boolean;
 /**

package/dist/metadata.js

@@ -1,4 +1,4 @@
-import { ColorFormat, Metadata as MetadataProto } from './buf/draw/v1/metadata_pb';
+import { ColorFormat, Metadata as MetadataProto, } from './buf/draw/v1/metadata_pb';
 /** Type guard that checks whether a string is a recognised metadata wire key. */
 export const isMetadataField = (key) => {
     return (key === 'colors' ||
@@ -6,7 +6,8 @@ export const isMetadataField = (key) => {
         key === 'opacities' ||
         key === 'show_axes_helper' ||
         key === 'invisible' ||
-        key === 'chunks');
+        key === 'chunks' ||
+        key === 'relationships');
 };
 /**
  * Extracts typed {@link Metadata} from a proto `Struct` fields map.
@@ -77,6 +78,29 @@ export const metadataFromStruct = (fields = {}) => {
                 }
                 break;
             }
+            case 'relationships': {
+                if (Array.isArray(unwrappedValue)) {
+                    json.relationships = unwrappedValue
+                        .filter((item) => typeof item === 'object' && item !== null)
+                        .map((item) => {
+                        const targetUuidStr = item['target_uuid'];
+                        let targetUuid = new Uint8Array();
+                        if (typeof targetUuidStr === 'string' && targetUuidStr.length > 0) {
+                            const binary = atob(targetUuidStr);
+                            targetUuid = new Uint8Array(binary.length);
+                            for (let i = 0; i < binary.length; i++) {
+                                targetUuid[i] = binary.charCodeAt(i);
+                            }
+                        }
+                        return {
+                            targetUuid,
+                            type: typeof item['type'] === 'string' ? item['type'] : '',
+                            indexMapping: typeof item['index_mapping'] === 'string' ? item['index_mapping'] : undefined,
+                        };
+                    });
+                }
+                break;
+            }
         }
     }
     return json;

package/dist/snapshot.d.ts

@@ -2,6 +2,11 @@ import type { Entity, World } from 'koota';
 import type { Snapshot } from './buf/draw/v1/snapshot_pb';
 import type { Settings } from './hooks/useSettings.svelte';
 import { type SceneMetadata } from './buf/draw/v1/scene_pb';
+import type { Relationship } from './metadata';
+export type SnapshotEntity = {
+    entity: Entity;
+    relationships: Relationship[] | undefined;
+};
 /**
  * Merges scene-level metadata (grid, camera, point/line settings) into the
  * current viewer settings. Millimeter values from the proto are converted
@@ -18,4 +23,4 @@ export declare const applySceneMetadata: (settings: Settings, metadata: SceneMet
  *
  * @returns The spawned entities
  */
-export declare const spawnSnapshotEntities: (world: World, snapshot: Snapshot) => Entity[];
+export declare const spawnSnapshotEntities: (world: World, snapshot: Snapshot) => SnapshotEntity[];