@forgeax/engine-runtime 0.1.4 → 0.1.6

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

@@ -1,3 +1,5 @@
+import * as SceneOwner from '@forgeax/engine-scene';
+
 // M2 test -- rootsToSceneAsset forest entry + schema-derived field conversion
 // (plan-strategy D-1/D-2/D-4/D-7/D-8).
 //
@@ -8,26 +10,45 @@
 //   m2-t4: root ChildOf strip + cross-root closure refs (AC-09/10)
 //   m2-t5: out-of-bounds fail-fast + GUID unresolved fail-fast + exhaustive switch (AC-11/12/17)
 
-import { defineComponent, type EntityHandle, World } from '@forgeax/engine-ecs';
-import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { AnimationPlayer } from '@forgeax/engine-animation';
+import type { Asset } from '@forgeax/engine-assets-runtime';
 import {
+  AssetRegistry,
+  resolveAssetHandle,
   SceneCollectAssetGuidUnresolvedError,
   SceneCollectEntityRefOutOfClosureError,
-} from '@forgeax/engine-runtime';
-import type { Asset } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
-import { rootsToSceneAsset } from '../collect-scene-asset';
-import '@forgeax/engine-render/internal';
+} from '@forgeax/engine-assets-runtime';
+import { defineComponent, type EntityHandle, World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { SceneInstance } from '@forgeax/engine-render';
 import { ChildOf } from '@forgeax/engine-scene';
+import type { Handle, SceneAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { rootsToSceneAsset, serializeSceneAssetToPack } from '../collect-scene-asset';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
 import { registerSceneComponents } from './helpers/register-scene-components';
-import { createTestSceneAssetStore, type TestSceneAssetStore } from './helpers/scene-asset-port';
+
+function linkChildren(
+  world: World,
+  parent: EntityHandle,
+  children: readonly (EntityHandle | number)[],
+): void {
+  registerSceneComponents(world);
+  for (const child of children) {
+    const result = world.addComponent(child as EntityHandle, {
+      component: ChildOf,
+      data: { parent },
+    });
+    if (!result.ok) throw new Error(result.error.code);
+  }
+}
 
 // ═══════════════════════════════════════════════════════════════════════════════
 // Helpers
 // ═══════════════════════════════════════════════════════════════════════════════
 
-function makeRegistry(): TestSceneAssetStore {
-  return createTestSceneAssetStore();
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
 }
 
 function makePayload(kind: Asset['kind']): Asset {
@@ -40,7 +61,7 @@ const Tag = defineComponent('Tag', { value: 'f32' });
 /** Spawn an entity with a component; return raw id. */
 // biome-ignore lint/suspicious/noExplicitAny: test helper bridging typed component tokens to World.spawn
 function s(w: World, comp: any, data: any): number {
-  registerSceneComponents(w, [Tag, Test_EntityRef, Test_EntityArray, comp]);
+  registerSceneComponents(w, [comp]);
   // biome-ignore lint/suspicious/noExplicitAny: test helper adapter for World.spawn overload
   const r = w.spawn({ component: comp, data } as any);
   if (!r.ok) throw new Error('spawn failed');
@@ -73,21 +94,12 @@ describe('m2-t1: forest multi-root BFS closure + localId renumbering', () => {
     const e5 = stag(world, 5);
 
     // Tree A: e0 -> e1 -> e2
-    world.addComponent(e1 as EntityHandle, {
-      component: ChildOf,
-      data: { parent: e0 as EntityHandle },
-    });
-    world.addComponent(e2 as EntityHandle, {
-      component: ChildOf,
-      data: { parent: e1 as EntityHandle },
-    });
+    linkChildren(world, e0 as EntityHandle, [e1 as EntityHandle]);
+    linkChildren(world, e1 as EntityHandle, [e2 as EntityHandle]);
     // Tree C: e4 -> e5
-    world.addComponent(e5 as EntityHandle, {
-      component: ChildOf,
-      data: { parent: e4 as EntityHandle },
-    });
+    linkChildren(world, e4 as EntityHandle, [e5 as EntityHandle]);
 
-    const result = rootsToSceneAsset(reg.port, world, [
+    const result = rootsToSceneAsset(reg, world, [
       e0 as EntityHandle,
       e3 as EntityHandle,
       e4 as EntityHandle,
@@ -104,20 +116,11 @@ describe('m2-t1: forest multi-root BFS closure + localId renumbering', () => {
     const e1 = stag(world, 1);
     const e2 = stag(world, 2);
     const e3 = stag(world, 3);
-    world.addComponent(e1 as EntityHandle, {
-      component: ChildOf,
-      data: { parent: e0 as EntityHandle },
-    });
-    world.addComponent(e2 as EntityHandle, {
-      component: ChildOf,
-      data: { parent: e1 as EntityHandle },
-    });
-    world.addComponent(e3 as EntityHandle, {
-      component: ChildOf,
-      data: { parent: e2 as EntityHandle },
-    });
+    linkChildren(world, e0 as EntityHandle, [e1 as EntityHandle]);
+    linkChildren(world, e1 as EntityHandle, [e2 as EntityHandle]);
+    linkChildren(world, e2 as EntityHandle, [e3 as EntityHandle]);
 
-    const result = rootsToSceneAsset(reg.port, world, [e0 as EntityHandle, e1 as EntityHandle]);
+    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);
@@ -131,24 +134,11 @@ describe('m2-t1: forest multi-root BFS closure + localId renumbering', () => {
     const e2 = stag(world, 2);
     const e3 = stag(world, 3);
     const e4 = stag(world, 4);
-    world.addComponent(e1 as EntityHandle, {
-      component: ChildOf,
-      data: { parent: e0 as EntityHandle },
-    });
-    world.addComponent(e2 as EntityHandle, {
-      component: ChildOf,
-      data: { parent: e0 as EntityHandle },
-    });
-    world.addComponent(e3 as EntityHandle, {
-      component: ChildOf,
-      data: { parent: e1 as EntityHandle },
-    });
-    world.addComponent(e4 as EntityHandle, {
-      component: ChildOf,
-      data: { parent: e2 as EntityHandle },
-    });
+    linkChildren(world, e0 as EntityHandle, [e1 as EntityHandle, e2 as EntityHandle]);
+    linkChildren(world, e1 as EntityHandle, [e3 as EntityHandle]);
+    linkChildren(world, e2 as EntityHandle, [e4 as EntityHandle]);
 
-    const result = rootsToSceneAsset(reg.port, world, [e0 as EntityHandle]);
+    const result = rootsToSceneAsset(reg, world, [e0 as EntityHandle]);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const scene = result.value;
@@ -161,7 +151,7 @@ describe('m2-t1: forest multi-root BFS closure + localId renumbering', () => {
   it('empty roots produces empty SceneAsset (no error)', () => {
     const world = new World();
     const reg = makeRegistry();
-    const result = rootsToSceneAsset(reg.port, world, []);
+    const result = rootsToSceneAsset(reg, world, []);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     expect(result.value.entities).toHaveLength(0);
@@ -179,12 +169,9 @@ describe('m2-t2: entity / array<entity> -> localId', () => {
 
     const r0 = stag(world, 0);
     const r1 = s(world, Test_EntityRef, { target: r0 });
-    world.addComponent(r1 as EntityHandle, {
-      component: ChildOf,
-      data: { parent: r0 as EntityHandle },
-    });
+    linkChildren(world, r0 as EntityHandle, [r1 as EntityHandle]);
 
-    const result = rootsToSceneAsset(reg.port, world, [r0 as EntityHandle]);
+    const result = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const scene = result.value;
@@ -206,21 +193,15 @@ describe('m2-t2: entity / array<entity> -> localId', () => {
     const r0 = stag(world, 0);
     const r1 = stag(world, 1);
     const r2 = stag(world, 2);
-    world.addComponent(r1 as EntityHandle, {
-      component: ChildOf,
-      data: { parent: r0 as EntityHandle },
-    });
-    world.addComponent(r2 as EntityHandle, {
-      component: ChildOf,
-      data: { parent: r0 as EntityHandle },
-    });
+    linkChildren(world, r0 as EntityHandle, [r1 as EntityHandle, r2 as EntityHandle]);
+    registerSceneComponents(world, [Test_EntityArray]);
     world.addComponent(r0 as EntityHandle, {
       component: Test_EntityArray,
       // biome-ignore lint/suspicious/noExplicitAny: entity handle arrays typed as EntityHandle[]; data schema matches component definition
       data: { targets: [r1 as EntityHandle, r2 as EntityHandle] } as any,
     });
 
-    const result = rootsToSceneAsset(reg.port, world, [r0 as EntityHandle]);
+    const result = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const scene = result.value;
@@ -248,7 +229,7 @@ describe('m2-t3: shared<> / array<shared<>> -> GUID', () => {
     const reg = makeRegistry();
     const guid = AssetGuid.parse('d0000000-d000-0000-0000-000000000001');
     if (!guid.ok) throw new Error('guid parse failed');
-    reg.add(guid.value, assetPayload);
+    reg.catalog(guid.value, assetPayload);
 
     const world = new World();
     const handle = world.allocSharedRef('', assetPayload);
@@ -263,7 +244,7 @@ describe('m2-t3: shared<> / array<shared<>> -> GUID', () => {
       // biome-ignore lint/suspicious/noExplicitAny: Handle<> branded type is not directly assignable to component data field for schema 'shared<>'
     } as any);
 
-    const result = rootsToSceneAsset(reg.port, world, [r0 as EntityHandle]);
+    const result = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const scene = result.value;
@@ -283,8 +264,8 @@ describe('m2-t3: shared<> / array<shared<>> -> GUID', () => {
     const guidA = AssetGuid.parse('d0000000-d000-0000-0000-000000000001');
     const guidB = AssetGuid.parse('e0000000-e000-0000-0000-000000000001');
     if (!guidA.ok || !guidB.ok) throw new Error('guid parse failed');
-    reg.add(guidA.value, assetA);
-    reg.add(guidB.value, assetB);
+    reg.catalog(guidA.value, assetA);
+    reg.catalog(guidB.value, assetB);
 
     const world = new World();
     const hA = world.allocSharedRef('', assetA);
@@ -301,7 +282,7 @@ describe('m2-t3: shared<> / array<shared<>> -> GUID', () => {
       // biome-ignore lint/suspicious/noExplicitAny: test helper adapter for component spawn
     } as any);
 
-    const result = rootsToSceneAsset(reg.port, world, [r0 as EntityHandle]);
+    const result = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const scene = result.value;
@@ -339,7 +320,7 @@ describe('m2-t3: shared<> / array<shared<>> -> GUID', () => {
       // biome-ignore lint/suspicious/noExplicitAny: test helper adapter for component spawn
     } as any);
 
-    const result = rootsToSceneAsset(reg.port, world, [r0 as EntityHandle]);
+    const result = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const ent0 = result.value.entities[0];
@@ -359,7 +340,7 @@ describe('m2-t3: shared<> / array<shared<>> -> GUID', () => {
     const reg = makeRegistry();
     const world = new World();
     const uncataloged = makePayload('material');
-    // allocSharedRef WITHOUT reg.add(...) -- the exact old bug shape.
+    // allocSharedRef WITHOUT reg.catalog(...) -- the exact old bug shape.
     const h = world.allocSharedRef('', uncataloged);
 
     const Test_HasSharedArray = defineComponent('Test_UncatMaterials', {
@@ -372,10 +353,10 @@ describe('m2-t3: shared<> / array<shared<>> -> GUID', () => {
       // biome-ignore lint/suspicious/noExplicitAny: test helper adapter for component spawn
     } as any);
 
-    const result = rootsToSceneAsset(reg.port, world, [r0 as EntityHandle]);
+    const result = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
     expect(result.ok).toBe(false);
     if (!result.ok) {
-      expect(result.error.code).toBe('scene-collect-asset-guid-unresolved');
+      expect(result.error).toBeInstanceOf(SceneCollectAssetGuidUnresolvedError);
     }
   });
 
@@ -406,7 +387,7 @@ describe('m2-t3: shared<> / array<shared<>> -> GUID', () => {
     // Spawn WITHOUT setting `ref` -- it defaults to slot 0 (NULL sentinel).
     const r0 = s(world, Test_UnsetScalar, { tag: 42 });
 
-    const result = rootsToSceneAsset(reg.port, world, [r0 as EntityHandle]);
+    const result = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const ent0 = result.value.entities[0];
@@ -428,7 +409,7 @@ describe('m2-t3: shared<> / array<shared<>> -> GUID', () => {
     const reg = makeRegistry();
     const guidA = AssetGuid.parse('d0000000-d000-0000-0000-000000000009');
     if (!guidA.ok) throw new Error('guid parse failed');
-    reg.add(guidA.value, assetA);
+    reg.catalog(guidA.value, assetA);
 
     const world = new World();
     const hA = world.allocSharedRef('', assetA);
@@ -445,7 +426,7 @@ describe('m2-t3: shared<> / array<shared<>> -> GUID', () => {
       // biome-ignore lint/suspicious/noExplicitAny: test helper adapter for component spawn
     } as any);
 
-    const result = rootsToSceneAsset(reg.port, world, [r0 as EntityHandle]);
+    const result = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const ent0 = result.value.entities[0];
@@ -475,7 +456,7 @@ describe('m2-t4: root ChildOf strip + cross-root closure refs', () => {
     const parent = stag(world, 99);
     const r0 = s(world, ChildOf, { parent: parent as EntityHandle });
 
-    const result = rootsToSceneAsset(reg.port, world, [r0 as EntityHandle]);
+    const result = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const scene = result.value;
@@ -494,15 +475,9 @@ describe('m2-t4: root ChildOf strip + cross-root closure refs', () => {
     const bRoot = stag(world, 1);
     const aChild = s(world, Test_EntityRef, { target: bRoot });
 
-    world.addComponent(aChild as EntityHandle, {
-      component: ChildOf,
-      data: { parent: aRoot as EntityHandle },
-    });
+    linkChildren(world, aRoot as EntityHandle, [aChild as EntityHandle]);
 
-    const result = rootsToSceneAsset(reg.port, world, [
-      aRoot as EntityHandle,
-      bRoot as EntityHandle,
-    ]);
+    const result = rootsToSceneAsset(reg, world, [aRoot as EntityHandle, bRoot as EntityHandle]);
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const scene = result.value;
@@ -535,7 +510,7 @@ describe('m2-t5: fail-fast error paths + exhaustive switch', () => {
     const external = stag(world, 99);
     const r0 = s(world, Test_EntityRef, { target: external });
 
-    const result = rootsToSceneAsset(reg.port, world, [r0 as EntityHandle]);
+    const result = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
     expect(result.ok).toBe(false);
 
     if (!result.ok) {
@@ -565,7 +540,7 @@ describe('m2-t5: fail-fast error paths + exhaustive switch', () => {
       src: handle as any,
     });
 
-    const result = rootsToSceneAsset(reg.port, world, [r0 as EntityHandle]);
+    const result = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
     expect(result.ok).toBe(false);
 
     if (!result.ok) {
@@ -584,7 +559,7 @@ describe('m2-t5: fail-fast error paths + exhaustive switch', () => {
     const external = stag(world, 99);
     const r0 = s(world, Test_EntityRef, { target: external });
 
-    const result = rootsToSceneAsset(reg.port, world, [r0 as EntityHandle]);
+    const result = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
     expect(result.ok).toBe(false);
 
     if (!result.ok) {
@@ -603,3 +578,134 @@ describe('m2-t5: fail-fast error paths + exhaustive switch', () => {
 });
 
 // ═══════════════════════════════════════════════════════════════════════════════
+// w19 — AC-07: end-to-end round-trip value equivalence
+//
+// The runtime synthesis of D-2 (GUID domain closed in assets-runtime) + D-3
+// (collect fold) + D-4 (add-or-patch value gate). Mount a GLB-like child scene
+// under a parent, addComponent(AnimationPlayer, { clips: [clipHandle] }) on a
+// live member, save (rootsToSceneAsset + serialize), reopen (parse + instantiate),
+// and assert the reopened member holds AnimationPlayer whose clip is a VALID
+// handle that resolveAssetHandle retrieves to the SAME clip asset (value
+// equivalence, not merely length/presence).
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const W19_CLIP = 'aa19aa19-1919-4191-8191-191919191919';
+const W19_CHILD = 'bb19bb19-1919-4191-8191-191919191919';
+const W19_PARENT = 'cc19cc19-1919-4191-8191-191919191919';
+const W19_SAVED = 'dd19dd19-1919-4191-8191-191919191919';
+
+function pgc(s: string): AssetGuid {
+  const r = AssetGuid.parse(s);
+  if (!r.ok) throw new Error(`bad GUID: ${s}`);
+  return r.value;
+}
+
+function accessParse(reg: AssetRegistry) {
+  const internal = reg as unknown as {
+    parseAssetPayload(kind: string, payload: Record<string, unknown>, refs?: string[]): unknown;
+  };
+  return (
+    kind: string,
+    payload: Record<string, unknown>,
+    refs?: readonly string[] | undefined,
+  ): SceneAsset => {
+    const r = internal.parseAssetPayload(kind, payload, refs as string[] | undefined);
+    if (r === undefined) throw new Error('parse returned undefined');
+    return r as SceneAsset;
+  };
+}
+
+function findMember(w: World, root: EntityHandle): EntityHandle {
+  for (const c of w.iterDescendants(root)) {
+    if (c === root) continue;
+    if (!w.get(c, SceneInstance).ok) continue;
+    const st = SceneOwner.worldGetSceneInstanceState(w, c);
+    if (!st.ok) continue;
+    for (const [member] of st.value.entityToLocalId) return member;
+  }
+  throw new Error('no mounted member');
+}
+
+describe('w19 — end-to-end round-trip value equivalence (AC-07)', () => {
+  it('mount + addComponent(AnimationPlayer) survives save/reopen with value-equal clip', () => {
+    const reg = makeRegistry();
+    const w = new World();
+    registerSceneComponents(w, [AnimationPlayer]);
+
+    // Catalogue the clip asset that the AnimationPlayer will reference.
+    const clipAsset = { kind: 'animation-clip', duration: 1.5 } as unknown as Asset;
+    reg.catalog(pgc(W19_CLIP), clipAsset);
+
+    // 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] } } }],
+    };
+    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 }],
+    };
+    reg.catalog(pgc(W19_PARENT), parent as Asset);
+
+    const inst = reg.instantiate(
+      w.allocSharedRef('SceneAsset', parent) as Handle<'SceneAsset', 'shared'>,
+      w,
+    );
+    expect(inst.ok).toBe(true);
+    if (!inst.ok) return;
+    const root = inst.value;
+
+    // addComponent AnimationPlayer with a handle pointing at the catalogued clip.
+    const clipH = w.allocSharedRef('AnimationClip', clipAsset);
+    const member = findMember(w, root);
+    const add = w.addComponent(member, {
+      component: AnimationPlayer,
+      data: { clips: [clipH] } as never,
+    });
+    expect(add.ok).toBe(true);
+
+    // Save: collect (fold) + serialize.
+    const collect = rootsToSceneAsset(reg, w, [root]);
+    expect(collect.ok).toBe(true);
+    if (!collect.ok) return;
+    const ser = serializeSceneAssetToPack(collect.value, w.components.entries(), W19_SAVED);
+    expect(ser.ok).toBe(true);
+    if (!ser.ok) return;
+
+    // Reopen: parse + catalog + instantiate.
+    const assets = ser.value.assets as Array<Record<string, unknown>>;
+    const a0 = assets[0];
+    if (!a0) throw new Error('no asset');
+    const parsed = accessParse(reg)(
+      'scene',
+      a0.payload as Record<string, unknown>,
+      a0.refs as readonly string[] | undefined,
+    );
+    reg.catalog(pgc(W19_SAVED), parsed as Asset);
+    const inst2 = reg.instantiate(
+      w.allocSharedRef('SceneAsset', parsed) as Handle<'SceneAsset', 'shared'>,
+      w,
+    );
+    expect(inst2.ok).toBe(true);
+    if (!inst2.ok) return;
+    const root2 = inst2.value;
+
+    // Assert: reopened member holds AnimationPlayer with a valid, value-equal clip.
+    const member2 = findMember(w, root2);
+    const apRes = w.get(member2, AnimationPlayer);
+    expect(apRes.ok).toBe(true);
+    if (!apRes.ok) return;
+    const clips2 = Array.from((apRes.value as { clips: ArrayLike<number> }).clips);
+    // slot 0 is a valid (non-zero) handle.
+    expect(clips2[0]).toBeGreaterThan(0);
+    // resolveAssetHandle retrieves the SAME clip asset (value equivalence).
+    const resolved = resolveAssetHandle(w, clips2[0] as unknown as Handle<string, 'shared'>);
+    expect(resolved.ok).toBe(true);
+    if (!resolved.ok) return;
+    const retrieved = resolved.value as unknown as { kind: string; duration: number };
+    expect(retrieved.kind).toBe('animation-clip');
+    expect(retrieved.duration).toBe(1.5);
+  });
+});