@forgeax/engine-runtime 0.1.27 → 0.1.29

package/src/__tests__/resolve-scene-guids.cases.unit.test.ts

@@ -417,19 +417,16 @@ type __MergedKeep =
     return parsed.value;
   }
 
-  function localId(n: number): LocalEntityId {
-    return n as LocalEntityId;
-  }
-
-  /** Build a minimal SceneAsset suitable for _resolveSceneGuids testing. */
+  /** Build a minimal keyed SceneAsset suitable for _resolveSceneGuids testing. */
   function buildTestAsset(
     nodes: Array<{ localId: number; components: Record<string, Record<string, unknown>> }>,
   ): SceneAsset {
-    const sceneNodes: SceneEntity[] = nodes.map((n) => ({
-      localId: localId(n.localId),
-      components: n.components,
-    }));
-    return { kind: 'scene', entities: sceneNodes };
+    return {
+      kind: 'scene',
+      entities: Object.fromEntries(
+        nodes.map((n) => [`entity-${n.localId}`, { components: n.components }]),
+      ),
+    };
   }
 
   describe('w4 - _resolveSceneGuids success path', () => {
@@ -503,9 +500,9 @@ type __MergedKeep =
       if (!result.ok) return;
       const resolvedAsset = result.value;
       expect(resolvedAsset.kind).toBe('scene');
-      expect(resolvedAsset.entities.length).toBe(1);
+      expect(Object.keys(resolvedAsset.entities).length).toBe(1);
 
-      const resolvedComp = resolvedAsset.entities[0]?.components as Record<
+      const resolvedComp = resolvedAsset.entities['entity-0']?.components as Record<
         string,
         Record<string, unknown>
       >;
@@ -555,7 +552,7 @@ type __MergedKeep =
       expect(result.ok).toBe(true);
       if (!result.ok) return;
       const resolvedAsset = result.value;
-      const resolvedComp = resolvedAsset.entities[0]?.components as Record<
+      const resolvedComp = resolvedAsset.entities['entity-0']?.components as Record<
         string,
         Record<string, unknown>
       >;
@@ -618,10 +615,10 @@ type __MergedKeep =
       if (!result.ok) return;
       const resolvedAsset = result.value;
       const comp0 = (
-        resolvedAsset.entities[0]?.components as Record<string, Record<string, unknown>>
+        resolvedAsset.entities['entity-0']?.components as Record<string, Record<string, unknown>>
       ).MeshFilter;
       const comp1 = (
-        resolvedAsset.entities[1]?.components as Record<string, Record<string, unknown>>
+        resolvedAsset.entities['entity-1']?.components as Record<string, Record<string, unknown>>
       ).MeshFilter;
       expect(comp0?.assetHandle).toBe(comp1?.assetHandle);
       expect(comp0?.assetHandle).toBeTypeOf('number');
@@ -648,7 +645,7 @@ type __MergedKeep =
       if (!result.ok) return;
       const resolvedAsset = result.value;
       const comp = (
-        resolvedAsset.entities[0]?.components as Record<string, Record<string, unknown>>
+        resolvedAsset.entities['entity-0']?.components as Record<string, Record<string, unknown>>
       ).Transform;
       expect(comp).toEqual({ pos: [1, 2, 3] });
     });
@@ -686,7 +683,7 @@ type __MergedKeep =
       expect(e.code).toBe('asset-not-found');
       // Hint must contain the GUID, localId, and field for AI-user debuggability (AC-04)
       expect(e.hint).toContain(UNREGISTERED_GUID_STR);
-      expect(e.hint).toContain('0'); // localId
+      expect(e.hint).toContain('entity-0'); // keyed entity address
       expect(e.hint).toContain('assetHandle');
     });
 
@@ -749,7 +746,7 @@ type __MergedKeep =
       expect(e.code).toBe('asset-not-found');
       // Hint should reference the first failing node (localId=1), not the second
       expect(e.hint).toContain(UNREGISTERED_GUID_STR);
