@forgeax/engine-runtime 0.1.3 → 0.1.6

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

@@ -0,0 +1,351 @@
+// M3 test -- full schema primitive round-trip (AC-18)
+// (plan-strategy: cover f32/f64/i32/u32/bool/string + entity + shared<>
+//  combination + TypedArray->Array normalization).
+//
+// The round-trip path is: spawn live entities → rootsToSceneAsset collect → verify
+// value equivalence. We use live entity spawning rather than instantiateScene because
+// instantiateScene creates internal shared<> refs back to the SceneAsset itself,
+// which would require cataloguing the scene asset.
+
+import type { Asset } from '@forgeax/engine-assets-runtime';
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { defineComponent, type EntityHandle, World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { ChildOf } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { rootsToSceneAsset } from '../collect-scene-asset';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+function linkChildren(
+  world: World,
+  parent: EntityHandle,
+  children: readonly (EntityHandle | number)[],
+): void {
+  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(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+function makePayload(kind: Asset['kind']): Asset {
+  return { kind } as Asset;
+}
+
+function registerComponents(
+  world: World,
+  ...components: readonly Parameters<World['components']['register']>[0][]
+): void {
+  for (const component of components) world.components.register(component).unwrap();
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: test helper bridging typed component tokens to World.spawn
+function s(w: World, compToken: any, data: any): number {
+  // biome-ignore lint/suspicious/noExplicitAny: test helper adapter for World.spawn overload
+  const r = w.spawn({ component: compToken, data } as any);
+  if (!r.ok) throw new Error('spawn failed');
+  return r.value as number;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// m3-t3(a): individual primitive field round-trip value equivalence
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe('m3-t3(a): individual primitive field round-trip', () => {
+  it('f32 field round-trips with value equivalence', () => {
+    const Test_F32 = defineComponent('Test_RT_F32', { val: 'f32' });
+
+    const world = new World();
+    registerComponents(world, Test_F32);
+    const reg = makeRegistry();
+    // 1.5 is exactly representable in f32.
+    const r0 = s(world, Test_F32, { val: 1.5 });
+
+    const collected = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+    const scene = collected.value;
+    expect(scene.entities).toHaveLength(1);
+
+    const ent0 = scene.entities[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;
+    expect(cf).toBeDefined();
+    if (!cf) throw new Error('Test_RT_F32 missing');
+    expect(cf.val).toBe(1.5);
+  });
+
+  it('f64 field round-trips with value equivalence', () => {
+    const Test_F64 = defineComponent('Test_RT_F64', { val: 'f64' });
+
+    const world = new World();
+    registerComponents(world, Test_F64);
+    const reg = makeRegistry();
+    const r0 = s(world, Test_F64, { val: 1.7976931348623157e308 });
+
+    const collected = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+    const scene = collected.value;
+    expect(scene.entities).toHaveLength(1);
+
+    const ent0 = scene.entities[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;
+    expect(cf).toBeDefined();
+    if (!cf) throw new Error('Test_RT_F64 missing');
+    const v = cf.val as number;
+    expect(v).toBeGreaterThan(1e308);
+  });
+
+  it('i32 field round-trips with value equivalence', () => {
+    const Test_I32 = defineComponent('Test_RT_I32', { val: 'i32' });
+
+    const world = new World();
+    registerComponents(world, Test_I32);
+    const reg = makeRegistry();
+    const r0 = s(world, Test_I32, { val: -42 });
+
+    const collected = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+    const scene = collected.value;
+    expect(scene.entities).toHaveLength(1);
+
+    const ent0 = scene.entities[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;
+    expect(cf).toBeDefined();
+    if (!cf) throw new Error('Test_RT_I32 missing');
+    expect(cf.val).toBe(-42);
+  });
+
+  it('u32 field round-trips with value equivalence', () => {
+    const Test_U32 = defineComponent('Test_RT_U32', { val: 'u32' });
+
+    const world = new World();
+    registerComponents(world, Test_U32);
+    const reg = makeRegistry();
+    const r0 = s(world, Test_U32, { val: 4294967295 });
+
+    const collected = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+    const scene = collected.value;
+    expect(scene.entities).toHaveLength(1);
+
+    const ent0 = scene.entities[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;
+    expect(cf).toBeDefined();
+    if (!cf) throw new Error('Test_RT_U32 missing');
+    expect(cf.val).toBe(4294967295);
+  });
+
+  it('bool field round-trips with value equivalence', () => {
+    const Test_Bool = defineComponent('Test_RT_BOOL', { flag: 'bool' });
+
+    const world = new World();
+    registerComponents(world, Test_Bool, ChildOf);
+    const reg = makeRegistry();
+    const r0 = s(world, Test_Bool, { flag: true });
+    const r1 = s(world, Test_Bool, { flag: false });
+    linkChildren(world, r0 as EntityHandle, [r1 as EntityHandle]);
+
+    const collected = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+    const scene = collected.value;
+    expect(scene.entities).toHaveLength(2);
+
+    const comps0 = (scene.entities[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;
+    expect(comps1).toBeDefined();
+    if (!comps1) throw new Error('Test_RT_BOOL missing on e1');
+    expect(comps1.flag).toBe(false);
+  });
+
+  it('string field round-trips with value equivalence', () => {
+    const Test_Str = defineComponent('Test_RT_STR', { label: 'string' });
+
+    const world = new World();
+    registerComponents(world, Test_Str);
+    const reg = makeRegistry();
+    const r0 = s(world, Test_Str, { label: 'hello-primitive-test' });
+
+    const collected = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+    const scene = collected.value;
+    expect(scene.entities).toHaveLength(1);
+
+    const ent0 = scene.entities[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;
+    expect(cf).toBeDefined();
+    if (!cf) throw new Error('Test_RT_STR missing');
+    expect(cf.label).toBe('hello-primitive-test');
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// m3-t3(b): entity + shared<> + primitive mixed entity full-chain value equivalence
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe('m3-t3(b): mixed entity+shared+primitive round-trip', () => {
+  it('entity with all primitive types + entity ref + shared ref survives round-trip', () => {
+    // Primitive component.
+    const Test_MixedPrim = defineComponent('Test_RT_MixedPrim', {
+      posX: 'f32',
+      posY: 'f32',
+      count: 'i32',
+      flags: 'u32',
+      active: 'bool',
+      name: 'string',
+    });
+
+    // Entity ref component.
+    const Test_EntityRef = defineComponent('Test_EntityRef', { target: 'entity' });
+
+    // Shared ref component.
+    const Test_HasShared = defineComponent('Test_HasShared', {
+      ref: { type: 'shared<TestAsset>' },
+      // biome-ignore lint/suspicious/noExplicitAny: defineComponent constraint too strict for shared<> schema
+    } as any);
+
+    // Register a catalogued asset.
+    const assetPayload = makePayload('skeleton');
+    const reg = makeRegistry();
+    const guid = AssetGuid.parse('d0000000-d000-0000-0000-000000000001');
+    if (!guid.ok) throw new Error('guid parse failed');
+    reg.catalog(guid.value, assetPayload);
+
+    const world = new World();
+    const handle = world.allocSharedRef('', assetPayload);
+    registerComponents(world, Test_MixedPrim, Test_EntityRef, Test_HasShared, ChildOf);
+
+    // Spawn entity A (primitive holder) as root.
+    const r0 = s(world, Test_MixedPrim, {
+      posX: 1.5,
+      posY: 2.5,
+      count: 7,
+      flags: 42,
+      active: true,
+      name: 'mixed-entity',
+    });
+
+    // Spawn entity B (with entity ref to A + shared ref).
+    const r1 = s(world, Test_EntityRef, { target: r0 as EntityHandle });
+    world.addComponent(r1 as EntityHandle, {
+      component: Test_HasShared,
+      // biome-ignore lint/suspicious/noExplicitAny: Handle branded type not assignable to component data for shared<> schema
+      data: { ref: handle as any },
+    });
+
+    // Link r0 → r1 via Children so both are in the BFS closure.
+    linkChildren(world, r0 as EntityHandle, [r1 as EntityHandle]);
+
+    const collected = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+    const scene = collected.value;
+    expect(scene.entities).toHaveLength(2);
+
+    // Entity 0 (r0): primitives
+    const ent0 = scene.entities[0];
+    if (!ent0) throw new Error('e0 missing');
+    const mp = (ent0.components as Record<string, Record<string, unknown>>).Test_RT_MixedPrim;
+    expect(mp).toBeDefined();
+    if (!mp) throw new Error('Test_RT_MixedPrim missing');
+    expect(mp.posX).toBe(1.5);
+    expect(mp.posY).toBe(2.5);
+    expect(mp.count).toBe(7);
+    expect(mp.flags).toBe(42);
+    expect(mp.active).toBe(true);
+    expect(mp.name).toBe('mixed-entity');
+
+    // Entity 1 (r1): entity ref + shared ref
+    const ent1 = scene.entities[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);
+
+    // shared<> field must resolve to GUID string.
+    const hs = (ent1.components as Record<string, Record<string, unknown>>).Test_HasShared;
+    expect(hs).toBeDefined();
+    if (!hs) throw new Error('Test_HasShared missing');
+    expect(typeof hs.ref).toBe('string');
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// m3-t3(c): Float32Array field round-trip as plain Array + value equivalence
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe('m3-t3(c): TypedArray->Array round-trip normalization', () => {
+  it('Float32Array field round-trips to plain Array with value equivalence', () => {
+    const Test_ArrF32 = defineComponent('Test_RT_ArrF32', {
+      data: 'array<f32>',
+    });
+
+    const world = new World();
+    registerComponents(world, Test_ArrF32);
+    const reg = makeRegistry();
+    const arr = new Float32Array([1.0, 2.5, 3.75, 4.0, 5.125]);
+    const r0 = s(world, Test_ArrF32, {
+      // biome-ignore lint/suspicious/noExplicitAny: Float32Array not directly assignable to component data field
+      data: arr as any,
+    });
+
+    const collected = rootsToSceneAsset(reg, world, [r0 as EntityHandle]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+    const scene = collected.value;
+    expect(scene.entities).toHaveLength(1);
+
+    const ent0 = scene.entities[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;
+    expect(cf).toBeDefined();
+    if (!cf) throw new Error('Test_RT_ArrF32 missing');
+    const data = cf.data as unknown[];
+
+    // Round-trip output must be a plain Array.
+    expect(Array.isArray(data)).toBe(true);
+    expect(data).not.toBeInstanceOf(Float32Array);
+
+    // Values must be equivalent.
+    expect(data).toHaveLength(5);
+    expect(data[0]).toBe(1.0);
+    expect(data[1]).toBe(2.5);
+    expect(data[2]).toBe(3.75);
+    expect(data[3]).toBe(4.0);
+    expect(data[4]).toBeCloseTo(5.125, 5);
+  });
+});

package/src/__tests__/scene-bare-guid-refs-instantiate.test.ts

@@ -0,0 +1,123 @@
+// scene-bare-guid-refs-instantiate.test — regression for the prod Play
+// instantiate crash (feedback 2026-06-23, root cause corrected 2026-06-24).
+//
+// Reproduces the production on-disk pack shape that in-process / unit tests
+// never exercised: a catalogued scene envelope whose `refs[]` are *bare GUID
+// edges* (`sceneEntityId` / `sourceField` stripped at the w7 D-10
+// serialization boundary), with multiple entities referencing the same mesh
+// GUID through `MeshFilter.assetHandle`.
+//
+// Before the fix, `_resolveSceneGuids` took Branch A (envelope.refs.length>0)
+// but `continue`-skipped every bare edge (no sceneEntityId/sourceField) →
+// `resolvedMap` stayed empty → the entity-walk fallback (only reachable on the
+// `else` / no-refs branch) never ran → the GUID *string* passed through to
+// spawn. There `col.view[row] = (guidString as number)` coerced to 0 and
+// `retainSharedScalarHandle(guidString)` skipped the `< BUILTIN_BASE` guard
+// (NaN compare is false) → `SharedRefStore.retain` routed `shared-ref-released`
+// to the World error handler, and the field read back as the sentinel 0 (the
+// per-frame `asset-not-registered` flood in the studio report).
+//
+// The fix falls through to the entity-walk fallback whenever the structured
+// edges resolved nothing, so GUID strings resolve to live user-tier handles
+// before spawn.
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { createBoxGeometry } from '@forgeax/engine-geometry';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { MeshFilter, SceneInstance } from '@forgeax/engine-render';
+import type { LocalEntityId, MeshAsset, SceneAsset, SceneEntity } 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;
+}
+
+function cubeMesh(): MeshAsset {
+  const res = createBoxGeometry(1, 1, 1);
+  if (!res.ok) throw new Error('createBoxGeometry(1,1,1) failed');
+  return res.value;
+}
+
+// Two distinct mesh GUIDs referenced from N entities each — mirrors the studio
+// report where engine builtin cube/sphere were among the unresolved handles.
+const MESH_GUID_A = '00d274da-e863-41d8-bafe-10b97d1468d4';
+const MESH_GUID_B = '95730fd2-1111-4222-8333-444455556666';
+
+describe('regression — prod bare-GUID scene envelope.refs resolve before retain', () => {
+  it('instantiate resolves bare-GUID MeshFilter.assetHandle across N entities (no shared-ref-released)', () => {
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    const world = new World();
+    registerSceneComponents(world, [MeshFilter]);
+
+    // Catalogue the two mesh payloads (as loadByGuid would on the prod path).
+    const guidA = AssetGuid.parse(MESH_GUID_A);
+    const guidB = AssetGuid.parse(MESH_GUID_B);
+    if (!guidA.ok || !guidB.ok) throw new Error('GUID parse failed');
+    expect(reg.catalog(guidA.value, cubeMesh()).ok).toBe(true);
+    expect(reg.catalog(guidB.value, cubeMesh()).ok).toBe(true);
+
+    // Build a scene whose entities reference the meshes by GUID *string* —
+    // exactly the post-parseScenePayload intermediate state. Several entities
+    // share each GUID to exercise the dedup (one allocSharedRef per GUID).
+    const entities: SceneEntity[] = [];
+    for (let i = 0; i < 4; i++) {
+      entities.push({
+        localId: localId(i),
+        components: {
+          MeshFilter: { assetHandle: i % 2 === 0 ? MESH_GUID_A : MESH_GUID_B },
+        },
+      } as unknown as SceneEntity);
+    }
+    const scene: SceneAsset = { kind: 'scene', entities };
+
+    // Catalogue the scene as an envelope carrying BARE-GUID refs[] — no
+    // sceneEntityId / sourceField (the prod serialization shape). This forces
+    // Branch A of _resolveSceneGuids while leaving every edge unresolvable.
+    const SCENE_GUID = 'c1111111-2222-4333-8444-555566667777';
+    const sceneGuid = AssetGuid.parse(SCENE_GUID);
+    if (!sceneGuid.ok) throw new Error('scene GUID parse failed');
+    expect(
+      reg.catalog(sceneGuid.value, scene, [{ guid: MESH_GUID_A }, { guid: MESH_GUID_B }]).ok,
+    ).toBe(true);
+
+    // Mint the scene handle and instantiate through the public sugar entry.
+    const sceneHandle = world.allocSharedRef('SceneAsset', scene);
+    const res = reg.instantiate<SceneAsset>(sceneHandle, world);
+
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+
+    // Every spawned member's MeshFilter.assetHandle is a resolved
+    //     user-tier slot (>= BUILTIN_BASE) — not the sentinel 0 a coerced GUID
+    //     string would leave behind.
+    const inst = world.get(res.value, SceneInstance);
+    expect(inst.ok).toBe(true);
+    if (!inst.ok) return;
+    let seen = 0;
+    for (let i = 0; i < 4; i++) {
+      const member = inst.value.mapping[i] as unknown as number;
+      const mf = world.get(member as never, MeshFilter);
+      expect(mf.ok).toBe(true);
+      if (!mf.ok) continue;
+      const handle = mf.value.assetHandle as unknown as number;
+      expect(typeof handle).toBe('number');
+      expect(handle).toBeGreaterThanOrEqual(BUILTIN_BASE);
+      seen++;
+    }
+    expect(seen).toBe(4);
+
+    // Dedup: the two distinct GUIDs mint exactly two user-tier handles,
+    //     shared across the four members (one allocSharedRef per unique GUID).
+    const handles = new Set<number>();
+    for (let i = 0; i < 4; i++) {
+      const member = inst.value.mapping[i] as unknown as number;
+      const mf = world.get(member as never, MeshFilter);
+      if (mf.ok) handles.add(mf.value.assetHandle as unknown as number);
+    }
+    expect(handles.size).toBe(2);
+  });
+});

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

@@ -1,8 +1,48 @@
+// feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w15 —
+// scene roundtrip + instantiate handle resolution for the declarative skylight
+// (plan-strategy §5.3 key test point (4); requirements AC-07 / AC-04;
+// research R-1 — scene-handle-fields generic `shared<` extraction auto-covers
+// the equirect field, no per-field whitelist).
+//
+// Two assertions, both on the CONSUMER path (not `.test-d.ts`):
+//   (1) A SceneAsset whose Skylight references an equirect source by GUID
+//       string round-trips through instantiate: the GUID resolves to a live
+//       user-tier shared handle on the spawned Skylight column (AC-07). This
+//       exercises BOTH scene-resolution paths the equirect field rides:
+//         - extractSceneEntityHandleGuids (generic `shared<` detection, R-1)
+//         - parseScenePayload HANDLE_FIELD_NAMES allowlist (w27, second path)
+//   (2) `world.spawn(Skylight{equirect}).data.equirect` is typed
+//       `Handle<'EquirectAsset','shared'>` — verified by assigning a branded
+//       EquirectAsset handle into the spawn data and reading it back (a wrong
+//       field type would fail typecheck on this consumer path, AC-04).
+//
+// TDD red phase: the equirect field lands in w16 (Skylight component) +
+// w27 (HANDLE_FIELD_NAMES). Until then the `shared<EquirectAsset>` field name
+// is `cubemap` and this file fails to compile / resolve — that is the red.
+
+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/internal';
-import type { EquirectAsset, Handle } from '@forgeax/engine-types';
+import { Skylight } from '@forgeax/engine-render';
+import type {
+  EquirectAsset,
+  Handle,
+  LocalEntityId,
+  SceneAsset,
+  SceneEntity,
+} 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.
 function equirectPod(width = 4, height = 2): EquirectAsset {
   return {
     kind: 'equirect',
@@ -14,20 +54,67 @@ function equirectPod(width = 4, height = 2): EquirectAsset {
   };
 }
 
-describe('Skylight equirect shared-reference ownership', () => {
-  it('stores a World.sharedRefs-owned EquirectAsset handle on the consumer path', () => {
+const EQUIRECT_GUID = '019e4a26-3c29-7420-af5d-20f2724a16b0';
+
+describe('scene equirect roundtrip + instantiate handle resolution (M3 / w15)', () => {
+  it('(1) Skylight{equirect: GUID} round-trips: instantiate resolves the GUID to a live user-tier shared handle (AC-07)', async () => {
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    const world = new World();
+    registerSceneComponents(world, [Skylight]);
+
+    // Catalogue the equirect payload exactly as loadByGuid would on the prod
+    // path, so the GUID string in the scene resolves to a real handle.
+    const { AssetGuid } = await import('@forgeax/engine-pack/guid');
+    const guid = AssetGuid.parse(EQUIRECT_GUID);
+    if (!guid.ok) throw new Error('equirect GUID parse failed');
+    expect(reg.catalog(guid.value, equirectPod()).ok).toBe(true);
+
+    // 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),
+        components: {
+          Skylight: { equirect: EQUIRECT_GUID, intensity: 1.0 },
+        },
+      } as unknown as SceneEntity,
+    ];
+    const scene: SceneAsset = { kind: 'scene', entities };
+
+    const sceneHandle = world.allocSharedRef('SceneAsset', scene);
+    const res = reg.instantiate<SceneAsset>(sceneHandle, world);
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+
+    // The spawned Skylight's equirect field must be a resolved user-tier slot
+    // (>= BUILTIN_BASE), not the sentinel 0 a coerced GUID string would leave.
+    const root = res.value as EntityHandle;
+    const { SceneInstance } = await import('@forgeax/engine-render');
+    const inst = world.get(root, SceneInstance);
+    expect(inst.ok).toBe(true);
+    if (!inst.ok) return;
+    const member = inst.value.mapping[0] as unknown as EntityHandle;
+    const sky = world.get(member, Skylight);
+    expect(sky.ok).toBe(true);
+    if (!sky.ok) return;
+    const equirectHandle = sky.value.equirect as unknown as number;
+    expect(typeof equirectHandle).toBe('number');
+    expect(equirectHandle).toBeGreaterThanOrEqual(BUILTIN_BASE);
+  });
+
+  it('(2) world.spawn(Skylight{equirect}).data.equirect is typed Handle<EquirectAsset,shared> on the consumer path (AC-04)', () => {
     const world = new World();
-    const equirect: Handle<'EquirectAsset', 'shared'> = world.allocSharedRef(
-      'EquirectAsset',
-      equirectPod(),
-    );
-    const entity = world.spawn({ component: Skylight, data: { equirect } }).unwrap();
-
-    const stored = world.get(entity, Skylight).unwrap().equirect;
-    const resolved = world.sharedRefs.resolve<string, EquirectAsset>(stored);
-
-    expect(stored).toBe(equirect);
-    expect(resolved.ok).toBe(true);
-    if (resolved.ok) expect(resolved.value.kind).toBe('equirect');
+    registerSceneComponents(world, [Skylight]);
+    // Branded EquirectAsset handle — assigning it into the spawn `equirect`
+    // field is the consumer-path type assertion: a wrong field type (e.g. the
+    // retired CubeTextureAsset, or a non-handle column) would fail typecheck
+    // here, not in a separate .test-d.ts.
+    const equirect: Handle<'EquirectAsset', 'shared'> = 1024 as Handle<'EquirectAsset', 'shared'>;
+    const e = world.spawn({ component: Skylight, data: { equirect } }).unwrap();
+    const r = world.get(e, Skylight).unwrap();
+    // The read-back value carries the same handle (runtime confirms the column
+    // stored the shared handle, complementing the compile-time field type).
+    expect(r.equirect as unknown as number).toBe(1024);
   });
 });

package/src/__tests__/scene-instance-authoring.integration.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from 'vitest';
+import { instantiateFlat } from '../../../assets-runtime/src/registry/instantiate';
+
+describe('scene authoring bridge', () => {
+  it('exposes the flat authoring entry without a runtime duplicate', () => {
+    expect(typeof instantiateFlat).toBe('function');
+  });
+});

package/src/__tests__/scene-instance-bridge.integration.test.ts

@@ -1,5 +1,5 @@
-import { postSpawnResolveJoints } from '@forgeax/engine-render/internal';
 import { describe, expect, it } from 'vitest';
+import { postSpawnResolveJoints } from '../../../render/src/scene-instances/post-spawn-resolve-joints';
 
 describe('scene instance skin bridge', () => {
   it('exports a post-spawn resolver for nested mounts', () => {

package/src/__tests__/scene-instance-component.test.ts

@@ -14,7 +14,7 @@
 // dynamic structure); plan-tasks §M2 / w15.
 
 import { componentSchema } from '@forgeax/engine-ecs/internal';
-import { SceneInstance } from '@forgeax/engine-render/internal';
+import { SceneInstance } from '@forgeax/engine-render';
 import { describe, expect, it } from 'vitest';
 
 describe('SceneInstance component (w15)', () => {