@forgeax/engine-runtime 0.1.20 → 0.1.23

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

@@ -10,7 +10,21 @@
 // This file is scoped to the 'browser' vitest project (file-naming convention
 // *.browser.test.ts); the 'dawn' and 'unit' projects exclude it.
 
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import {
+  Camera,
+  DirectionalLight,
+  Materials,
+  MeshFilter,
+  MeshRenderer,
+  PointLight,
+  PointLightShadow,
+} from '@forgeax/engine-render';
+import { propagateTransforms, Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
+import { page } from 'vitest/browser';
+import { constructRuntimeRendererHost } from '../renderer-host';
 
 // WebGPU bitmask constants per spec (avoids needing @webgpu/types globals
 // in the runtime tsconfig). Values are stable across implementations.
@@ -192,87 +206,199 @@ describe('M0 cube_array comparison sampler (browser)', () => {
   });
 });
 
-// feat-20260612-point-light-shadows-urp-hdrp M3 / T-M3-6 (AC-14 URP path).
-//
-// URP-end-to-end pixel-readback assertion: spawn PointLight + PointLightShadow
-// + occluder + ground plane, run one frame, read back swap-chain pixels, and
-// assert the occluded fragment is darker than a non-occluded reference
-// fragment.
-//
-// Round-2 status (feat-20260612 Round-2 commit-B + commit-C): the BGL
-// hookup landed -- POINT_SHADOW_AVAILABLE is registered at all 3
-// vite-plugin-shader define sites, the runtime PBR view BGL emits
-// always-on bindings 5 (cube_array depth atlas) + 6 (shadowParams UBO 64 B),
-// and recordPointShadowPass walks validated entries with real drawIndexed
-// calls + per-face VP write to viewUniformBuffer.lightSpaceMatrix. The
-// shadowParams UBO is written per frame in record-stage with
-// (near, far, 1/(far-near), 0) per shadow-casting snapshot.
-//
-// What remains for this `it.skip` to flip to `it`: the full
-// createRenderer + canvas + readPixels + scene scaffolding (mirror of
-// `light-casters-9-light.browser.test.ts` shape: spawnCamera + spawn
-// occluder cube + spawn ground plane + spawnPointAt + spawnPointShadow
-// + driving FRAMES_PER_SCENE rAF ticks + sampleBlockAverage at occluded
-// vs free sample sites). The wiring is unblocked at the engine layer; the
-// scope of writing the test fixture itself + tuning the lighting setup so
-// occluded < non-occluded reliably under chromium headless presentation
-// timing exceeds Round-2 fix-up budget. Tracked as a sub-followup
-// (feat-followup-point-shadow-browser-readback) per implement-decisions.md.
-describe('URP point shadow pixel readback (browser, T-M3-6 / AC-14)', () => {
-  it.skip('occluded fragment darker than non-occluded -- BGL hookup landed in Round-2; full createRenderer + readPixels scaffolding deferred', () => {
-    // Pseudocode for the assertion the runnable test will make once the
-    // hookup lands:
-    //
-    //   const renderer = createRenderer(canvas, { ... });
-    //   const world = new World();
-    //   world.spawn({ component: Transform, data: {...} },
-    //               { component: PointLight, data: {...} },
-    //               { component: PointLightShadow, data: {} });
-    //   // ... ground plane + occluder ...
-    //   renderer.draw(world);
-    //   const px = await readback(canvas, occludedX, occludedY);
-    //   const py = await readback(canvas, freeX, freeY);
-    //   expect(px.r + px.g + px.b).toBeLessThan(py.r + py.g + py.b);
-    //   expect(py.r + py.g + py.b).toBeGreaterThan(0); // non-black frame
-  });
-});
+// feat-20260612-point-light-shadows-urp-hdrp M5 / AC-24 focused consumer.
+// This is a real Standard createRenderer path rather than a cube-array-only
+// primitive: the same caster/receiver scene is rendered with and without the
+// PointLightShadow component, then the canvas pixels and renderer pass facts
+// are checked together.
+const browserReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+const REAL_CANVAS_SIZE = 96;
 
