@forgeax/engine-runtime 0.1.21 → 0.1.23

package/src/__tests__/loader-name-survival.test.ts

@@ -13,11 +13,11 @@
 //                 after loadByGuid (parseAssetPayload sync branch) resolveName
 //                 returns each stored name.
 //   AC-08 async — a texture in its own (single-asset) package; after loadByGuid
-//                 (texture upstream async branch) resolveName returns the
-//                 basename derived from its package path. Without the entry ->
-//                 Package wiring the texture would land in a null package and
-//                 resolveName would be '' -- so basename here still proves the
-//                 async load path registered the package post-roundtrip.
+//                 (texture upstream async branch) resolveName preserves the
+//                 explicit entry name. Without the entry -> Package wiring the
+//                 texture would land in a null package and resolveName would be
+//                 '' -- so the named result proves the async load path registered
+//                 the package post-roundtrip.
 //   FALSIFY     — the same pack with the entry name stripped degrades to
 //                 basename(path), proving the assertion is name-sensitive (not
 //                 a tautology). The FALSIFY block does not gate CI; it documents
@@ -187,10 +187,9 @@ describe('loader name survival (AC-08)', () => {
 
     const r = await reg.loadByGuid(parseGuid(TEX));
     expect(r.ok).toBe(true);
-    // Single-asset texture package -> basename(path) (AC-01). The wiring is what
-    // makes this non-empty: without entry -> Package the texture lands in a null
-    // package and resolveName would be ''.
-    expect(reg.resolveName(TEX)).toBe('diffuse.pack.json');
+    // An explicit entry name wins even for a single-asset package. The wiring
+    // makes this name survive the async JSON-roundtrip path.
+    expect(reg.resolveName(TEX)).toBe('Diffuse');
   });
 
   it('FALSIFY: stripped entry.name degrades to basename, proving name-sensitivity', async () => {

package/src/__tests__/package-promotion.test.ts

@@ -7,13 +7,10 @@
 //           asset's derived basename is frozen as its stored name so it keeps
 //           the same resolveName (now via the multi-asset branch), with no error
 //           and no caller awareness. Promotion is idempotent: re-registering the
-//           same path does not overwrite an already-frozen name.
+//           same path does not overwrite an already-frozen name. An explicitly
+//           authored name is already stable and is preserved through promotion.
 //
-// The promotion is observable through `package.xor-invariant-violated`: when the
-// original asset already carries a stored name at promotion time (the abnormal
-// single-asset-with-name state, D-4), the freeze must not overwrite it and the
-// soft-violation counter increments. Without w11 there is no promotion branch,
-// so the counter never fires (the falsifying assertion).
+// The promotion must not emit a violation for an explicitly named first asset.
 
 import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
@@ -70,19 +67,18 @@ describe('1->N package promotion (AC-05)', () => {
     expect(reg.resolveName(G2)).toBe('SecondAsset');
   });
 
-  it('abnormal single-asset-with-name state bumps the xor counter and is not overwritten', () => {
+  it('preserves an explicitly authored first-asset name without a false violation', () => {
     const reg = makeRegistry();
     const metrics = createEngineMetrics();
     reg.setMetrics(metrics);
-    // Abnormal: a single-asset package whose lone asset already carries a name.
     reg.catalog(parseGuid(G1), sampler);
     reg._registerPackage(PATH, [G1], new Map([[G1, 'PreNamed']]));
     reg.catalog(parseGuid(G2), sampler);
-    // Promotion fires: the pre-existing name is preserved (not overwritten by
-    // basename) and the soft-violation counter records the abnormal state.
+    // Promotion preserves the authored name rather than replacing it with the
+    // package basename.
     reg._registerPackage(PATH, [G2], new Map([[G2, 'SecondAsset']]));
 
     expect(reg.resolveName(G1)).toBe('PreNamed');
-    expect(metrics.snapshot()['package.xor-invariant-violated']).toBe(1);
+    expect(metrics.snapshot()['package.xor-invariant-violated'] ?? 0).toBe(0);
   });
 });

package/src/__tests__/pbr-pipeline.unit.test.ts

@@ -44,34 +44,29 @@ function makeSpec(): PipelineSpec {
 
 describe('buildBindGroupLayoutDescriptor — pbr-pipeline 6 sites byte-equiv', () => {
   describe('pbr-view', () => {
-    it('storageBuffer=true: 12 entries with read-only-storage on bindings 1+2 and projector bindings 11+12', () => {
+    it('storageBuffer=true: 10 entries with projector bindings 11+12', () => {
       const spec = makeSpec();
       const out = buildBindGroupLayoutDescriptor(spec, {
         kind: 'pbr-view',
-        caps: { storageBuffer: true },
+        caps: { storageBuffer: true, extendedLighting: false },
       });
       const expected = {
         label: 'pbr-view-bgl',
-        entries: buildPbrViewBglEntries({ storageBuffer: true }),
+        entries: buildPbrViewBglEntries({ storageBuffer: true, extendedLighting: false }),
       };
       expect(out).toEqual(expected);
-      // feat-20260625-spot-light-shadow-mapping: binding 8 (spot shadow atlas,
-      // w14) raised the view BGL to 9 entries (always-on, D-5). The
-      // Points/Lines viewport UBO occupies binding 10, while w25 (scope-amend
-      // webkit-fallback) folded the former binding 9 spotLightViewProj matrices
-      // UBO into the View UBO (`view.spotLightViewProj`), so the BGL stays at 9
-      // entries (bindings 0..8 plus optional projector 11+12 and binding 10)
-      // — keeping the WebGL2 fallback fragment uniform-buffer count <= 11
-      // (GLES 3.0), while the projector remains available on the default
-      // WebGPU path.
-      expect(out.entries.length).toBe(12);
+      // Binding 8 is the always-on spot shadow atlas, binding 10 is the
+      // Points/Lines viewport UBO, and bindings 11/12 are the optional
+      // projector resources. Local lights are exclusively carried by the
+      // Standard Cluster group(2), so the view group has no point/spot slots.
+      expect(out.entries.length).toBe(10);
       expect(out.entries.find((entry) => entry.binding === 9)).toBeUndefined();
       expect(out.entries.find((entry) => entry.binding === 10)?.buffer?.type).toBe('uniform');
       expect(out.entries.find((entry) => entry.binding === 11)?.texture?.viewDimension).toBe('2d');
       expect(out.entries.find((entry) => entry.binding === 12)?.sampler?.type).toBe('filtering');
     });
 
-    it('storageBuffer=false: bindings 1+2 fall back to uniform', () => {
+    it('storageBuffer=false: view group still has no local-light bindings', () => {
       const spec = makeSpec();
       const out = buildBindGroupLayoutDescriptor(spec, {
         kind: 'pbr-view',
@@ -82,17 +77,22 @@ describe('buildBindGroupLayoutDescriptor — pbr-pipeline 6 sites byte-equiv', (
         entries: buildPbrViewBglEntries({ storageBuffer: false }),
       };
       expect(out).toEqual(expected);
+      expect(out.entries.some((entry) => entry.binding === 1 || entry.binding === 2)).toBe(false);
     });
 
     it('projectorAvailable=false: omits optional projector bindings for the 16-texture limit', () => {
       const spec = makeSpec();
       const out = buildBindGroupLayoutDescriptor(spec, {
         kind: 'pbr-view',
-        caps: { storageBuffer: true, projectorAvailable: false },
+        caps: { storageBuffer: true, projectorAvailable: false, extendedLighting: false },
       });
       expect(out).toEqual({
         label: 'pbr-view-bgl',
-        entries: buildPbrViewBglEntries({ storageBuffer: true, projectorAvailable: false }),
+        entries: buildPbrViewBglEntries({
+          storageBuffer: true,
+          projectorAvailable: false,
+          extendedLighting: false,
+        }),
       });
       expect(out.entries.find((entry) => entry.binding === 11)).toBeUndefined();
       expect(out.entries.find((entry) => entry.binding === 12)).toBeUndefined();

package/src/__tests__/pipeline.unit.test.ts

@@ -904,16 +904,14 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
       expect(result.value).toBe(false);
     });
 
-    it('buildPbrViewBglEntries with UNIFORM_CAPS yields uniform for bindings 1 and 2', () => {
+    it('buildPbrViewBglEntries with UNIFORM_CAPS has no local-light bindings', () => {
       const entries = buildPbrViewBglEntries(UNIFORM_CAPS);
-      expect(entries[1]?.buffer?.type).toBe('uniform');
-      expect(entries[2]?.buffer?.type).toBe('uniform');
+      expect(entries.some((entry) => entry.binding === 1 || entry.binding === 2)).toBe(false);
     });
 
-    it('buildPbrViewBglEntries with STORAGE_CAPS yields read-only-storage (regression guard)', () => {
+    it('buildPbrViewBglEntries with STORAGE_CAPS has no local-light bindings', () => {
       const entries = buildPbrViewBglEntries(STORAGE_CAPS);
-      expect(entries[1]?.buffer?.type).toBe('read-only-storage');
-      expect(entries[2]?.buffer?.type).toBe('read-only-storage');
+      expect(entries.some((entry) => entry.binding === 1 || entry.binding === 2)).toBe(false);
     });
   });
 
@@ -990,14 +988,15 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
       expect(instBgl?.entries[0]?.buffer?.type).toBe('uniform');
     });
 
-    it('uniform fallback: view BGL bindings 1+2 are uniform', () => {
+    it('uniform fallback: view BGL has no local-light bindings', () => {
       const device = makeMockDevice();
       // biome-ignore lint/suspicious/noExplicitAny: structural mock
       buildPbrPipelineLayouts(device as any, UNIFORM_CAPS);
       const viewBgl = device.capturedBgls.find((b) => b.label === 'pbr-view-bgl');
       expect(viewBgl).toBeDefined();
-      expect(viewBgl?.entries[1]?.buffer?.type).toBe('uniform');
-      expect(viewBgl?.entries[2]?.buffer?.type).toBe('uniform');
+      expect(viewBgl?.entries.some((entry) => entry.binding === 1 || entry.binding === 2)).toBe(
+        false,
+      );
     });
 
     it('storage path: mesh-array BGL entry type is read-only-storage (regression guard)', () => {
@@ -5090,26 +5089,23 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
 
   // ── Standard cluster index-overflow RuntimeError class shape ─────────────────
 
-  // ── AC-03 guardrail: URP LIGHT_ARRAY_MAX_SLOTS=4 + 5 PointLights ─────────────
-  //
-  // This test verifies that the existing URP `render-system-multi-light` warn-once
-  // still fires when PointLights exceed the first-slice cap (AC-03).
-  // The budget constant LIGHT_ARRAY_MAX_SLOTS must remain at 4.
+  // ── Unified Cluster light ABI guardrails ─────────────────────────────────
 
-  describe('URP light budget warn-once guardrail (AC-03)', () => {
-    it('LIGHT_ARRAY_MAX_SLOTS is still 4 (URP first-slice cap)', async () => {
-      const { LIGHT_ARRAY_MAX_SLOTS } = await import('../../../render/src/light-buffer-layout');
-      expect(LIGHT_ARRAY_MAX_SLOTS).toBe(4);
+  describe('Standard Cluster light ABI guardrail', () => {
+    it('BYTES_PER_DIRECT_LIGHT_SLOT matches the unified URP and HDRP ABI', async () => {
+      const { BYTES_PER_DIRECT_LIGHT_SLOT } = await import(
+        '../../../render/src/light-buffer-layout'
+      );
+      expect(BYTES_PER_DIRECT_LIGHT_SLOT).toBe(80);
     });
 
-    it('POINT_LIGHT_STD430_BYTES and SPOT_LIGHT_STD430_BYTES match the current URP payloads', async () => {
-      const { POINT_LIGHT_STD430_BYTES, SPOT_LIGHT_STD430_BYTES } = await import(
+    it('direct-light payload byte size matches the Cluster volume transport', async () => {
+      const { BYTES_PER_DIRECT_LIGHT_SLOT } = await import(
         '../../../render/src/light-buffer-layout'
       );
-      expect(POINT_LIGHT_STD430_BYTES).toBe(32);
-      // SpotLight's projector receiver controls and shadow intensity occupy
-      // the appended fifth vec4 column; point-light layout remains unchanged.
-      expect(SPOT_LIGHT_STD430_BYTES).toBe(80);
+      // Point, Spot, and Rect volume receivers share the same five-row
+      // DirectLightSlot transport as the Standard surface Cluster path.
+      expect(BYTES_PER_DIRECT_LIGHT_SLOT).toBe(80);
     });
   });
 }

package/src/__tests__/point-light-shadow.browser.test.ts

@@ -400,4 +400,5 @@ it.skipIf(!browserReady)(
       canvas.remove();
     }
   },
+  60_000,
 );

package/src/__tests__/point-light-shadow.unit.test.ts

@@ -19,10 +19,9 @@ import { describe, expect, it } from 'vitest';
 import { validatePointLightShadowData } from '../../../render/src/components/light-helpers';
 import { ShadowInvalidConfigError } from '../../../render/src/errors/render';
 import {
-  BYTES_PER_LIGHT_SLOT,
-  LIGHTSLOT_LAYOUT,
-  packLightSlot,
-  SPOT_LIGHT_PROJECTOR_FLAG,
+  BYTES_PER_DIRECT_LIGHT_SLOT,
+  DIRECT_LIGHT_SLOT_LAYOUT,
+  packDirectLightSlot,
 } from '../../../render/src/light-buffer-layout';
 import { buildPointShadowMatrices } from '../../../render/src/render-system-extract';
 import {
@@ -551,7 +550,7 @@ function spawnValidatedPointShadow(
     });
 
     describe('standard point shadow light-slot packing (AC-05)', () => {
-      it('AC-13: packLightSlot writes shadow info onto LightSlot pad lanes (byte 52..64)', () => {
+      it('AC-13: packDirectLightSlot writes point shadow identity metadata', () => {
         const snap = {
           kind: 'point' as const,
           position: vec3.create(1, 2, 3),
@@ -559,26 +558,18 @@ function spawnValidatedPointShadow(
           intensity: 1,
           invRangeSquared: 0.04,
         };
-        // Without shadow info: layer = -1 sentinel; near/far = 0.
-        const noShadow = packLightSlot(snap);
+        // Without shadow info: layer = -1 sentinel in metadata word 17.
+        const noShadow = packDirectLightSlot(snap);
         const i32NoShadow = new Int32Array(noShadow.buffer);
-        expect(i32NoShadow[13]).toBe(-1); // sentinel
-        expect(noShadow[14]).toBe(0); // near
-        expect(noShadow[15]).toBe(0); // far
-
-        // With shadow info: layer 2, near 0.1, far 25 — matches PointLightShadow defaults.
-        const withShadow = packLightSlot(snap, {
-          shadowAtlasLayer: 2,
-          near: 0.1,
-          far: 25,
-        });
+        expect(i32NoShadow[17]).toBe(-1); // sentinel
+
+        // Extract joins the PointLightShadow layer before packing.
+        const withShadow = packDirectLightSlot({ ...snap, shadowAtlasLayer: 2 });
         const i32Shadow = new Int32Array(withShadow.buffer);
-        expect(i32Shadow[13]).toBe(2);
-        expect(withShadow[14]).toBeCloseTo(0.1, 5);
-        expect(withShadow[15]).toBe(25);
+        expect(i32Shadow[17]).toBe(2);
       });
 
-      it('AC-13: spot light packLightSlot writes its shadow defaults into the tail lanes', () => {
+      it('AC-13: unified Spot packing writes shadow metadata', () => {
         const spotSnap = {
           kind: 'spot' as const,
           entity: 0,
@@ -596,86 +587,15 @@ function spawnValidatedPointShadow(
           farPlane: 50,
           shadowAtlasTile: -1,
         };
-        // SpotLight uses the former pad lanes for the shadow intensity and
-        // PCF-kernel defaults. The atlas tile remains the -1 sentinel while
-        // projector/shadow consumers read the appended payload fields.
-        const packed = packLightSlot(spotSnap, {
-          shadowAtlasLayer: 0,
-          near: 0.1,
-          far: 25,
-        });
+        const packed = packDirectLightSlot(spotSnap);
         const i32 = new Int32Array(packed.buffer);
-        expect(i32[13]).toBe(-1); // sentinel; spot lights stay shadowless
-        expect(packed[14]).toBeCloseTo(1, 5);
-        expect(packed[15]).toBeCloseTo(3, 5);
+        expect(i32[17]).toBe(-1);
       });
 
-      it('keeps authored spot shadow intensity and PCF width in the cluster lanes', () => {
-        const spotSnap = {
-          kind: 'spot' as const,
-          entity: 0,
-          position: vec3.create(0, 0, 0),
-          direction: vec3.create(0, -1, 0),
-          color: vec3.create(1, 1, 1),
-          intensity: 1,
-          invRangeSquared: 0,
-          cosInner: 0.95,
-          cosOuter: 0.85,
-          castShadow: true,
-          lightViewProj: undefined,
-          mapSize: 2048,
-          nearPlane: 0.1,
-          farPlane: 50,
-          shadowAtlasTile: 2,
-          shadowIntensity: 0.35,
-          pcfKernelSize: 5,
-        };
-        const packed = packLightSlot(spotSnap);
-        const i32 = new Int32Array(packed.buffer);
-        expect(i32[13]).toBe(2);
-        expect(packed[14]).toBeCloseTo(0.35, 5);
-        expect(packed[15]).toBeCloseTo(5, 5);
-      });
-
-      it('marks the accepted projector without losing a shadow tile', () => {
-        const spotSnap = {
-          kind: 'spot' as const,
-          entity: 7,
-          position: vec3.create(0, 2, 0),
-          direction: vec3.create(0, -1, 0),
-          color: vec3.create(1, 1, 1),
-          intensity: 1,
-          invRangeSquared: 0.04,
-          cosInner: 0.95,
-          cosOuter: 0.85,
-          castShadow: true,
-          lightViewProj: new Float32Array(16),
-          mapSize: 512,
-          nearPlane: 0.1,
-          farPlane: 25,
-          shadowAtlasTile: 2,
-          projectorAsset: { kind: 'texture' } as never,
-        };
-        const packed = packLightSlot(spotSnap, undefined, true);
-        const encoded = new Int32Array(packed.buffer)[13] ?? 0;
-        expect(encoded & SPOT_LIGHT_PROJECTOR_FLAG).toBe(SPOT_LIGHT_PROJECTOR_FLAG);
-        expect(encoded & (SPOT_LIGHT_PROJECTOR_FLAG - 1)).toBe(2);
-
-        const projectorOnly = packLightSlot({ ...spotSnap, shadowAtlasTile: -1 }, undefined, true);
-        const projectorOnlyEncoded = new Int32Array(projectorOnly.buffer)[13] ?? 0;
-        expect(projectorOnlyEncoded).toBe(SPOT_LIGHT_PROJECTOR_FLAG);
-      });
-
-      it('AC-05: LIGHTSLOT_LAYOUT byteSize unchanged at 64 (no-regression for standard)', () => {
-        // The pad-lane re-purposing must not change the total LightSlot size:
-        // the std430 vec4 stride is preserved; only the field semantics within
-        // bytes 52..64 changed (u32 pad -> i32 layer + f32 near + f32 far).
-        expect(BYTES_PER_LIGHT_SLOT).toBe(64);
-        expect(LIGHTSLOT_LAYOUT.byteSize).toBe(64);
-        expect(LIGHTSLOT_LAYOUT.shadowAtlasLayerOffset).toBe(52);
-        expect(LIGHTSLOT_LAYOUT.shadowPayloadOffset).toBe(52);
-        expect(LIGHTSLOT_LAYOUT.shadowNearOffset).toBe(56);
-        expect(LIGHTSLOT_LAYOUT.shadowFarOffset).toBe(60);
+      it('AC-05: DIRECT_LIGHT_SLOT_LAYOUT keeps the five-row ABI', () => {
+        expect(BYTES_PER_DIRECT_LIGHT_SLOT).toBe(80);
+        expect(DIRECT_LIGHT_SLOT_LAYOUT.byteSize).toBe(80);
+        expect(DIRECT_LIGHT_SLOT_LAYOUT.shadowByteOffset).toBe(68);
       });
     });
 

package/src/__tests__/propagate-transforms.dawn.test.ts

@@ -5,13 +5,12 @@
 // Environment: node + setupFiles ./vitest.setup-webgpu.ts injects
 //   globalThis.navigator.gpu (provided by dawn.node native binding).
 //
-// feat-20260601 M4: GlobalTransform is retired. propagateTransforms now writes
-// the resolved world mat4 into the `Transform.world` column (column-major 16
-// floats). Tests read that column via the ECS array view and assert the
-// translation column (m[12,13,14]).
+// The derived world mat4 lives in the paired `GlobalTransform.world` column
+// (column-major 16 floats). Tests read that column via the ECS array view and
+// assert the translation column (m[12,13,14]).
 //
 // Scope (w6 acceptanceCheck):
-//   (a) root-only entity: Transform.world translation = local translation
+//   (a) root-only entity: GlobalTransform.world translation = local translation
 //   (b) 2-level hierarchy: child.world = parent.world x child local
 //   (c) stale ChildOf ref: Result.err(RhiError({ code: 'hierarchy-broken' }))
 //   (d) N=3 deep chain: composition stacks correctly
@@ -24,7 +23,7 @@
 import type { EntityHandle } from '@forgeax/engine-ecs';
 import { World } from '@forgeax/engine-ecs';
 import { readRenderArrayView } from '@forgeax/engine-ecs/projection';
-import { ChildOf, propagateTransforms, Transform } from '@forgeax/engine-scene';
+import { ChildOf, GlobalTransform, propagateTransforms, Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
 import { TileLayer, Tilemap } from '../../../render/src/components';
 
@@ -36,16 +35,17 @@ function identityTransformData() {
   };
 }
 
-// Read the resolved world mat4 (column-major 16 floats) from the Transform
-// world column array view. Translation lives in column 3 (m[12,13,14]).
+// Read the resolved world mat4 (column-major 16 floats) from the
+// GlobalTransform world column array view. Translation lives in column 3
+// (m[12,13,14]).
 function worldOf(world: World, entity: EntityHandle): Float32Array {
-  const view = readRenderArrayView(world, entity, Transform, 'world');
-  if (view === undefined) throw new Error('Transform.world view missing');
+  const view = readRenderArrayView(world, entity, GlobalTransform, 'world');
+  if (view === undefined) throw new Error('GlobalTransform.world view missing');
   return view as Float32Array;
 }
 
 describe('propagate-transforms.dawn - root-down DFS + stale ChildOf fail-fast (AC-04)', () => {
-  it('root entity: Transform.world translation = local translation (identity chain)', () => {
+  it('root entity: GlobalTransform.world translation = local translation (identity chain)', () => {
     const world = new World();
     const root = world
       .spawn({
@@ -153,7 +153,7 @@ describe('propagate-transforms.dawn - root-down DFS + stale ChildOf fail-fast (A
 
   // AC-07 (tweak-20260714-tilemap-layer-childed-render-entities M5): TileLayer
   // as an identity middle node must be transparent to propagateTransforms -- the
-  // layer's Transform.world (16 f32) must equal its Tilemap parent's world mat4
+  // layer's GlobalTransform.world (16 f32) must equal its Tilemap parent's world mat4
   // byte-for-byte. This proves M1's coAttach injection produces a genuinely
   // identity TRS (pos=[0,0,0], quat=[0,0,0,1], scale=[1,1,1]) and the compose
   // (parent.world x identity) is a no-op in mat4 form.
@@ -165,7 +165,7 @@ describe('propagate-transforms.dawn - root-down DFS + stale ChildOf fail-fast (A
   // asserted here because the M1 contract is precisely "identity default,
   // callers may override" -- the interesting invariant is transparency in the
   // default case.
-  it('AC-07: identity TileLayer middle node -> Transform.world byte-identical to Tilemap parent', () => {
+  it('AC-07: identity TileLayer middle node -> GlobalTransform.world byte-identical to Tilemap parent', () => {
     const world = new World();
     for (const component of [ChildOf, TileLayer, Tilemap, Transform]) {
       world.components.register(component).unwrap();
@@ -189,9 +189,8 @@ describe('propagate-transforms.dawn - root-down DFS + stale ChildOf fail-fast (A
         },
       )
       .unwrap();
-    // TileLayer carries an explicit identity Transform in the current ECS
-    // component vocabulary. This mirrors the demo spawn pattern in
-    // apps/hello/tilemap/** and keeps the hierarchy contract explicit.
+    // TileLayer carries an identity Transform; the generic Transform requirement
+    // materializes its GlobalTransform world column at the structural boundary.
     const layer = world
       .spawn(
         {

package/src/__tests__/record-worldid-isolation.test.ts

@@ -6,10 +6,11 @@
 //
 // Anchors:
 //   plan-tasks.json m2 (patch assignment)
-//   plan-strategy D-1a #1 (instanceBuffers positive half) and #3 (instancesBgPerEntity)
+//   plan-strategy D-1a #1 (instanceBuffers positive half); bind groups are now
+//   shared by opaque buffer handles after the probe/identity layout split.
 //   requirements AC-07
 //
-// The 13 sites under test (plus 2 read-side instancesBgPerEntity reads) are
+// The production instance-buffer sites and the shared bind-group resolver are
 // located by their stable cache operation below; source line numbers are not
 // part of the contract and must not make this gate stale after extraction.
 //
@@ -29,7 +30,7 @@ import { describe, expect, it } from 'vitest';
  * Verify that a cache site uses a worldEntityKey composite key.
  * Scans the source file around the given line (within a window) for both
  * `worldEntityKey` and the cache operation (`targetPattern` such as
- * `instanceBuffers.get`, `instancesBgPerEntity` as second arg, etc.).
+ * `instanceBuffers.get`, etc.).
  */
 function expectWorldEntityKeyAt(
   filePath: string,
@@ -95,19 +96,16 @@ describe('production-path geometry instanceBuffers worldEntityKey', () => {
   });
 });
 
-// ── Sprite identity BG instancesBgPerEntity (D-1a #3) ──────────────────────
-
 const SPRITE_FILE = fileURLToPath(
   new URL('../../../render/src/record/main-pass-sprite-draws.ts', import.meta.url),
 );
 
-describe('production-path sprite identity instancesBgPerEntity worldEntityKey', () => {
-  it('identityInstBg entityKey uses worldEntityKey', () => {
-    expectWorldEntityKeyAt(
-      SPRITE_FILE,
-      findLine(SPRITE_FILE, 'frameState.instancesBgPerEntity', 0),
-      'main-pass-sprite-draws instancesBgPerEntity write',
-    );
+describe('production-path shared instance bind-group resolver', () => {
+  it('sprite identity and sprite-instance paths use the shared resolver', () => {
+    const src = readFileSync(SPRITE_FILE, 'utf8');
+    expect(src).toContain('const identityInstBg = resolveGeometryInstancesBindGroup(');
+    expect(src).toContain('const spriteInstBg = resolveGeometryInstancesBindGroup(');
+    expect(src).toContain('const spriteInstancesBg = resolveGeometryInstancesBindGroup(');
   });
 });
 
@@ -131,18 +129,6 @@ describe('production-path sprite Instances instanceBuffers worldEntityKey', () =
   });
 });
 
-// ── Sprite pass instancesBgPerEntity (D-1a #3) ─────────────────────────────
-
-describe('production-path sprite pass instancesBgPerEntity worldEntityKey', () => {
-  it('spriteInstancesBg entityKey write uses worldEntityKey', () => {
-    expectWorldEntityKeyAt(
-      SPRITE_FILE,
-      findLine(SPRITE_FILE, 'frameState.instancesBgPerEntity', 1),
-      'main-pass-sprite-draws sprite pass instancesBgPerEntity write',
-    );
-  });
-});
-
 // ── SpriteInstances instanceBuffers (D-1a #1) ──────────────────────────────
 
 describe('production-path SpriteInstances instanceBuffers worldEntityKey', () => {
@@ -197,15 +183,13 @@ describe('production-path shadow instanceBuffers worldEntityKey', () => {
   });
 });
 
-// ── Shadow pass instancesBgPerEntity (D-1a #3) ─────────────────────────────
-
-describe('production-path shadow instancesBgPerEntity worldEntityKey', () => {
-  it('shadowInstancesBg entityKey write uses worldEntityKey', () => {
-    expectWorldEntityKeyAt(
-      SHADOW_FILE,
-      findLine(SHADOW_FILE, 'c.frameState.instancesBgPerEntity', 0),
-      'shadow-pass instancesBgPerEntity write',
+describe('production-path shadow shared instance bind-group resolver', () => {
+  it('shadow pass resolves the bind group from the world-aware buffer cache', () => {
+    const src = readFileSync(SHADOW_FILE, 'utf8');
+    expect(src).toContain(
+      'const shadowInstancesBg = resolveGeometryInstancesBindGroup(c, shadowInstanceBuffer);',
     );
+    expect(src).toContain('worldEntityKey(entry.source.worldId, shadowInst.cacheKey)');
   });
 });
 

package/src/__tests__/render-error-exhaustive.test-d.ts

@@ -128,6 +128,7 @@ function exhaustiveSwitchOnRenderCode(code: RenderErrorCode): string {
       return code;
     case 'points-lines-prepare-failed':
       return code;
+    case 'light-resource-unavailable':
     case 'projector-binding-failed':
       return code;
     case 'volume-owner-conflict':
@@ -392,6 +393,15 @@ function narrowRenderError(err: RenderError): void {
       void err.detail.owner;
       void err.detail.generation;
       break;
+    case 'light-resource-unavailable':
+      void err.detail.entity;
+      void err.detail.feature;
+      void err.detail.generation;
+      void err.detail.sourceKey;
+      void err.detail.reason;
+      void err.expected;
+      void err.hint;
+      break;
     case 'transmission-capability-missing':
       void err.detail.material;
       void err.detail.capability;

package/src/__tests__/render-system-extract.test.ts

@@ -40,22 +40,22 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
 {
   // w9 -- render-system-extract consumer migration unit tests (M3, AC-07 / AC-15).
   //
-  // Post-migration extract reads the single resolved `Transform.world` mat4
+  // Post-migration extract reads the single resolved `GlobalTransform.world` mat4
   // (written by propagateTransforms) for every world-space consumer; the legacy
   // GlobalTransform-column-switch + per-snapshot `mat4.compose` are gone.
   //
   // Five consumer classes covered:
   //   1. mesh-walk     -> RenderableSnapshot.transform.world is the 16-float
   //      column-major world mat4 (parent x child), copied straight from the
-  //      Transform.world view; no per-snapshot compose.
+  //      GlobalTransform.world view; no per-snapshot compose.
   //   2. frustum cull  -> the cull AABB follows the world mat4 (a child placed
   //      off-screen by its parent is culled; in-screen is kept) -- same-source
   //      with the rendered world (AC-05 carried forward).
   //   3. camera view   -> CameraSnapshot.position is the world-space translation
-  //      (mat4.getTranslation of Transform.world); a child camera reflects
+  //      (mat4.getTranslation of GlobalTransform.world); a child camera reflects
   //      parent x child.
   //   4. light position -> point / spot light position is the world-space
-  //      translation extracted from Transform.world (mat4.getTranslation).
+  //      translation extracted from GlobalTransform.world (mat4.getTranslation).
   //   5. AC-15 zero-materialization -> the mesh-walk reads world through the
   //      column-level array view; it does NOT call `world.get` per renderable
   //      to materialize a `{}` whole-component object.
@@ -209,7 +209,7 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
       expect(w?.[12]).toBeCloseTo(12, 5);
       expect(w?.[13]).toBeCloseTo(3, 5);
       expect(w?.[14]).toBeCloseTo(0, 5);
-      // The snapshot world must equal the entity's Transform.world column byte-for-byte.
+      // The snapshot world must equal the entity's GlobalTransform.world column byte-for-byte.
     });
 
     it('mesh-walk: flat root world mat4 equals compose(local)', () => {

package/src/__tests__/render-system-record-multi-material-textureview.test.ts

@@ -291,6 +291,7 @@ async function importEcs(): Promise<{
 
 async function importComponents(): Promise<{
   Transform: unknown;
+  GlobalTransform: unknown;
   MeshFilter: unknown;
   MeshRenderer: unknown;
   Camera: unknown;

package/src/__tests__/render-system-record-per-submesh-transparency.test.ts

@@ -232,6 +232,7 @@ async function importEcs(): Promise<{
 }
 async function importComponents(): Promise<{
   Transform: unknown;
+  GlobalTransform: unknown;
   MeshFilter: unknown;
   MeshRenderer: unknown;
   Camera: unknown;

package/src/__tests__/renderer-surface.unit.test.ts

@@ -180,8 +180,6 @@ function makeFrameState(): MockObj {
     transientInstanceBuffers: [],
     warnedZeroLightStandard: false,
     warnedMultiLightDirectional: false,
-    warnedMultiLightPoint: false,
-    warnedMultiLightSpot: false,
     warnedSkyboxTonemapNone: false,
     warnedMissingBaseColorTextureHandles: new Set<number>(),
     warnedNineSliceScaleEntities: new Set<number>(),