-      expect(e.hint).toContain('1'); // localId of the first failing node
+      expect(e.hint).toContain('entity-1'); // keyed entity address of the first failing node
       // Must NOT contain the second GUID (stopped before reaching it)
       expect(e.hint).not.toContain(SECOND_UNREGISTERED.slice(0, 8)); // prefix match sufficient
     });
@@ -820,7 +817,7 @@ type __MergedKeep =
           {
             guid: MESH_GUID_STR,
             sourceField: { componentName: 'MeshFilter', fieldName: 'assetHandle' },
-            sceneEntityId: 0,
+            sceneEntityKey: 'entity-0',
           },
           {
             guid: MATERIAL_GUID_STR,
@@ -829,7 +826,7 @@ type __MergedKeep =
               fieldName: 'materials',
               arrayIndex: 0,
             },
-            sceneEntityId: 0,
+            sceneEntityKey: 'entity-0',
           },
           {
             guid: MATERIAL2_GUID_STR,
@@ -838,7 +835,7 @@ type __MergedKeep =
               fieldName: 'materials',
               arrayIndex: 1,
             },
-            sceneEntityId: 0,
+            sceneEntityKey: 'entity-0',
           },
           {
             guid: MATERIAL3_GUID_STR,
@@ -847,14 +844,18 @@ type __MergedKeep =
               fieldName: 'materials',
               arrayIndex: 2,
             },
-            sceneEntityId: 0,
+            sceneEntityKey: 'entity-0',
           },
         ];
         reg.catalog(sceneGuid, sceneAsset, refs);
 
         const world = new World();
-        defineComponent('MeshFilter', { assetHandle: 'shared<MeshAsset>' });
-        defineComponent('MeshRenderer', { materials: 'array<shared<MaterialAsset>>' });
+        world.components
+          .register(defineComponent('MeshFilter', { assetHandle: 'shared<MeshAsset>' }))
+          .unwrap();
+        world.components
+          .register(defineComponent('MeshRenderer', { materials: 'array<shared<MaterialAsset>>' }))
+          .unwrap();
 
         // biome-ignore lint/suspicious/noExplicitAny: private helper access
         const internal = reg as any as {
@@ -870,9 +871,9 @@ type __MergedKeep =
         if (!result.ok) return;
         const resolvedAsset = result.value;
         expect(resolvedAsset.kind).toBe('scene');
-        expect(resolvedAsset.entities.length).toBe(1);
+        expect(Object.keys(resolvedAsset.entities).length).toBe(1);
 
-        const resolvedComp = resolvedAsset.entities[0]?.components as Record<
+        const resolvedComp = resolvedAsset.entities['entity-0']?.components as Record<
           string,
           Record<string, unknown>
         >;
@@ -918,7 +919,7 @@ type __MergedKeep =
               fieldName: 'materials',
               arrayIndex: 0,
             },
-            sceneEntityId: 0,
+            sceneEntityKey: 'entity-0',
           },
           {
             guid: MATERIAL2_GUID_STR,
@@ -927,7 +928,7 @@ type __MergedKeep =
               fieldName: 'materials',
               arrayIndex: 1,
             },
-            sceneEntityId: 0,
+            sceneEntityKey: 'entity-0',
           },
           {
             guid: MATERIAL3_GUID_STR,
@@ -936,13 +937,15 @@ type __MergedKeep =
               fieldName: 'materials',
               arrayIndex: 2,
             },
-            sceneEntityId: 0,
+            sceneEntityKey: 'entity-0',
           },
         ];
         reg.catalog(sceneGuid, sceneAsset, refs);
 
         const world = new World();
