@forgeax/engine-runtime 0.1.27 → 0.1.29

package/src/__tests__/skin-m2-extract-null-assets.cases.unit.test.ts

@@ -63,6 +63,7 @@ import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import type { EntityHandle, World as WorldType } from '@forgeax/engine-ecs';
 import { ENTITY_NULL_RAW, World } from '@forgeax/engine-ecs';
 import { SpriteAnimationInvalidError } from '@forgeax/engine-ecs/projection';
+import { buildMeshAttributeMapForUvSets } from '@forgeax/engine-geometry';
 import { mat4, vec3 } from '@forgeax/engine-math';
 import type { RenderErrorCode, Renderer as RendererType } from '@forgeax/engine-render';
 import {
@@ -391,6 +392,7 @@ function registerSkinM2Mesh(world: World): Handle<'MeshAsset', 'shared'> {
     vertices: SKIN_M2_TRIANGLE_VERTICES,
     indices: new Uint16Array([0, 1, 2]),
     attributes: {
+      ...buildMeshAttributeMapForUvSets(1),
       position: SKIN_M2_TRIANGLE_POSITIONS,
       skinIndex: new Uint16Array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
       skinWeight: new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]),
@@ -492,17 +494,40 @@ function spawnSkinM2SkinnedEntity(
 
 type SkinM2StubAllocator = {
   buffer: null;
-  allocateSlice(jointCount: number): { jointCount: number; byteOffset: number };
+  allocatePersistentSlice(input: {
+    identity: string;
+    generation: number;
+    jointCount: number;
+    bounds?: Float32Array;
+  }): SkinM2PersistentReceipt;
+  observePersistentJoints(
+    identity: string,
+    ibms: readonly Float32Array[],
+    jointWorlds: readonly Float32Array[],
+  ): readonly number[];
+  allocateSlice(jointCount: number): { jointCount: number; byteOffset: number; buffer: null };
   writeJointPalette(
     slice: { jointCount: number; byteOffset: number },
     ibms: readonly Float32Array[],
     jointWorlds: readonly Float32Array[],
   ): void;
+  beginFrame(): void;
+  endFrame(): void;
+  releasePersistentSlice(identity: string): void;
+  writePersistentJointPalette(receipt: SkinM2PersistentReceipt): void;
   resetForFrame(): void;
   _resetCount(): number;
   _writeCount(): number;
 };
 
+type SkinM2PersistentReceipt = {
+  identity: string;
+  generation: number;
+  jointCount: number;
+  byteOffset: number;
+  buffer: null;
+};
+
 function makeSkinM2StubAllocator(): SkinM2StubAllocator {
   let cursor = 0;
   let resetCount = 0;
@@ -513,11 +538,34 @@ function makeSkinM2StubAllocator(): SkinM2StubAllocator {
       const offset = cursor;
       // 256-aligned bump (mirrors real allocator dyn-offset alignment).
       cursor = (cursor + jointCount * 64 + 255) & ~255;
-      return { jointCount, byteOffset: offset };
+      return { jointCount, byteOffset: offset, buffer: null };
     },
     writeJointPalette() {
       writeCount++;
     },
+    observePersistentJoints() {
+      return [];
+    },
+    allocatePersistentSlice(input) {
+      const slice = this.allocateSlice(input.jointCount);
+      return {
+        ...slice,
+        identity: input.identity,
+        generation: input.generation,
+        fence: 1,
+        customDataStart: 0,
+        storageOrUniform: 'storage',
+        dirtyRanges: [{ startJoint: 0, jointCount: input.jointCount }],
+        uploadBytes: input.jointCount * 64,
+        ...(input.bounds === undefined ? {} : { bounds: input.bounds }),
+      };
+    },
+    writePersistentJointPalette() {
+      writeCount++;
+    },
+    beginFrame() {},
+    endFrame() {},
+    releasePersistentSlice() {},
     resetForFrame() {
       cursor = 0;
       resetCount++;

package/src/__tests__/skin-m2-extract-skeleton-error.cases.unit.test.ts

@@ -63,6 +63,7 @@ import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import type { EntityHandle, World as WorldType } from '@forgeax/engine-ecs';
 import { ENTITY_NULL_RAW, World } from '@forgeax/engine-ecs';
 import { SpriteAnimationInvalidError } from '@forgeax/engine-ecs/projection';
+import { buildMeshAttributeMapForUvSets } from '@forgeax/engine-geometry';
 import { mat4, vec3 } from '@forgeax/engine-math';
 import type { RenderErrorCode, Renderer as RendererType } from '@forgeax/engine-render';
 import {
@@ -391,6 +392,7 @@ function registerSkinM2Mesh(world: World): Handle<'MeshAsset', 'shared'> {
     vertices: SKIN_M2_TRIANGLE_VERTICES,
     indices: new Uint16Array([0, 1, 2]),
     attributes: {
+      ...buildMeshAttributeMapForUvSets(1),
       position: SKIN_M2_TRIANGLE_POSITIONS,
       skinIndex: new Uint16Array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
       skinWeight: new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]),
@@ -492,17 +494,40 @@ function spawnSkinM2SkinnedEntity(
 
 type SkinM2StubAllocator = {
   buffer: null;
-  allocateSlice(jointCount: number): { jointCount: number; byteOffset: number };
+  allocatePersistentSlice(input: {
+    identity: string;
+    generation: number;
+    jointCount: number;
+    bounds?: Float32Array;
+  }): SkinM2PersistentReceipt;
+  observePersistentJoints(
+    identity: string,
+    ibms: readonly Float32Array[],
+    jointWorlds: readonly Float32Array[],
+  ): readonly number[];
+  allocateSlice(jointCount: number): { jointCount: number; byteOffset: number; buffer: null };
   writeJointPalette(
     slice: { jointCount: number; byteOffset: number },
     ibms: readonly Float32Array[],
     jointWorlds: readonly Float32Array[],
   ): void;
+  beginFrame(): void;
+  endFrame(): void;
+  releasePersistentSlice(identity: string): void;
+  writePersistentJointPalette(receipt: SkinM2PersistentReceipt): void;
   resetForFrame(): void;
   _resetCount(): number;
   _writeCount(): number;
 };
 
+type SkinM2PersistentReceipt = {
+  identity: string;
+  generation: number;
+  jointCount: number;
+  byteOffset: number;
+  buffer: null;
+};
+
 function makeSkinM2StubAllocator(): SkinM2StubAllocator {
   let cursor = 0;
   let resetCount = 0;
@@ -513,11 +538,34 @@ function makeSkinM2StubAllocator(): SkinM2StubAllocator {
       const offset = cursor;
       // 256-aligned bump (mirrors real allocator dyn-offset alignment).
       cursor = (cursor + jointCount * 64 + 255) & ~255;
-      return { jointCount, byteOffset: offset };
+      return { jointCount, byteOffset: offset, buffer: null };
     },
     writeJointPalette() {
       writeCount++;
     },
+    observePersistentJoints() {
+      return [];
+    },
+    allocatePersistentSlice(input) {
+      const slice = this.allocateSlice(input.jointCount);
+      return {
+        ...slice,
+        identity: input.identity,
+        generation: input.generation,
+        fence: 1,
+        customDataStart: 0,
+        storageOrUniform: 'storage',
+        dirtyRanges: [{ startJoint: 0, jointCount: input.jointCount }],
+        uploadBytes: input.jointCount * 64,
+        ...(input.bounds === undefined ? {} : { bounds: input.bounds }),
+      };
+    },
+    writePersistentJointPalette() {
+      writeCount++;
+    },
+    beginFrame() {},
+    endFrame() {},
+    releasePersistentSlice() {},
     resetForFrame() {
       cursor = 0;
       resetCount++;

package/src/__tests__/skin-palette-extract.cases.unit.test.ts

@@ -378,7 +378,9 @@ type __MergedKeep =
               written.push({ offset, data });
               return { ok: true };
             },
+            onSubmittedWorkDone: async () => undefined,
           },
+          destroyBuffer: () => ({ ok: true, value: undefined }),
         } as unknown as Parameters<typeof createSkinPaletteAllocator>[0],
         buffers,
         written,

package/src/__tests__/skinned-shadow-mixed.dawn.test.ts

@@ -7,6 +7,7 @@
 
 import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
+import { packInterleavedVertexAttributes } from '@forgeax/engine-geometry';
 import type { Renderer } from '@forgeax/engine-render';
 import { Camera, DirectionalLight, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
 import { Transform } from '@forgeax/engine-scene';
@@ -67,7 +68,7 @@ function staticMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
   });
 }
 
-function skinnedMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
+function skinnedMaterial(world: World, masked: boolean): Handle<'MaterialAsset', 'shared'> {
   return world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
     kind: 'material',
     passes: [
@@ -86,7 +87,8 @@ function skinnedMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
       },
     ],
     values: {
-      baseColor: [0.15, 0.45, 0.9, 1],
+      baseColor: [0.15, 0.45, 0.9, masked ? 0 : 1],
+      alphaCutoff: masked ? 0.5 : 0,
       metallic: 0.1,
       roughness: 0.55,
       emissive: [0, 0, 0],
@@ -120,22 +122,22 @@ function floorMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
 function skinnedMesh(world: World): Handle<'MeshAsset', 'shared'> {
   // Canonical interleaved order: position, normal, uv, tangent, skinIndex,
   // skinWeight (72 bytes / vertex). All vertices use joint zero.
-  const vertices = new Float32Array([
-    -0.75, 0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0.75, 0, 0, 0, 0, 1, 1, 0, 1, 0,
-    0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1.2, 0, 0, 0, 1, 0.5, 1, 1, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0,
-  ]);
+  const attributes = {
+    position: new Float32Array([-0.75, 0, 0, 0.75, 0, 0, 0, 1.2, 0]),
+    normal: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]),
+    uv: new Float32Array([0, 0, 1, 0, 0.5, 1]),
+    tangent: new Float32Array([1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1]),
+    skinIndex: new Uint16Array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
+    skinWeight: new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]),
+  };
+  const packed = packInterleavedVertexAttributes(attributes, 3);
+  if (!packed.ok) throw packed.error;
+  const vertices = packed.value.vertices;
   return world.allocSharedRef<'MeshAsset', MeshAsset>('MeshAsset', {
     kind: 'mesh',
     vertices,
     indices: new Uint16Array([0, 1, 2]),
-    attributes: {
-      position: new Float32Array([-0.75, 0, 0, 0.75, 0, 0, 0, 1.2, 0]),
-      normal: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]),
-      uv: new Float32Array([0, 0, 1, 0, 0.5, 1]),
-      tangent: new Float32Array([1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1]),
-      skinIndex: new Uint16Array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
-      skinWeight: new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]),
-    },
+    attributes,
     aabb: new Float32Array([-0.75, 0, 0, 0.75, 1.2, 0]),
     materialSlots: [{ slotName: 'Default' }],
     submeshes: [
@@ -150,7 +152,7 @@ function skinnedMesh(world: World): Handle<'MeshAsset', 'shared'> {
   });
 }
 
