From 1800f468f4d5707c697df45a23e6cbddca26ccf2 Mon Sep 17 00:00:00 2001
From: David-Alexandre Chanel <Lyptik@users.noreply.github.com>
Date: Sat, 3 Oct 2026 15:13:12 +0200
Subject: [PATCH 1/4] feat: expose container UUID

---
 src/data.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/data.ts b/src/data.ts
index 3dd8160..606376b 100644
--- a/src/data.ts
+++ b/src/data.ts
@@ -252,6 +252,8 @@ export class Container {
     public readonly position: Vector3 = [0, 0, 0],
     public readonly rotation: Vector3 = [0, 0, 0],
     public readonly color: Vector4 = [0, 0, 0, 0],
+    /** Stable UUID supplied by the server for setup/update containers. */
+    public readonly uuid = '',
     public readonly parameters?: ContainerSpecificParameters,
     public readonly children: readonly Container[] = []
   ) {}
@@ -268,6 +270,7 @@ export class Container {
   getPosition(): Vector3 { return this.position; }
   getRotation(): Vector3 { return this.rotation; }
   getColor(): Vector4 { return this.color; }
+  getUUID(): string { return this.uuid; }
   getSceneParameters(): SceneParameters {
     if (!this.isScene()) throw new Error('Container is not a scene.');
     return this.parameters as SceneParameters;

From dfdfdc4cfabbacf0b1dc54e826fb93fbcda89093 Mon Sep 17 00:00:00 2001
From: David-Alexandre Chanel <Lyptik@users.noreply.github.com>
Date: Sat, 3 Oct 2026 15:13:17 +0200
Subject: [PATCH 2/4] feat: parse container UUID from control messages

---
 src/control.ts | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/control.ts b/src/control.ts
index 47d9492..2f199b1 100644
--- a/src/control.ts
+++ b/src/control.ts
@@ -36,6 +36,7 @@ function parseContainer(value: unknown): Container {
   const position = vec3(value.position);
   const rotation = vec3(value.rotation);
   const color = vec4(value.color);
+  const uuid = typeof value.uuid === 'string' ? value.uuid : '';
   const rawChildren = Array.isArray(value.children)
     ? value.children
     : isRecord(value.children)
@@ -52,6 +53,7 @@ function parseContainer(value: unknown): Container {
       position,
       rotation,
       color,
+      uuid,
       {},
       children
     );
@@ -93,6 +95,7 @@ function parseContainer(value: unknown): Container {
       position,
       rotation,
       color,
+      uuid,
       new ZoneParameters(shapeType, shapeParameters, localSliderAxis),
       children
     );
@@ -106,13 +109,14 @@ function parseContainer(value: unknown): Container {
       position,
       rotation,
       color,
+      uuid,
       { size: vec3(value.size) },
       children
     );
   }
 
   const type = rawType ? ContainerType.Container : ContainerType.Unknown;
-  return new Container(type, name, address, position, rotation, color, {}, children);
+  return new Container(type, name, address, position, rotation, color, uuid, {}, children);
 }
 
 function parseContainerPayload(value: unknown): Container {

From c5bbce72e38f105e9b53a791a14f5aa2ef015463 Mon Sep 17 00:00:00 2001
From: David-Alexandre Chanel <Lyptik@users.noreply.github.com>
Date: Sat, 3 Oct 2026 15:13:24 +0200
Subject: [PATCH 3/4] test: cover container UUID parsing

---
 tests/sdk.test.mjs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/tests/sdk.test.mjs b/tests/sdk.test.mjs
index 5c3c5b9..c14ecf7 100644
--- a/tests/sdk.test.mjs
+++ b/tests/sdk.test.mjs
@@ -186,6 +186,7 @@ test('Control setup messages expose scene and zone hierarchy', () => {
                 name: 'Zone',
                 type: 'Zone',
                 address: '/world/scene/zone',
+                uuid: 'zone-uuid-123',
                 position: [1, 2, 3],
                 rotation: [0, 45, 0],
                 localSliderAxis: 'z',
@@ -207,6 +208,7 @@ test('Control setup messages expose scene and zone hierarchy', () => {
   assert.deepEqual(scene.getSceneParameters().size, [10, 3, 8]);
   const zone = scene.getChildren()[0];
   assert.equal(zone.getType(), ContainerType.Zone);
+  assert.equal(zone.getUUID(), 'zone-uuid-123');
   assert.equal(zone.getZoneParameters().getShapeType(), ShapeType.Box);
   assert.equal(zone.getZoneParameters().getLocalSliderAxis(), 'z');
   assert.deepEqual(zone.getZoneParameters().getBoxShapeParameters().size, [2, 1, 4]);

From de30d5fb2b760a729c9887f0aa38b6aabc406ba8 Mon Sep 17 00:00:00 2001
From: David-Alexandre Chanel <Lyptik@users.noreply.github.com>
Date: Sat, 3 Oct 2026 15:13:28 +0200
Subject: [PATCH 4/4] docs: document container UUID

---
 docs/API.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/API.md b/docs/API.md
index 70e150f..07b5287 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -42,7 +42,7 @@ Main methods:
 
 Represents JSON setup/update messages.
 
-A setup message exposes a root `Container`, which can recursively contain scenes, zones and generic containers. Common fields include name, address, position, rotation, color and children.
+A setup message exposes a root `Container`, which can recursively contain scenes, zones and generic containers. Common fields include name, address, UUID, position, rotation, color and children. `getUUID()` exposes the stable server-side container UUID when provided.
 
 Scene containers expose scene size. Zone containers expose the shape information currently provided by Pleiades: Box, Cylinder, Sphere, Path, Grid, Polygon and Segment.