-// feat-20260612-point-light-shadows-urp-hdrp M4 / T-M4-6 (AC-14 HDRP path).
-//
-// HDRP-end-to-end pixel-readback assertion: createRenderer with HDRP pipeline
-// installed -> spawn PointLight + PointLightShadow + occluder + ground ->
-// renderFrame -> readback pixels. Assert occluded < non-occluded brightness
-// AND non-black frame.
-//
-// Round-2 status (feat-20260612 Round-2 commit-B + commit-C): the BGL
-// hookup landed for both URP and HDRP -- the shared `pbr-view-bgl` declares
-// always-on bindings 5 + 6 (HDRP rides binding 5 only; HDRP gets the
-// (near, far) pair via LightSlot.kind_and_pad.zw per plan-strategy D-8),
-// and hdrp-cluster-forward.wgsl now imports shadowAtlas + shadowSampler
-// from common.wgsl under the POINT_SHADOW_AVAILABLE ifdef so naga_oil
-// resolves the free identifiers. recordPointShadowPass writes real depth
-// values to the cube atlas faces.
-//
-// What remains for this `it.skip` to flip to `it`: same as the URP test --
-// the full createRenderer + canvas + readPixels + scene scaffolding,
-// additionally with `installPipeline(hdrpAsset)` to drive the HDRP path.
-// Tracked under the same sub-followup (feat-followup-point-shadow-browser-readback).
-describe('HDRP point shadow pixel readback (browser, T-M4-6 / AC-14)', () => {
-  it.skip('occluded fragment darker than non-occluded -- BGL hookup landed in Round-2; full createRenderer + readPixels + HDRP install scaffolding deferred', () => {
-    // Pseudocode for the assertion the runnable test will make once the
-    // hookup lands:
-    //
-    //   const renderer = createRenderer(canvas, { ... });
-    //   renderer.installPipeline(hdrpAsset);  // forgeax::hdrp
-    //   const world = new World();
-    //   world.spawn({ component: Transform, data: {...} },
-    //               { component: PointLight, data: {...} },
-    //               { component: PointLightShadow, data: {} });
-    //   // ... ground plane + occluder ...
-    //   renderer.draw(world);
-    //   const px = await readback(canvas, occludedX, occludedY);
-    //   const py = await readback(canvas, freeX, freeY);
-    //   expect(px.r + px.g + px.b).toBeLessThan(py.r + py.g + py.b);
-    //   expect(py.r + py.g + py.b).toBeGreaterThan(0); // non-black frame
-  });
-});
+function spawnPointShadowScene(world: World, withShadow: boolean): void {
+  const material = world.allocSharedRef(
+    'MaterialAsset',
+    Materials.standard({
+      baseColor: [0.78, 0.26, 0.08, 1],
+      metallic: 0,
+      roughness: 0.45,
+    }),
+  );
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 0], scale: [1.3, 1.3, 1.3] } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: { materials: [material] } },
+    )
+    .unwrap();
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, -1.65, 0], scale: [3.5, 0.15, 3.5] } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: { materials: [material] } },
+    )
+    .unwrap();
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 6] } },
+      { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 50 } },
+    )
+    .unwrap();
+  world
+    .spawn({
+      component: DirectionalLight,
+      data: { direction: [-0.4, -0.8, -1], intensity: 0.35, castShadow: false },
+    })
+    .unwrap();
+  const point = [1.8, 2.6, 2.2] as const;
+  world
+    .spawn(
+      { component: Transform, data: { pos: point } },
+      { component: PointLight, data: { color: [1, 0.72, 0.4], intensity: 22, range: 12 } },
+      ...(withShadow
+        ? [{ component: PointLightShadow, data: { mapSize: 256, nearPlane: 0.1, farPlane: 25 } }]
+        : []),
+    )
+    .unwrap();
+
+  // The standalone renderer host does not install scenePlugin for this
+  // fixture. Publish world-space matrices before extract so the pixel proof
+  // exercises the actual caster/receiver scene instead of the clear colour.
+  propagateTransforms(world).unwrap();
+}
+
+async function waitForPresentedPixels(canvas: HTMLCanvasElement): Promise<Uint8Array> {
+  let latest = new Uint8Array(REAL_CANVAS_SIZE * REAL_CANVAS_SIZE * 4);
+  for (let attempt = 0; attempt < 6; attempt += 1) {
+    await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+    await new Promise<void>((resolve) => setTimeout(resolve, 25));
+    // CDP-backed element screenshots read the compositor surface directly;
+    // createImageBitmap(canvas) can race swap-chain presentation in headless
+    // Chromium and return an all-zero opaque surface.
+    const shot = await page.elementLocator(canvas).screenshot({ base64: true, save: false });
+    const b64 = typeof shot === 'string' ? shot : shot.base64;
+    const binary = atob(b64);
+    const encoded = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+      encoded[index] = binary.charCodeAt(index);
+    }
+    const bitmap = await createImageBitmap(new Blob([encoded], { type: 'image/png' }));
+    const surface = new OffscreenCanvas(bitmap.width, bitmap.height);
+    const context = surface.getContext('2d', { willReadFrequently: true });
+    if (context === null) {
+      bitmap.close();
+      throw new Error('point-shadow browser test: canvas readback context unavailable');
+    }
+    context.drawImage(bitmap, 0, 0);
+    const image = context.getImageData(0, 0, bitmap.width, bitmap.height);
+    bitmap.close();
+    latest = new Uint8Array(image.data);
+    let nonBlack = false;
+    for (let index = 0; index < latest.length; index += 4) {
+      if ((latest[index] ?? 0) + (latest[index + 1] ?? 0) + (latest[index + 2] ?? 0) > 0) {
+        nonBlack = true;
+        break;
+      }
+    }
+    if (nonBlack) return latest;
+  }
+  return latest;
+}
+
+function pixelLuma(pixels: Uint8Array): number {
+  let sum = 0;
+  for (let index = 0; index < pixels.length; index += 4) {
+    sum += (pixels[index] ?? 0) + (pixels[index + 1] ?? 0) + (pixels[index + 2] ?? 0);
+  }
+  return sum / (pixels.length / 4);
+}
+
+function pixelDifference(a: Uint8Array, b: Uint8Array): number {
+  let difference = 0;
+  for (let index = 0; index < Math.min(a.length, b.length); index += 4) {
+    difference += Math.abs((a[index] ?? 0) - (b[index] ?? 0));
+    difference += Math.abs((a[index + 1] ?? 0) - (b[index + 1] ?? 0));
+    difference += Math.abs((a[index + 2] ?? 0) - (b[index + 2] ?? 0));
+  }
+  return difference;
+}
+
+it.skipIf(!browserReady)(
+  'Standard point-shadow scene differs from its no-shadow baseline',
+  async () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = REAL_CANVAS_SIZE;
+    canvas.height = REAL_CANVAS_SIZE;
+    canvas.style.width = `${REAL_CANVAS_SIZE}px`;
+    canvas.style.height = `${REAL_CANVAS_SIZE}px`;
+    document.body.appendChild(canvas);
+    let renderer: import('@forgeax/engine-render').Renderer | undefined;
+    try {
+      const host = await constructRuntimeRendererHost(
+        canvas,
+        {},
+        { shaderManifestUrl: '/shaders/manifest.json' },
+      );
+      if (!host.ok) throw host.error;
+      renderer = host.value.renderer;
+      const errors: string[] = [];
+      const unsubscribe = renderer.subscribe((event) => {
+        if (event.kind === 'error') errors.push(event.error.code);
+      });
+
+      const shadowWorld = new World();
+      spawnPointShadowScene(shadowWorld, true);
+      const shadowAttachment = renderer.attach(shadowWorld);
+      expect(shadowAttachment.ok).toBe(true);
+      if (!shadowAttachment.ok) throw shadowAttachment.error;
+      for (let frame = 0; frame < 6; frame += 1) {
+        shadowWorld.update(1 / 60).unwrap();
+        const drawn = renderer.draw({
+          leases: [shadowAttachment.value],
+          camera: { lease: shadowAttachment.value },
+          environment: { lease: shadowAttachment.value },
+        });
+        expect(drawn.ok).toBe(true);
+        if (!drawn.ok) throw drawn.error;
+      }
+      const shadowPixels = await waitForPresentedPixels(canvas);
+      const shadowInspection = renderer.inspect();
+      expect(shadowInspection.pointShadow?.status).toBe('ready');
+      expect(shadowInspection.pointShadow?.requested).toBe(1);
+      expect(shadowInspection.pointShadow?.admitted).toBe(1);
+      expect(
+        shadowInspection.perFramePassNames.filter((name) => name.startsWith('point-shadow-')),
+      ).toHaveLength(6);
+
+      const noShadowWorld = new World();
+      spawnPointShadowScene(noShadowWorld, false);
+      const noShadowAttachment = renderer.attach(noShadowWorld);
+      expect(noShadowAttachment.ok).toBe(true);
+      if (!noShadowAttachment.ok) throw noShadowAttachment.error;
+      for (let frame = 0; frame < 6; frame += 1) {
+        noShadowWorld.update(1 / 60).unwrap();
+        const drawn = renderer.draw({
+          leases: [noShadowAttachment.value],
+          camera: { lease: noShadowAttachment.value },
+          environment: { lease: noShadowAttachment.value },
+        });
+        expect(drawn.ok).toBe(true);
+        if (!drawn.ok) throw drawn.error;
+      }
+      const noShadowPixels = await waitForPresentedPixels(canvas);
+      const noShadowInspection = renderer.inspect();
+      expect(noShadowInspection.pointShadow?.status).toBe('inactive');
+      expect(
+        noShadowInspection.perFramePassNames.filter((name) => name.startsWith('point-shadow-')),
+      ).toHaveLength(0);
+      expect(pixelLuma(shadowPixels)).toBeGreaterThan(0);
+      expect(pixelLuma(noShadowPixels)).toBeGreaterThan(0);
+      expect(pixelDifference(shadowPixels, noShadowPixels)).toBeGreaterThan(0);
+      expect(errors).toEqual([]);
+      unsubscribe();
+    } finally {
+      if (renderer !== undefined) await renderer.dispose();
+      canvas.remove();
+    }
+  },
+  60_000,
+);

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