-        defineComponent('MeshRenderer', { materials: 'array<shared<MaterialAsset>>' });
+        world.components
+          .register(defineComponent('MeshRenderer', { materials: 'array<shared<MaterialAsset>>' }))
+          .unwrap();
 
         // biome-ignore lint/suspicious/noExplicitAny: private helper access
         const internal = reg as any as {
@@ -956,7 +959,7 @@ type __MergedKeep =
 
         expect(result.ok).toBe(true);
         if (!result.ok) return;
-        const resolvedComp = result.value.entities[0]?.components as Record<
+        const resolvedComp = result.value.entities['entity-0']?.components as Record<
           string,
           Record<string, unknown>
         >;
@@ -994,18 +997,20 @@ type __MergedKeep =
           {
             guid: MESH_GUID_STR,
             sourceField: { componentName: 'MeshFilter', fieldName: 'assetHandle' },
-            sceneEntityId: 0,
+            sceneEntityKey: 'entity-0',
           },
           {
             guid: MESH_GUID_STR,
             sourceField: { componentName: 'MeshFilter', fieldName: 'assetHandle' },
-            sceneEntityId: 1,
+            sceneEntityKey: 'entity-1',
           },
         ];
         reg.catalog(sceneGuid, sceneAsset, refs);
 
         const world = new World();
-        defineComponent('MeshFilter', { assetHandle: 'shared<MeshAsset>' });
+        world.components
+          .register(defineComponent('MeshFilter', { assetHandle: 'shared<MeshAsset>' }))
+          .unwrap();
 
         // biome-ignore lint/suspicious/noExplicitAny: private helper access
         const internal = reg as any as {
@@ -1020,17 +1025,17 @@ type __MergedKeep =
         expect(result.ok).toBe(true);
         if (!result.ok) return;
         const comp0 = (
-          result.value.entities[0]?.components as Record<string, Record<string, unknown>>
+          result.value.entities['entity-0']?.components as Record<string, Record<string, unknown>>
         ).MeshFilter;
         const comp1 = (
-          result.value.entities[1]?.components as Record<string, Record<string, unknown>>
+          result.value.entities['entity-1']?.components as Record<string, Record<string, unknown>>
         ).MeshFilter;
         // Same GUID → same handle (one allocSharedRef per unique payload)
         expect(comp0?.assetHandle).toBe(comp1?.assetHandle);
         expect(comp0?.assetHandle).toBeTypeOf('number');
       });
 
-      it('(d) breadcrumb from envelope.refs: buildSceneChildContext returns correct sceneEntityId + componentField', () => {
+      it('(d) breadcrumb from envelope.refs: buildSceneChildContext returns correct sceneEntityKey + componentField', () => {
         const reg = new AssetRegistry(makeMockShaderRegistry());
 
         registerAsset(reg, MESH_GUID_STR, makeTestMesh());
@@ -1048,7 +1053,7 @@ type __MergedKeep =
           {
             guid: MESH_GUID_STR,
             sourceField: { componentName: 'MeshFilter', fieldName: 'assetHandle' },
-            sceneEntityId: 5,
+            sceneEntityKey: 'entity-5',
           },
         ];
         reg.catalog(sceneGuid, sceneAsset, refs);
@@ -1056,7 +1061,7 @@ type __MergedKeep =
         const ctx = buildSceneChildContext(reg, sceneAsset, MESH_GUID_STR.toLowerCase());
 
         expect(ctx).toBeDefined();
-        expect(ctx?.sceneEntityId).toBe(5);
+        expect(ctx?.sceneEntityKey).toBe('entity-5');
         expect(ctx?.componentField).toBe('MeshFilter.assetHandle');
       });
 
@@ -1093,17 +1098,17 @@ type __MergedKeep =
               fieldName: 'materials',
               arrayIndex: 0,
             },
-            sceneEntityId: 0,
+            sceneEntityKey: 'entity-0',
           },
           {
             guid: TEXTURE_GUID_STR,
             // sourceField intentionally omitted — texture edge, D-2
-            sceneEntityId: undefined,
+            sceneEntityKey: undefined,
           },
         ];
         reg.catalog(sceneGuid, sceneAsset, refs);
 
