@viamrobotics/motion-tools 1.19.1 → 1.21.0

package/dist/draw.d.ts

@@ -2,18 +2,31 @@ import type { TransformWithUUID } from '@viamrobotics/sdk';
 import type { Entity, Trait, World } from 'koota';
 import type { Transform as TransformProto } from './buf/common/v1/common_pb';
 import type { Drawing } from './buf/draw/v1/drawing_pb';
+import type { Relationship } from './metadata';
 import { type Metadata } from './metadata';
 export type Transform = TransformWithUUID | TransformProto;
-type Options = {
+export declare const uuidBytesToString: (bytes: Uint8Array | undefined) => string | undefined;
+export declare const uuidStringToBytes: (uuid: string) => Uint8Array<ArrayBuffer>;
+interface DrawOptions {
     removable?: boolean;
+}
+export declare const drawTransform: (world: World, { referenceFrame, poseInObserverFrame, physicalObject, metadata, uuid }: Transform, api: Trait, { removable }?: DrawOptions) => {
+    entity: Entity;
+    relationships: import("@bufbuild/protobuf").PlainMessage<import("./buf/draw/v1/metadata_pb").Relationship>[] | undefined;
 };
-export declare const drawTransform: (world: World, { referenceFrame, poseInObserverFrame, physicalObject, metadata }: Transform, api: Trait, options?: Options) => Entity;
-export declare const drawDrawing: (world: World, drawing: Drawing, api: Trait, options?: Options) => Entity[];
-export declare const updateTransform: (entity: Entity, { poseInObserverFrame, physicalObject, metadata }: Transform, options?: Options) => void;
-export declare const updateMetadata: (entity: Entity, metadata: Metadata, { pointCloud }?: {
+export interface DrawingResult {
+    entity: Entity;
+    relationships: Relationship[] | undefined;
+}
+export declare const drawDrawing: (world: World, drawing: Drawing, api: Trait, { removable }?: DrawOptions) => DrawingResult;
+export declare const updateTransform: (entity: Entity, { poseInObserverFrame, physicalObject, metadata }: Transform, { removable }?: DrawOptions) => {
+    entity: Entity;
+    relationships: import("@bufbuild/protobuf").PlainMessage<import("./buf/draw/v1/metadata_pb").Relationship>[] | undefined;
+};
+interface MetadataOptions {
     pointCloud?: boolean;
-}) => void;
-export declare const updateDrawing: (world: World, entities: Entity[], drawing: Drawing, api: Trait, options?: Options) => Entity[];
-export declare const addColorTraits: (entity: Entity, colors: Uint8Array) => void;
-export declare const setColorTraits: (entity: Entity, colors: Uint8Array) => void;
+}
+export declare const updateMetadata: (entity: Entity, metadata: Metadata, { pointCloud }?: MetadataOptions) => void;
+export declare const updateDrawing: (world: World, entity: Entity, drawing: Drawing, { removable }?: DrawOptions) => DrawingResult;
+export declare const updateModel: (world: World, entity: Entity, drawing: Drawing, api: Trait, { removable }?: DrawOptions) => DrawingResult;
 export {};

package/dist/draw.js

@@ -1,8 +1,9 @@
 import { Vector3, Vector4 } from 'three';
 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 { traits } from './ecs';
+import { relations, traits } from './ecs';
 import { parsePcdInWorker } from './loaders/pcd';
 import { metadataFromStruct } from './metadata';
 import { createPose } from './transform';
@@ -21,12 +22,28 @@ const DEFAULT_LINE_DOT_COLORS = new Uint8Array([0, 0, 139]);
 const DEFAULT_POINTS_COLORS = new Uint8Array([51, 51, 51]);
 const DEFAULT_NURBS_COLORS = new Uint8Array([0, 255, 255]);
 const DEFAULT_OPACITY = 1;
-export const drawTransform = (world, { referenceFrame, poseInObserverFrame, physicalObject, metadata }, api, options = { removable: true }) => {
+export const uuidBytesToString = (bytes) => {
+    if (!bytes || bytes.length === 0)
+        return undefined;
+    return UuidTool.toString([...bytes]);
+};
+export const uuidStringToBytes = (uuid) => {
+    const arr = new Uint8Array(16);
+    arr.set(UuidTool.toBytes(uuid));
+    return arr;
+};
+const isModel = (drawing) => {
+    return drawing.physicalObject?.geometryType?.case === 'model';
+};
+export const drawTransform = (world, { referenceFrame, poseInObserverFrame, physicalObject, metadata, uuid }, api, { removable = true } = {}) => {
     const entityTraits = [
         traits.Name(referenceFrame),
         traits.Pose(createPose(poseInObserverFrame?.pose)),
         api,
     ];
+    const uuidStr = uuidBytesToString(uuid);
+    if (uuidStr)
+        entityTraits.push(traits.UUID(uuidStr));
     if (physicalObject) {
         entityTraits.push(traits.Geometry(physicalObject));
         const center = physicalObject.center;
@@ -36,7 +53,7 @@ export const drawTransform = (world, { referenceFrame, poseInObserverFrame, phys
     else {
         entityTraits.push(traits.ReferenceFrame);
     }
-    if (options.removable)
+    if (removable)
         entityTraits.push(traits.Removable);
     entityTraits.push(...traits.getParentTrait(poseInObserverFrame?.referenceFrame));
     const parsedMetadata = metadataFromStruct(metadata?.fields);
@@ -60,23 +77,28 @@ export const drawTransform = (world, { referenceFrame, poseInObserverFrame, phys
     const entity = world.spawn(...entityTraits);
     if (pointCloud)
         parsePointCloud(world, entity, pointCloud, parsedMetadata);
-    return entity;
+    return { entity, relationships: parsedMetadata.relationships };
 };
-export const drawDrawing = (world, drawing, api, options = { removable: true }) => {
-    const { referenceFrame, poseInObserverFrame, physicalObject, metadata } = drawing;
-    if (physicalObject?.geometryType?.case === 'model')
-        return drawModel(world, drawing, api, options);
-    const entity = world.spawn(traits.Name(referenceFrame), traits.Pose(createPose(poseInObserverFrame?.pose)), api, ...traits.getParentTrait(poseInObserverFrame?.referenceFrame));
-    if (options.removable)
+export const drawDrawing = (world, drawing, api, { removable = true } = {}) => {
+    const { referenceFrame, poseInObserverFrame, metadata, uuid } = drawing;
+    if (isModel(drawing)) {
+        return drawModel(world, drawing, api, { removable });
+    }
+    const uuidTraits = [];
+    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);
+    if (removable)
         entity.add(traits.Removable);
     if (metadata?.showAxesHelper)
         entity.add(traits.ShowAxesHelper);
     if (metadata?.invisible)
         entity.add(traits.Invisible);
     applyShape(entity, drawing);
-    return [entity];
+    return { entity, relationships: metadata?.relationships };
 };
-export const updateTransform = (entity, { poseInObserverFrame, physicalObject, metadata }, options = { removable: true }) => {
+export const updateTransform = (entity, { poseInObserverFrame, physicalObject, metadata }, { removable = true } = {}) => {
     entity.set(traits.Pose, createPose(poseInObserverFrame?.pose));
     traits.setParentTrait(entity, poseInObserverFrame?.referenceFrame);
     if (physicalObject) {
@@ -89,13 +111,15 @@ export const updateTransform = (entity, { poseInObserverFrame, physicalObject, m
             entity.remove(traits.Center);
         }
     }
-    updateMetadata(entity, metadataFromStruct(metadata?.fields), {
+    const parsedMetadata = metadataFromStruct(metadata?.fields);
+    updateMetadata(entity, parsedMetadata, {
         pointCloud: isPointCloud(physicalObject?.geometryType),
     });
-    if (options.removable)
+    if (removable)
         entity.add(traits.Removable);
-    if (!options.removable)
+    if (!removable)
         entity.remove(traits.Removable);
+    return { entity, relationships: parsedMetadata.relationships };
 };
 export const updateMetadata = (entity, metadata, { pointCloud = false } = {}) => {
     if (metadata.showAxesHelper)
@@ -116,20 +140,10 @@ export const updateMetadata = (entity, metadata, { pointCloud = false } = {}) =>
     }
     entity.set(traits.Opacity, asOpacity(opacities, DEFAULT_OPACITY));
 };
-export const updateDrawing = (world, entities, drawing, api, options = { removable: true }) => {
-    const { poseInObserverFrame, physicalObject, metadata } = drawing;
-    if (physicalObject?.geometryType?.case === 'model') {
-        for (const entity of entities) {
-            if (world.has(entity))
-                entity.destroy();
-        }
-        return drawDrawing(world, drawing, api, options);
-    }
-    if (entities.length === 0)
-        return entities;
-    const entity = entities[0];
+export const updateDrawing = (world, entity, drawing, { removable = true } = {}) => {
+    const { poseInObserverFrame, metadata } = drawing;
     if (!world.has(entity))
-        return entities;
+        return { entity, relationships: metadata?.relationships };
     entity.set(traits.Pose, createPose(poseInObserverFrame?.pose));
     traits.setParentTrait(entity, poseInObserverFrame?.referenceFrame);
     if (metadata?.showAxesHelper)
@@ -140,8 +154,17 @@ export const updateDrawing = (world, entities, drawing, api, options = { removab
         entity.add(traits.Invisible);
     if (!metadata?.invisible)
         entity.remove(traits.Invisible);
+    if (removable)
+        entity.add(traits.Removable);
+    if (!removable)
+        entity.remove(traits.Removable);
     updateShape(entity, drawing);
-    return entities;
+    return { entity, relationships: metadata?.relationships };
+};
+export const updateModel = (world, entity, drawing, api, { removable = true } = {}) => {
+    if (world.has(entity))
+        entity.destroy();
+    return drawDrawing(world, drawing, api, { removable });
 };
 const applyShape = (entity, { physicalObject, metadata }) => {
     const colors = metadata?.colors;
@@ -242,32 +265,39 @@ const applyShape = (entity, { physicalObject, metadata }) => {
         }
     }
 };
-const drawModel = (world, { referenceFrame, poseInObserverFrame, physicalObject, metadata }, api, { removable = true }) => {
-    const entities = [];
-    const geometryType = physicalObject?.geometryType;
-    if (geometryType?.case !== 'model')
-        return entities;
+const drawModel = (world, model, api, { removable = true }) => {
+    const { referenceFrame, physicalObject, poseInObserverFrame, metadata, uuid } = model;
+    const { animationName, assets, scale } = physicalObject.geometryType.value;
     const baseTraits = [
         traits.Name(referenceFrame),
         traits.Pose(createPose(poseInObserverFrame?.pose)),
         api,
         ...traits.getParentTrait(poseInObserverFrame?.referenceFrame),
     ];
+    const uuidStr = uuidBytesToString(uuid);
+    if (uuidStr)
+        baseTraits.push(traits.UUID(uuidStr));
     if (removable)
         baseTraits.push(traits.Removable);
     if (metadata?.invisible)
         baseTraits.push(traits.Invisible);
-    entities.push(world.spawn(...baseTraits, traits.ReferenceFrame));
-    const { scale, animationName } = geometryType.value;
+    if (metadata?.showAxesHelper)
+        baseTraits.push(traits.ShowAxesHelper);
+    const root = world.spawn(...baseTraits, traits.ReferenceFrame);
     let i = 1;
-    for (const asset of geometryType.value.assets) {
+    for (const asset of assets) {
         const subEntityTraits = [
             traits.Name(`${referenceFrame} model ${i++}`),
             traits.Parent(referenceFrame),
+            relations.ChildOf(root),
             api,
         ];
         if (scale)
             subEntityTraits.push(traits.Scale(scale));
+        if (metadata?.invisible)
+            subEntityTraits.push(traits.Invisible);
+        if (metadata?.showAxesHelper)
+            subEntityTraits.push(traits.ShowAxesHelper);
         if (asset.content.case === 'url') {
             subEntityTraits.push(traits.GLTF({
                 source: { url: asset.content.value },
@@ -280,9 +310,9 @@ const drawModel = (world, { referenceFrame, poseInObserverFrame, physicalObject,
                 animationName: animationName ?? DEFAULT_ANIMATION_NAME,
             }));
         }
-        entities.push(world.spawn(...subEntityTraits));
+        world.spawn(...subEntityTraits);
     }
-    return entities;
+    return { entity: root, relationships: metadata?.relationships };
 };
 const parsePointCloud = (world, entity, pointCloud, metadata) => {
     parsePcdInWorker(new Uint8Array(pointCloud)).then((pointcloud) => {
@@ -422,7 +452,7 @@ const updateShape = (entity, { physicalObject, metadata }) => {
         }
     }
 };
-export const addColorTraits = (entity, colors) => {
+const addColorTraits = (entity, colors) => {
     if (isVertexColors(colors)) {
         entity.add(traits.Colors(colors));
     }
@@ -430,7 +460,7 @@ export const addColorTraits = (entity, colors) => {
         entity.add(traits.Color(asRGB(colors, rgb)));
     }
 };
-export const setColorTraits = (entity, colors) => {
+const setColorTraits = (entity, colors) => {
     if (isVertexColors(colors)) {
         if (entity.has(traits.Colors))
             entity.set(traits.Colors, colors);

package/dist/ecs/relations.js

@@ -1,5 +1,5 @@
 import { relation } from 'koota';
-export const ChildOf = relation({ exclusive: true });
+export const ChildOf = relation({ exclusive: true, autoDestroy: 'orphan' });
 export const SubEntityLinkType = {
     HoverLink: 'HoverLink',
 };

package/dist/ecs/traits.d.ts

@@ -4,6 +4,7 @@ import { type ConfigurableTrait, 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>;
 export declare const Pose: import("koota").Trait<{
     x: number;
     y: number;
@@ -77,6 +78,7 @@ export declare const Color: import("koota").Trait<{
  */
 export declare const Material: import("koota").Trait<{
     depthTest: boolean;
+    depthWrite: boolean;
 }>;
 export declare const DepthTest: import("koota").Trait<() => boolean>;
 export declare const Arrow: import("koota").Trait<() => boolean>;

package/dist/ecs/traits.js

@@ -8,6 +8,7 @@ import { parsePcdInWorker } from '../loaders/pcd';
 import { parsePlyInput } from '../ply';
 export const Name = trait(() => '');
 export const Parent = trait(() => 'world');
+export const UUID = 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 Center = trait({ x: 0, y: 0, z: 0, oX: 0, oY: 0, oZ: 1, theta: 0 });
@@ -53,6 +54,7 @@ export const Color = trait({ r: 0, g: 0, b: 0 });
  */
 export const Material = trait({
     depthTest: false,
+    depthWrite: true,
 });
 export const DepthTest = trait(() => true);
 export const Arrow = trait(() => true);

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

@@ -6,6 +6,8 @@ declare const ConnectionStatus: {
 type ConnectionStatusType = (typeof ConnectionStatus)[keyof typeof ConnectionStatus];
 interface Context {
     connectionStatus: ConnectionStatusType;
+    createRelationship: (sourceUuid: string, targetUuid: string, type: string, indexMapping?: string) => Promise<void>;
+    deleteRelationship: (sourceUuid: string, targetUuid: string) => Promise<void>;
 }
 export declare function provideDrawService(): void;
 export declare function useDrawService(): Context;

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/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);
+};