@@ -19,9 +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,
+  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 {
@@ -164,8 +164,8 @@ function spawnValidatedPointShadow(
           expect(r.error).toBeInstanceOf(ShadowInvalidConfigError);
           const detail = (r.error as unknown as ShadowInvalidConfigError).detail;
           expect(detail.field).toBe('mapSize');
-          expect(detail.value).toBe(0);
-          expect(detail.min).toBe(1);
+          expect(detail.actual).toBe(0);
+          expect(detail.bound).toEqual({ kind: 'lower-bound', operator: '>=', value: 1 });
           // .expected and .hint carry actionable strings
           expect((r.error as unknown as ShadowInvalidConfigError).expected).toContain('mapSize');
           expect((r.error as unknown as ShadowInvalidConfigError).hint).toContain('mapSize');
@@ -190,8 +190,8 @@ function spawnValidatedPointShadow(
           expect(r.error).toBeInstanceOf(ShadowInvalidConfigError);
           const detail = (r.error as unknown as ShadowInvalidConfigError).detail;
           expect(detail.field).toBe('farPlane');
-          expect(detail.value).toBe(0.5);
-          expect(detail.min).toBe(1.0);
+          expect(detail.actual).toBe(0.5);
+          expect(detail.bound).toEqual({ kind: 'lower-bound', operator: '>=', value: 1.0 });
         }
       });
 
@@ -550,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),
@@ -558,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,
@@ -595,30 +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);
-      });
-
-      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);
+        expect(i32[17]).toBe(-1);
+      });
+
+      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)');
   });
 });