-function skeleton(world: World): Handle<'SkeletonAsset', 'shared'> {
+function skeleton(world: World, missingBounds: boolean): Handle<'SkeletonAsset', 'shared'> {
   const inverseBindMatrices = new Float32Array(16);
   inverseBindMatrices[0] = 1;
   inverseBindMatrices[5] = 1;
@@ -160,6 +162,7 @@ function skeleton(world: World): Handle<'SkeletonAsset', 'shared'> {
     kind: 'skeleton',
     inverseBindMatrices,
     jointCount: 1,
+    ...(missingBounds ? {} : { bounds: new Float32Array([-1, -1, -1, 1, 1, 1]) }),
   });
 }
 
@@ -167,12 +170,17 @@ function identityTransform(pos: readonly [number, number, number] = [0, 0, 0]) {
   return { pos, quat: [0, 0, 0, 1] as const, scale: [1, 1, 1] as const };
 }
 
-function spawnMixedScene(world: World, castShadow: boolean): void {
+function spawnMixedScene(
+  world: World,
+  castShadow: boolean,
+  maskedSkin: boolean,
+  omitSkin: boolean,
+): void {
   const staticMat = staticMaterial(world);
-  const skinMat = skinnedMaterial(world);
+  const skinMat = skinnedMaterial(world, maskedSkin);
   const floorMat = floorMaterial(world);
   const skinMesh = skinnedMesh(world);
-  const skinSkeleton = skeleton(world);
+  const skinSkeleton = skeleton(world, maskedSkin);
 
   world.spawn(
     { component: Transform, data: { ...identityTransform([0, 5, 5]), scale: [10, 0.1, 10] } },
@@ -219,18 +227,19 @@ function spawnMixedScene(world: World, castShadow: boolean): void {
   // Entity order is intentional: static A -> skinned B -> static C.
   spawnStaticCaster(-3);
   const joint = world.spawn({ component: Transform, data: identityTransform([0, 7, 5]) }).unwrap();
-  world.spawn(
-    { component: Transform, data: identityTransform() },
-    { component: MeshFilter, data: { assetHandle: skinMesh } },
-    { component: MeshRenderer, data: { materials: [skinMat] } },
-    {
-      component: Skin,
-      data: {
-        skeleton: skinSkeleton,
-        joints: new Uint32Array([joint as unknown as number]),
+  if (!omitSkin)
+    world.spawn(
+      { component: Transform, data: identityTransform() },
+      { component: MeshFilter, data: { assetHandle: skinMesh } },
+      { component: MeshRenderer, data: { materials: [skinMat] } },
+      {
+        component: Skin,
+        data: {
+          skeleton: skinSkeleton,
+          joints: new Uint32Array([joint as unknown as number]),
+        },
       },
-    },
-  );
+    );
   spawnStaticCaster(3);
 }
 
@@ -253,7 +262,18 @@ async function readPixels(device: GPUDevice, texture: GPUTexture): Promise<Uint8
   return pixels;
 }
 
-async function renderMixed(castShadow: boolean): Promise<MixedCapture> {
+/**
+ * Render both comparison worlds through one host/device.  The previous
+ * fixture constructed and tore down a complete renderer twice; that paid the
+ * native shader prewarm cost twice while adding no GPU coverage.  Keeping the
+ * renderer alive across the two worlds preserves the shadow/no-shadow pixel
+ * comparison and makes the Dawn test's startup cost proportional to one
+ * renderer initialization.
+ */
+async function renderMixedPair(maskedSkin = false): Promise<{
+  readonly shadow: MixedCapture;
+  readonly baseline: MixedCapture;
+}> {
   let device: GPUDevice | undefined;
   let target: GPUTexture | undefined;
   const originalRequestAdapter = globalThis.navigator.gpu.requestAdapter.bind(
@@ -313,22 +333,35 @@ async function renderMixed(castShadow: boolean): Promise<MixedCapture> {
         errors.push(event.error.code);
       }
     });
-    const world = new World();
-    spawnMixedScene(world, castShadow);
-    // The first frame warms the static and skinned PSOs; the second frame is
-    // the asserted mixed command stream after both cache entries exist.
-    for (let frame = 0; frame < 2; frame += 1) {
-      const receipt = drawPublished(renderer, world);
-      expect(receipt.ok, `mixed ${castShadow ? 'shadow' : 'baseline'} draw`).toBe(true);
-      if (!receipt.ok) throw receipt.error;
-      const completed = await receipt.value.completed;
-      expect(completed.ok, 'Queue::submit completion').toBe(true);
-      if (!completed.ok) throw completed.error;
-    }
-    if (device === undefined || target === undefined)
-      throw new Error('Dawn target not initialized');
-    await device.queue.onSubmittedWorkDone();
-    return { pixels: await readPixels(device, target), errors };
+    const renderWorld = async (castShadow: boolean, omitSkin = false): Promise<MixedCapture> => {
+      const world = new World();
+      spawnMixedScene(world, castShadow, maskedSkin, omitSkin);
+      const attached = renderer?.attach(world);
+      if (attached === undefined || !attached.ok) {
+        throw attached?.error ?? new Error('renderer attachment missing');
+      }
+      // The first frame warms the static and skinned PSOs; the second frame is
+      // the asserted mixed command stream after both cache entries exist.
+      for (let frame = 0; frame < 2; frame += 1) {
+        const receipt = drawPublished(renderer, world);
+        expect(receipt.ok, `mixed ${castShadow ? 'shadow' : 'baseline'} draw`).toBe(true);
+        if (!receipt.ok) throw receipt.error;
+        const completed = await receipt.value.completed;
+        expect(completed.ok, 'Queue::submit completion').toBe(true);
+        if (!completed.ok) throw completed.error;
+      }
+      if (device === undefined || target === undefined)
+        throw new Error('Dawn target not initialized');
+      await device.queue.onSubmittedWorkDone();
+      const pixels = await readPixels(device, target);
+      attached.value.dispose();
+      return { pixels, errors: [...errors] };
+    };
+    const shadow = await renderWorld(true);
+    // Remove only the clipped skin for the mask control; retain neighboring
+    // rigid shadows so their PCF contributions cancel exactly.
+    const baseline = maskedSkin ? await renderWorld(true, true) : await renderWorld(false);
+    return { shadow, baseline };
   } finally {
     globalThis.navigator.gpu.requestAdapter = originalRequestAdapter;
     unsubscribe?.();
@@ -356,12 +389,24 @@ function regionDiff(a: Uint8Array, b: Uint8Array, x0: number, x1: number): numbe
 }
 
 describe('mixed static/skinned shadow pipeline (Dawn)', () => {
+  it('keeps alpha clipping on CPU skin residuals without conservative bounds', async () => {
+    const { shadow, baseline } = await renderMixedPair(true);
+    expect(shadow.errors).toEqual([]);
+    expect(baseline.errors).toEqual([]);
+    // A fully clipped skin must match an absent skin in both color and depth.
+    // The opaque test below independently proves all three caster regions.
+    const changed = shadow.pixels.reduce(
+      (count, value, index) => count + Number(value !== baseline.pixels[index]),
+      0,
+    );
+    expect(changed).toBe(0);
+  }, 120000);
+
   it('submits static → skinned → static casters with zero validation errors', async () => {
     if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') {
       throw new Error('dawn-node navigator.gpu not injected');
     }
-    const shadow = await renderMixed(true);
-    const baseline = await renderMixed(false);
+    const { shadow, baseline } = await renderMixedPair();
     expect(shadow.errors).toEqual([]);
     expect(baseline.errors).toEqual([]);
     expect(shadow.pixels.length).toBeGreaterThan(0);

package/src/__tests__/skylight-pipeline-layout.cases.unit.test.ts

@@ -420,13 +420,17 @@ type __MergedKeep =
       expect(layout?.label).toBe('pbr-pl');
     });
 
-    it('(b) PBR material BGL entry count === 24 (user region 0..14 + Skylight 15..21 + transmission 22..23)', () => {
+    it('(b) PBR material BGL entry count === 25 (user region 0..14 + Skylight 15..21 + transmission 22..23 + scene row 46)', () => {
       const device = makeMockDevice();
       // biome-ignore lint/suspicious/noExplicitAny: structural mock
       buildPbrPipelineLayouts(device as any, STORAGE_CAPS);
       const materialBgl = device.capturedBgls.find((b) => b.label === 'pbr-material-skylight-bgl');
       expect(materialBgl).toBeDefined();
-      expect(materialBgl?.entries).toHaveLength(24);
+      expect(materialBgl?.entries).toHaveLength(25);
+      expect(materialBgl?.entries[24]).toMatchObject({
+        binding: 46,
+        buffer: { type: 'read-only-storage', hasDynamicOffset: false },
+      });
     });
 
     it('(c) binding indices 0..23 in order; 15..21 resource types in D-5 round-4 order; 22..23 transmission', () => {

package/src/__tests__/sparse-tag-scene-roundtrip.test.ts

@@ -24,7 +24,7 @@ describe('sparse tag scene persistence', () => {
       .unwrap();
     const registry = {} as AssetRegistry;
     const collected = rootsToSceneAsset(registry, source, [entity]).unwrap();
-    const components = collected.entities[0]?.components as
+    const components = Object.values(collected.entities)[0]?.components as
       | Record<string, Record<string, unknown>>
       | undefined;
 

package/src/__tests__/sprite-lit-bgl-byte-identical.test.ts

@@ -126,16 +126,24 @@ describe('sprite-lit BGL byte-identical to sprite (AC-07, w4/w5 close)', () => {
       expect(base.length).toBe(15);
     });
 
-    it('pbr-material-merged stays 24 entries (sprite/sprite-lit do not change material BGL shape)', () => {
+    it('pbr-material-merged stays 25 entries (sprite/sprite-lit do not change material BGL shape)', () => {
       const merged = buildBindGroupLayoutDescriptor(makeSpec('forgeax::sprite-lit'), {
         kind: 'pbr-material-merged',
       });
-      expect(merged.entries.length).toBe(24);
+      expect(merged.entries.length).toBe(25);
       // mergeSkylightIntoMaterialBgl + transmission injection must stay
       // append-only against the 7-entry PBR base.
       const base = buildPbrMaterialUserRegionEntries();
       const afterSky = mergeSkylightIntoMaterialBgl(base);
-      const expected = [...afterSky, ...appendInjection(afterSky, 'transmission')];
+      const expected = [
+        ...afterSky,
+        ...appendInjection(afterSky, 'transmission'),
+        {
+          binding: 46,
+          visibility: 0x1 | 0x2,
+          buffer: { type: 'read-only-storage', hasDynamicOffset: false },
+        },
+      ];
       expect(merged.entries).toEqual(expected);
     });
   });

package/src/__tests__/template-game-default-api-contract.test.ts

@@ -38,15 +38,11 @@ import { MeshRenderer, SceneInstance } from '@forgeax/engine-render';
 // undefined during instantiate. ChildOf + SceneInstance are used directly
 // below as values; Transform / MeshRenderer pin the side-effect import.
 import { ChildOf, Transform } from '@forgeax/engine-scene';
-import type { LocalEntityId, MaterialAsset, SceneAsset, SceneEntity } from '@forgeax/engine-types';
+import type { MaterialAsset, SceneAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
 import { registerRuntimeComponents } from './helpers/register-runtime-components';
 
-function lid(n: number): LocalEntityId {
-  return n as LocalEntityId;
-}
-
 // Shape this fixture mirrors the `apps/game-capability-lab/assets/scene.pack.json`
 // SceneAsset payload after the template's `instantiateScenePack` helper has
 // rewritten ref-int → GUID strings + lifted MeshRenderer.material → materials[].
@@ -61,9 +57,8 @@ function buildSceneAssetWithGuidRef(): SceneAsset {
   void Transform;
   void MeshRenderer;
 
-  const nodes: SceneEntity[] = [
-    {
-      localId: lid(0),
+  const nodes = {
+    'entity-0': {
       components: {
         Transform: { pos: [0, 0, 0] },
         // GUID string (post template ref-int → GUID rewrite). The registry's
@@ -72,14 +67,13 @@ function buildSceneAssetWithGuidRef(): SceneAsset {
         MeshRenderer: { materials: [MAT_GUID] },
       },
     },
-    {
-      localId: lid(1),
+    'entity-1': {
       components: {
         Transform: { pos: [1, 0, 0] },
-        ChildOf: { parent: 0 as unknown as EntityHandle },
+        ChildOf: { parent: 'entity-0' },
       },
     },
-  ];
+  };
   return { kind: 'scene', entities: nodes };
 }
 
@@ -272,13 +266,19 @@ describe('game-capability-lab API contract (regression for `world.sceneInstances
       assets:
         | {
             kind: string;
-            payload?: { entities?: SceneEntity[]; nodes?: SceneEntity[] };
+            payload?: {
+              entities?: Record<string, { components: Record<string, Record<string, unknown>> }>;
+              nodes?: Record<string, { components: Record<string, Record<string, unknown>> }>;
+            };
           }[]
         | Record<
             string,
             {
               kind: string;
-              payload?: { entities?: SceneEntity[]; nodes?: SceneEntity[] };
+              payload?: {
+                entities?: Record<string, { components: Record<string, Record<string, unknown>> }>;
+                nodes?: Record<string, { components: Record<string, Record<string, unknown>> }>;
+              };
             }
           >;
     };
@@ -291,7 +291,7 @@ describe('game-capability-lab API contract (regression for `world.sceneInstances
       // no longer restates it (Derive, Don't Duplicate — the loader synthesises
       // Asset.kind from the envelope on load).
       if (asset.kind !== 'scene') continue;
-      for (const node of asset.payload?.entities ?? asset.payload?.nodes ?? []) {
+      for (const node of Object.values(asset.payload?.entities ?? asset.payload?.nodes ?? {})) {
         for (const [compName, data] of Object.entries(node.components)) {
           if (STRIP_COMPONENTS.has(compName)) continue;
           scanned++;
@@ -305,9 +305,7 @@ describe('game-capability-lab API contract (regression for `world.sceneInstances
           for (const rawField of Object.keys(data ?? {})) {
             const field = rename[rawField] ?? rawField;
             if (!(field in schema)) {
-              offenders.push(
-                `${compName}.${rawField} (localId ${node.localId as unknown as number})`,
-              );
+              offenders.push(`${compName}.${rawField} (scene entity key)`);
             }
           }
         }
@@ -330,7 +328,9 @@ describe('game-capability-lab API contract (regression for `world.sceneInstances
     type TemplatePackAsset = {
       guid?: string;
       kind: string;
-      payload?: { entities?: { components: { MeshRenderer?: { materials?: number[] } } }[] };
+      payload?: {
+        entities?: Record<string, { components: { MeshRenderer?: { materials?: number[] } } }>;
+      };
       refs?: string[];
     };
     const pack = JSON.parse(readFileSync(packPath, 'utf-8')) as {
@@ -346,7 +346,7 @@ describe('game-capability-lab API contract (regression for `world.sceneInstances
     if (scene === undefined) return;
 
     const referencedMaterialGuids = new Set(
-      (scene.payload?.entities ?? []).flatMap((entity) =>
+      Object.values(scene.payload?.entities ?? {}).flatMap((entity) =>
         (entity.components.MeshRenderer?.materials ?? []).map((index) => scene.refs?.[index]),
       ),
     );
@@ -369,7 +369,7 @@ describe('game-capability-lab API contract (regression for `world.sceneInstances
     const reg = new AssetRegistry(makeMockShaderRegistry());
     const sceneGuid = AssetGuid.parse(SCENE_GUID);
     if (!sceneGuid.ok) throw new Error('parse');
-    const payload: SceneAsset = { kind: 'scene', entities: [] };
+    const payload: SceneAsset = { kind: 'scene', entities: {} };
     const cataloged = reg.catalog<SceneAsset>(sceneGuid.value, payload);
     expect(cataloged.ok).toBe(true);
     if (!cataloged.ok) return;

package/src/__tests__/tonemap-hdr-target.cases.unit.test.ts

@@ -407,10 +407,10 @@ type __MergedKeep =
       __mockTag: 'gpu-device',
       lost,
       features: new Set(),
-      // Model a native WebGPU device: the test below asserts the preferred
-      // swap-chain format selected by the storage-buffer path. An empty limits
-      // object describes a downlevel device and correctly selects the rgba
-      // fallback instead.
+      // Model a native WebGPU device: this test exercises the preferred
+      // swap-chain format selected by the storage-buffer path.  An empty
+      // limits object describes a downlevel device and correctly selects the
+      // rgba fallback instead.
       limits: {
         maxStorageBuffersPerShaderStage: 8,
       },
@@ -634,14 +634,17 @@ type __MergedKeep =
       // test if the format is RENDER_ATTACHMENT-renderable. NOT an HDR
       // colour attachment -- a one-shot probe destroyed immediately. Filter
       // by label so the AC-03(c) lazy-HDR contract remains testable.
+      // The neutral normal-map fallback uses float16 to represent 0.5 exactly;
+      // it is a 1x1 sampled material input, not a scene HDR attachment.
       const hdrTextureCalls = log.records.filter(
         (r) =>
           r.type === 'createTexture' &&
           r.format === 'rgba16float' &&
+          r.label !== 'fallback-normal-1x1' &&
           !(r.label?.startsWith('skylight-fallback-') ?? false) &&
           !(r.label?.startsWith('forgeax-caps-probe-') ?? false),
       );
-      expect(hdrTextureCalls.length).toBe(0);
+      expect(hdrTextureCalls.map((record) => record.label)).toEqual([]);
     });
 
     it('row 4: pbr + unlit engine modules compile at boot (tonemap defers to unified channel)', async () => {

package/src/__tests__/tonemap-pipeline-split.cases.unit.test.ts

@@ -519,10 +519,13 @@ type __MergedKeep =
       },
       getPipelineState: () => null,
       assets: {
+        catalogEpoch: 0,
         get: () => ({ ok: false, error: { code: 'asset-not-registered' } }),
         getMeshGpuHandles: () => undefined,
         getTextureGpuView: () => undefined,
       },
+      deviceScope: { generation: 0 },
+      gpuStore: { meshResidencyEpoch: 0 },
       errorRegistry: {
         fire: () => undefined,
       },