-        // Look up the material GUID — should find sceneEntityId + componentField
+        // Look up the material GUID — should find sceneEntityKey + componentField
         const materialCtx = buildSceneChildContext(
           reg,
           sceneAsset,
@@ -1115,7 +1120,7 @@ type __MergedKeep =
         // Look up the texture GUID — sourceField=undefined → componentField undefined
         const textureCtx = buildSceneChildContext(reg, sceneAsset, TEXTURE_GUID_STR.toLowerCase());
         expect(textureCtx).toBeDefined();
-        expect(textureCtx?.sceneEntityId).toBeUndefined();
+        expect(textureCtx?.sceneEntityKey).toBeUndefined();
         expect(textureCtx?.componentField).toBeUndefined();
       });
     });

package/src/__tests__/rhi-null-command-flow.unit.test.ts

@@ -1,5 +1,5 @@
 import { World } from '@forgeax/engine-ecs';
-import type { Renderer } from '@forgeax/engine-render';
+import type { Renderer, RendererEvent } from '@forgeax/engine-render';
 import { rhi } from '@forgeax/engine-rhi-null';
 import { describe, expect, it } from 'vitest';
 import { requireRenderer } from './renderer-test-utils';
@@ -17,11 +17,7 @@ function frameRequest(lease: Parameters<Renderer['draw']>[0]['leases'][number])
 describe('RhiNull command flow', () => {
   it('returns the synchronous receipt after the host submits a frame', async () => {
     const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
-    const events: Array<{
-      readonly kind: string;
-      readonly frameId?: number;
-      readonly deviceGeneration?: number;
-    }> = [];
+    const events: RendererEvent[] = [];
     const unsubscribe = renderer.subscribe((event) => events.push(event));
     const world = new World();
     const attached = renderer.attach(world);
@@ -32,11 +28,17 @@ describe('RhiNull command flow', () => {
     const frame = renderer.draw(frameRequest(attached.value));
     expect(frame.ok).toBe(true);
     if (!frame.ok) return;
-    expect(events.filter((event) => event.kind === 'frame-submitted')).toEqual([
+    expect(
+      events.filter(
+        (event): event is Extract<RendererEvent, { kind: 'frame-submitted' }> =>
+          event.kind === 'frame-submitted',
+      ),
+    ).toEqual([
       {
         kind: 'frame-submitted',
         frameId: frame.value.frameId,
         deviceGeneration: frame.value.deviceGeneration,
+        receipt: frame.value,
       },
     ]);
     const completed = await frame.value.completed;

package/src/__tests__/roots-to-scene-asset.test.ts

@@ -106,7 +106,7 @@ describe('m2-t1: forest multi-root BFS closure + localId renumbering', () => {
     ]);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
-    expect(result.value.entities).toHaveLength(6);
+    expect(Object.keys(result.value.entities)).toHaveLength(6);
   });
 
   it('ancestor-descendant overlapping roots silently de-duplicate', () => {
@@ -123,7 +123,7 @@ describe('m2-t1: forest multi-root BFS closure + localId renumbering', () => {
     const result = rootsToSceneAsset(reg, world, [e0 as EntityHandle, e1 as EntityHandle]);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
-    expect(result.value.entities).toHaveLength(4);
+    expect(Object.keys(result.value.entities)).toHaveLength(4);
   });
 
   it('localIds are 0..N-1 continuous in BFS order', () => {
@@ -142,10 +142,10 @@ describe('m2-t1: forest multi-root BFS closure + localId renumbering', () => {
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const scene = result.value;
-    expect(scene.entities).toHaveLength(5);
+    expect(Object.keys(scene.entities)).toHaveLength(5);
 
-    const localIds = scene.entities.map((e) => e.localId as unknown as number);
-    expect(localIds).toEqual([0, 1, 2, 3, 4]);
+    const keys = Object.keys(scene.entities);
+    expect(keys).toEqual(['entity-0', 'entity-1', 'entity-2', 'entity-3', 'entity-4']);
   });
 
   it('empty roots produces empty SceneAsset (no error)', () => {
@@ -154,7 +154,7 @@ describe('m2-t1: forest multi-root BFS closure + localId renumbering', () => {
     const result = rootsToSceneAsset(reg, world, []);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
-    expect(result.value.entities).toHaveLength(0);
+    expect(Object.keys(result.value.entities)).toHaveLength(0);
   });
 });
 
@@ -175,15 +175,14 @@ describe('m2-t2: entity / array<entity> -> localId', () => {
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const scene = result.value;
-    expect(scene.entities).toHaveLength(2);
+    expect(Object.keys(scene.entities)).toHaveLength(2);
 
-    const e1 = scene.entities[1];
+    const e1 = scene.entities['entity-1'];
     if (!e1) throw new Error('entity 1 missing');
     const refComps = (e1.components as Record<string, Record<string, unknown>>).Test_EntityRef;
     expect(refComps).toBeDefined();
     if (!refComps) throw new Error('Test_EntityRef missing');
-    expect(refComps.target).toBeTypeOf('number');
-    expect(refComps.target).toBe(0);
+    expect(refComps.target).toBe('entity-0');
   });
 
   it('array<entity> field round-trips each element as localId', () => {
@@ -205,9 +204,9 @@ describe('m2-t2: entity / array<entity> -> localId', () => {
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const scene = result.value;
-    expect(scene.entities).toHaveLength(3);
+    expect(Object.keys(scene.entities)).toHaveLength(3);
 
-    const rootEnt = scene.entities[0];
+    const rootEnt = scene.entities['entity-0'];
     if (!rootEnt) throw new Error('entity 0 missing');
     const elComps = (rootEnt.components as Record<string, Record<string, unknown>>)
       .Test_EntityArray;
@@ -215,7 +214,7 @@ describe('m2-t2: entity / array<entity> -> localId', () => {
     if (!elComps) throw new Error('Test_EntityArray missing');
     const targetsArr = elComps.targets as unknown[];
     expect(Array.isArray(targetsArr)).toBe(true);
-    expect(targetsArr).toEqual([1, 2]);
+    expect(targetsArr).toEqual(['entity-1', 'entity-2']);
   });
 });
 
@@ -248,7 +247,7 @@ describe('m2-t3: shared<> / array<shared<>> -> GUID', () => {
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const scene = result.value;
-    const ent0 = scene.entities[0];
+    const ent0 = scene.entities['entity-0'];
     if (!ent0) throw new Error('entity 0 missing');
     const comps = (ent0.components as Record<string, Record<string, unknown>>).Test_HasShared;
     expect(comps).toBeDefined();
@@ -286,7 +285,7 @@ describe('m2-t3: shared<> / array<shared<>> -> GUID', () => {
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const scene = result.value;
-    const ent0 = scene.entities[0];
+    const ent0 = scene.entities['entity-0'];
     if (!ent0) throw new Error('entity 0 missing');
     const comps = (ent0.components as Record<string, Record<string, unknown>>).Test_HasSharedArray;
     expect(comps).toBeDefined();
@@ -323,7 +322,7 @@ describe('m2-t3: shared<> / array<shared<>> -> GUID', () => {
     const result = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
-    const ent0 = result.value.entities[0];
+    const ent0 = result.value.entities['entity-0'];
     if (!ent0) throw new Error('entity 0 missing');
     const comps = (ent0.components as Record<string, Record<string, unknown>>).Test_EmptyMaterials;
     // An empty shared array serializes to [] (or the component is omitted when it
@@ -390,7 +389,7 @@ describe('m2-t3: shared<> / array<shared<>> -> GUID', () => {
     const result = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
-    const ent0 = result.value.entities[0];
+    const ent0 = result.value.entities['entity-0'];
     if (!ent0) throw new Error('entity 0 missing');
     const comps = (ent0.components as Record<string, Record<string, unknown>>)
       .Test_UnsetScalarShared;
@@ -429,7 +428,7 @@ describe('m2-t3: shared<> / array<shared<>> -> GUID', () => {
     const result = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
-    const ent0 = result.value.entities[0];
+    const ent0 = result.value.entities['entity-0'];
     if (!ent0) throw new Error('entity 0 missing');
     const comps = (ent0.components as Record<string, Record<string, unknown>>)
       .Test_SparseSharedArray;
@@ -460,9 +459,9 @@ describe('m2-t4: root ChildOf strip + cross-root closure refs', () => {
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const scene = result.value;
-    expect(scene.entities).toHaveLength(1);
+    expect(Object.keys(scene.entities)).toHaveLength(1);
 
-    const ent0 = scene.entities[0];
+    const ent0 = scene.entities['entity-0'];
     if (!ent0) throw new Error('entity missing');
     const comps = ent0.components as Record<string, Record<string, unknown>>;
     expect(comps.ChildOf).toBeUndefined();
@@ -481,9 +480,9 @@ describe('m2-t4: root ChildOf strip + cross-root closure refs', () => {
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const scene = result.value;
-    expect(scene.entities).toHaveLength(3);
+    expect(Object.keys(scene.entities)).toHaveLength(3);
 
-    const childEntity = scene.entities.find(
+    const childEntity = Object.values(scene.entities).find(
       (e) =>
         (e.components as Record<string, Record<string, unknown>>).Test_EntityRef?.target !==
         undefined,
@@ -493,9 +492,8 @@ describe('m2-t4: root ChildOf strip + cross-root closure refs', () => {
     const refVal = (childEntity.components as Record<string, Record<string, unknown>>)
       .Test_EntityRef;
     if (!refVal) throw new Error('Test_EntityRef missing');
-    expect(typeof refVal.target).toBe('number');
-    expect(refVal.target as number).toBeGreaterThanOrEqual(0);
-    expect(refVal.target as number).toBeLessThan(3);
+    expect(typeof refVal.target).toBe('string');
+    expect(refVal.target).toBe('entity-2');
   });
 });
 
@@ -639,13 +637,14 @@ describe('w19 — end-to-end round-trip value equivalence (AC-07)', () => {
     // Child (GLB-like) scene + parent scene that mounts it.
     const child: SceneAsset = {
       kind: 'scene',
-      entities: [{ localId: 0 as never, components: { Transform: { pos: [1, 0, 0] } } }],
+      entities: { 'entity-0': { components: { Transform: { pos: [1, 0, 0] } } } },
     };
     reg.catalog(pgc(W19_CHILD), child as Asset);
     const parent: SceneAsset = {
       kind: 'scene',
-      entities: [{ localId: 0 as never, components: { Transform: { pos: [0, 0, 0] } } }],
-      mounts: [{ localId: 1 as never, source: W19_CHILD, memberFirst: 2 as never, memberCount: 1 }],
+      entities: {
+        wrapper: { components: { Transform: { pos: [0, 0, 0] } }, instance: { source: W19_CHILD } },
+      },
     };
     reg.catalog(pgc(W19_PARENT), parent as Asset);
 

package/src/__tests__/roundtrip-primitive.test.ts

@@ -75,9 +75,9 @@ describe('m3-t3(a): individual primitive field round-trip', () => {
     expect(collected.ok).toBe(true);
     if (!collected.ok) return;
     const scene = collected.value;
-    expect(scene.entities).toHaveLength(1);
+    expect(Object.keys(scene.entities)).toHaveLength(1);
 
-    const ent0 = scene.entities[0];
+    const ent0 = scene.entities['entity-0'];
     if (!ent0) throw new Error('entity 0 missing');
     const comps = ent0.components as Record<string, Record<string, unknown>>;
     const cf = comps.Test_RT_F32;
@@ -98,9 +98,9 @@ describe('m3-t3(a): individual primitive field round-trip', () => {
     expect(collected.ok).toBe(true);
     if (!collected.ok) return;
     const scene = collected.value;
-    expect(scene.entities).toHaveLength(1);
+    expect(Object.keys(scene.entities)).toHaveLength(1);
 
-    const ent0 = scene.entities[0];
+    const ent0 = scene.entities['entity-0'];
     if (!ent0) throw new Error('entity 0 missing');
     const comps = ent0.components as Record<string, Record<string, unknown>>;
     const cf = comps.Test_RT_F64;
@@ -122,9 +122,9 @@ describe('m3-t3(a): individual primitive field round-trip', () => {
     expect(collected.ok).toBe(true);
     if (!collected.ok) return;
     const scene = collected.value;
-    expect(scene.entities).toHaveLength(1);
+    expect(Object.keys(scene.entities)).toHaveLength(1);
 
-    const ent0 = scene.entities[0];
+    const ent0 = scene.entities['entity-0'];
     if (!ent0) throw new Error('entity 0 missing');
     const comps = ent0.components as Record<string, Record<string, unknown>>;
     const cf = comps.Test_RT_I32;
@@ -145,9 +145,9 @@ describe('m3-t3(a): individual primitive field round-trip', () => {
     expect(collected.ok).toBe(true);
     if (!collected.ok) return;
     const scene = collected.value;
-    expect(scene.entities).toHaveLength(1);
+    expect(Object.keys(scene.entities)).toHaveLength(1);
 
-    const ent0 = scene.entities[0];
+    const ent0 = scene.entities['entity-0'];
     if (!ent0) throw new Error('entity 0 missing');
     const comps = ent0.components as Record<string, Record<string, unknown>>;
     const cf = comps.Test_RT_U32;
@@ -170,16 +170,18 @@ describe('m3-t3(a): individual primitive field round-trip', () => {
     expect(collected.ok).toBe(true);
     if (!collected.ok) return;
     const scene = collected.value;
-    expect(scene.entities).toHaveLength(2);
+    expect(Object.keys(scene.entities)).toHaveLength(2);
 
-    const comps0 = (scene.entities[0]?.components as Record<string, Record<string, unknown>>)
-      .Test_RT_BOOL;
+    const comps0 = (
+      scene.entities['entity-0']?.components as Record<string, Record<string, unknown>>
+    ).Test_RT_BOOL;
     expect(comps0).toBeDefined();
     if (!comps0) throw new Error('Test_RT_BOOL missing on e0');
     expect(comps0.flag).toBe(true);
 
-    const comps1 = (scene.entities[1]?.components as Record<string, Record<string, unknown>>)
-      .Test_RT_BOOL;
+    const comps1 = (
+      scene.entities['entity-1']?.components as Record<string, Record<string, unknown>>
+    ).Test_RT_BOOL;
     expect(comps1).toBeDefined();
     if (!comps1) throw new Error('Test_RT_BOOL missing on e1');
     expect(comps1.flag).toBe(false);
@@ -197,9 +199,9 @@ describe('m3-t3(a): individual primitive field round-trip', () => {
     expect(collected.ok).toBe(true);
     if (!collected.ok) return;
     const scene = collected.value;
-    expect(scene.entities).toHaveLength(1);
+    expect(Object.keys(scene.entities)).toHaveLength(1);
 
-    const ent0 = scene.entities[0];
+    const ent0 = scene.entities['entity-0'];
     if (!ent0) throw new Error('entity 0 missing');
     const comps = ent0.components as Record<string, Record<string, unknown>>;
     const cf = comps.Test_RT_STR;
@@ -270,10 +272,10 @@ describe('m3-t3(b): mixed entity+shared+primitive round-trip', () => {
     expect(collected.ok).toBe(true);
     if (!collected.ok) return;
     const scene = collected.value;
-    expect(scene.entities).toHaveLength(2);
+    expect(Object.keys(scene.entities)).toHaveLength(2);
 
     // Entity 0 (r0): primitives
-    const ent0 = scene.entities[0];
+    const ent0 = scene.entities['entity-0'];
     if (!ent0) throw new Error('e0 missing');
     const mp = (ent0.components as Record<string, Record<string, unknown>>).Test_RT_MixedPrim;
     expect(mp).toBeDefined();
@@ -286,14 +288,13 @@ describe('m3-t3(b): mixed entity+shared+primitive round-trip', () => {
     expect(mp.name).toBe('mixed-entity');
 
     // Entity 1 (r1): entity ref + shared ref
-    const ent1 = scene.entities[1];
+    const ent1 = scene.entities['entity-1'];
     if (!ent1) throw new Error('e1 missing');
     const er = (ent1.components as Record<string, Record<string, unknown>>).Test_EntityRef;
     expect(er).toBeDefined();
     if (!er) throw new Error('Test_EntityRef missing');
-    // After localId renumbering, the target should be a valid localId number.
-    expect(typeof er.target).toBe('number');
-    expect(er.target as number).toBeGreaterThanOrEqual(0);
+    // Entity references retain the keyed authoring identity.
+    expect(er.target).toBe('entity-0');
 
     // shared<> field must resolve to GUID string.
     const hs = (ent1.components as Record<string, Record<string, unknown>>).Test_HasShared;
@@ -326,9 +327,9 @@ describe('m3-t3(c): TypedArray->Array round-trip normalization', () => {
     expect(collected.ok).toBe(true);
     if (!collected.ok) return;
     const scene = collected.value;
-    expect(scene.entities).toHaveLength(1);
+    expect(Object.keys(scene.entities)).toHaveLength(1);
 
-    const ent0 = scene.entities[0];
+    const ent0 = scene.entities['entity-0'];
     if (!ent0) throw new Error('entity 0 missing');
     const comps = ent0.components as Record<string, Record<string, unknown>>;
     const cf = comps.Test_RT_ArrF32;

package/src/__tests__/scene-equirect-roundtrip.test.ts

@@ -24,22 +24,12 @@ import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import type { EntityHandle } from '@forgeax/engine-ecs';
 import { World } from '@forgeax/engine-ecs';
 import { Skylight } from '@forgeax/engine-render';
-import type {
-  EquirectAsset,
-  Handle,
-  LocalEntityId,
-  SceneAsset,
-  SceneEntity,
-} from '@forgeax/engine-types';
+import type { EquirectAsset, Handle, SceneAsset } from '@forgeax/engine-types';
 import { BUILTIN_BASE } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
 import { registerSceneComponents } from './helpers/register-scene-components';
 
-function localId(n: number): LocalEntityId {
-  return n as LocalEntityId;
-}
-
 // A minimal valid EquirectAsset POD (kind:'equirect', single 2D rgba16float
 // image). The roundtrip never decodes the bytes; a tiny tight-packed buffer is
 // enough to catalogue + resolve the handle.
@@ -72,14 +62,13 @@ describe('scene equirect roundtrip + instantiate handle resolution (M3 / w15)',
     // A scene whose single Skylight references the equirect source by GUID
     // string — the post-parseScenePayload intermediate state where handle
     // fields hold GUID strings awaiting resolution.
-    const entities: SceneEntity[] = [
-      {
-        localId: localId(0),
+    const entities = {
+      'entity-0': {
         components: {
           Skylight: { equirect: EQUIRECT_GUID, intensity: 1.0 },
         },
-      } as unknown as SceneEntity,
-    ];
+      },
+    };
     const scene: SceneAsset = { kind: 'scene', entities };
 
     const sceneHandle = world.allocSharedRef('SceneAsset', scene);