@forgeax/engine-runtime 0.1.7 → 0.1.20

package/src/__tests__/shadow-fields-observable.dawn.test.ts

@@ -33,6 +33,11 @@ const WIDTH = 256;
 const HEIGHT = 256;
 const BPR = Math.ceil((WIDTH * 4) / 256) * 256;
 
+// Each falsifier performs four fresh 256x256 Dawn readbacks. Windows' Dawn
+// prebuild can exceed Vitest's 90-second bound for that sequence while still
+// completing well inside the nightly platform job's 45-minute budget.
+const SHADOW_FIELDS_FALSIFIER_TIMEOUT_MS = 300_000;
+
 const ENGINE_MANIFEST = await (async () => {
   const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
   return buildEngineShaderManifest();
@@ -582,45 +587,57 @@ describe('M6 shadow fields observability', () => {
   // (physically removing the UBO write), comment out the matching
   // `viewPayload[126|127|128] = ...` line in render-system-record.ts and re-run
   // the corresponding `varied` leg — its diff collapses to 0, matching `held`.
-  it('falsification: depthBias varied differs, held does not (signal attributable to the field)', async () => {
-    if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') return;
-    const varied = diff(
-      await renderConfig(true, 0.0, 0.05, 3),
-      await renderConfig(true, 0.5, 0.05, 3),
-    );
-    const held = diff(
-      await renderConfig(true, 0.0, 0.05, 3),
-      await renderConfig(true, 0.0, 0.05, 3),
-    );
-    expect(varied.diff).toBeGreaterThan(0);
-    expect(held.diff).toBe(0);
-  }, 90000);
+  it(
+    'falsification: depthBias varied differs, held does not (signal attributable to the field)',
+    async () => {
+      if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') return;
+      const varied = diff(
+        await renderConfig(true, 0.0, 0.05, 3),
+        await renderConfig(true, 0.5, 0.05, 3),
+      );
+      const held = diff(
+        await renderConfig(true, 0.0, 0.05, 3),
+        await renderConfig(true, 0.0, 0.05, 3),
+      );
+      expect(varied.diff).toBeGreaterThan(0);
+      expect(held.diff).toBe(0);
+    },
+    SHADOW_FIELDS_FALSIFIER_TIMEOUT_MS,
+  );
 
-  it('falsification: normalBias varied differs, held does not', async () => {
-    if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') return;
-    const varied = diff(
-      await renderConfig(true, 0.005, 0.0, 3),
-      await renderConfig(true, 0.005, 0.5, 3),
-    );
-    const held = diff(
-      await renderConfig(true, 0.005, 0.0, 3),
-      await renderConfig(true, 0.005, 0.0, 3),
-    );
-    expect(varied.diff).toBeGreaterThan(0);
-    expect(held.diff).toBe(0);
-  }, 90000);
+  it(
+    'falsification: normalBias varied differs, held does not',
+    async () => {
+      if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') return;
+      const varied = diff(
+        await renderConfig(true, 0.005, 0.0, 3),
+        await renderConfig(true, 0.005, 0.5, 3),
+      );
+      const held = diff(
+        await renderConfig(true, 0.005, 0.0, 3),
+        await renderConfig(true, 0.005, 0.0, 3),
+      );
+      expect(varied.diff).toBeGreaterThan(0);
+      expect(held.diff).toBe(0);
+    },
+    SHADOW_FIELDS_FALSIFIER_TIMEOUT_MS,
+  );
 
-  it('falsification: pcfKernelSize varied differs, held does not', async () => {
-    if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') return;
-    const varied = diff(
-      await renderConfig(true, 0.005, 0.05, 1),
-      await renderConfig(true, 0.005, 0.05, 5),
-    );
-    const held = diff(
-      await renderConfig(true, 0.005, 0.05, 1),
-      await renderConfig(true, 0.005, 0.05, 1),
-    );
-    expect(varied.diff).toBeGreaterThan(0);
-    expect(held.diff).toBe(0);
-  }, 90000);
+  it(
+    'falsification: pcfKernelSize varied differs, held does not',
+    async () => {
+      if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') return;
+      const varied = diff(
+        await renderConfig(true, 0.005, 0.05, 1),
+        await renderConfig(true, 0.005, 0.05, 5),
+      );
+      const held = diff(
+        await renderConfig(true, 0.005, 0.05, 1),
+        await renderConfig(true, 0.005, 0.05, 1),
+      );
+      expect(varied.diff).toBeGreaterThan(0);
+      expect(held.diff).toBe(0);
+    },
+    SHADOW_FIELDS_FALSIFIER_TIMEOUT_MS,
+  );
 });

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

@@ -0,0 +1,385 @@
+// Real Dawn regression for the static/skinned shadow pipeline transition.
+//
+// The static shadow path uses the canonical all-true variant key (`''`) while
+// the skinned path uses an explicit negative skinning axis.  Keep both entries
+// in one production render so the pipeline layout and group-2 bind group must
+// change at the same command-recording boundary.
+
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import type { Renderer } from '@forgeax/engine-render';
+import { Camera, DirectionalLight, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import { Skin } from '@forgeax/engine-skinning';
+import type { Handle, MaterialAsset, MeshAsset, SkeletonAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { constructRuntimeRendererHost } from '../renderer-host';
+import { drawPublished } from './draw-published';
+
+const WIDTH = 384;
+const HEIGHT = 256;
+const BYTES_PER_ROW = Math.ceil((WIDTH * 4) / 256) * 256;
+const TEXTURE_USAGE_COPY_SRC = 0x01;
+const TEXTURE_USAGE_RENDER_ATTACHMENT = 0x10;
+const BUFFER_USAGE_MAP_READ = 0x0001;
+const BUFFER_USAGE_COPY_DST = 0x0008;
+const MAP_MODE_READ = 0x0001;
+
+const ENGINE_MANIFEST = await (async () => {
+  const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
+  return buildEngineShaderManifest();
+})();
+const ENGINE_MANIFEST_URL = `data:application/json,${encodeURIComponent(
+  JSON.stringify(ENGINE_MANIFEST),
+)}`;
+
+type MixedCapture = {
+  readonly pixels: Uint8Array;
+  readonly errors: readonly string[];
+};
+
+function staticMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
+  return world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+    kind: 'material',
+    passes: [
+      {
+        name: 'Forward',
+        program: { module: 'forgeax::default-standard-pbr' },
+        renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+      },
+      {
+        name: 'ShadowCaster',
+        program: { module: 'forgeax::default-shadow-caster' },
+        renderState: {
+          tags: { LightMode: 'ShadowCaster' },
+          passKind: 'shadow-caster',
+        },
+      },
+    ],
+    values: {
+      baseColor: [0.8, 0.35, 0.15, 1],
+      metallic: 0.1,
+      roughness: 0.55,
+      emissive: [0, 0, 0],
+      emissiveIntensity: 0,
+      occlusionStrength: 1,
+    },
+  });
+}
+
+function skinnedMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
+  return world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+    kind: 'material',
+    passes: [
+      {
+        name: 'Forward',
+        program: { module: 'forgeax::pbr-skin' },
+        renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+      },
+      {
+        name: 'ShadowCaster',
+        program: { module: 'forgeax::default-shadow-caster' },
+        renderState: {
+          tags: { LightMode: 'ShadowCaster' },
+          passKind: 'shadow-caster',
+        },
+      },
+    ],
+    values: {
+      baseColor: [0.15, 0.45, 0.9, 1],
+      metallic: 0.1,
+      roughness: 0.55,
+      emissive: [0, 0, 0],
+      emissiveIntensity: 0,
+      occlusionStrength: 1,
+    },
+  });
+}
+
+function floorMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
+  return world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+    kind: 'material',
+    passes: [
+      {
+        name: 'Forward',
+        program: { module: 'forgeax::default-standard-pbr' },
+        renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+      },
+    ],
+    values: {
+      baseColor: [0.75, 0.75, 0.75, 1],
+      metallic: 0,
+      roughness: 0.9,
+      emissive: [0, 0, 0],
+      emissiveIntensity: 0,
+      occlusionStrength: 1,
+    },
+  });
+}
+
+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,
+  ]);
+  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]),
+    },
+    aabb: new Float32Array([-0.75, 0, 0, 0.75, 1.2, 0]),
+    materialSlots: [{ slotName: 'Default' }],
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: 3,
+        vertexCount: 3,
+        materialSlot: 0,
+        topology: 'triangle-list',
+      },
+    ],
+  });
+}
+
+function skeleton(world: World): Handle<'SkeletonAsset', 'shared'> {
+  const inverseBindMatrices = new Float32Array(16);
+  inverseBindMatrices[0] = 1;
+  inverseBindMatrices[5] = 1;
+  inverseBindMatrices[10] = 1;
+  inverseBindMatrices[15] = 1;
+  return world.allocSharedRef<'SkeletonAsset', SkeletonAsset>('SkeletonAsset', {
+    kind: 'skeleton',
+    inverseBindMatrices,
+    jointCount: 1,
+  });
+}
+
+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 {
+  const staticMat = staticMaterial(world);
+  const skinMat = skinnedMaterial(world);
+  const floorMat = floorMaterial(world);
+  const skinMesh = skinnedMesh(world);
+  const skinSkeleton = skeleton(world);
+
+  world.spawn(
+    { component: Transform, data: { ...identityTransform([0, 5, 5]), scale: [10, 0.1, 10] } },
+    { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+    { component: MeshRenderer, data: { materials: [floorMat] } },
+  );
+  world.spawn(
+    { component: Transform, data: identityTransform([0, 8, 18]) },
+    {
+      component: Camera,
+      data: {
+        fov: (45 * Math.PI) / 180,
+        aspect: WIDTH / HEIGHT,
+        near: 0.1,
+        far: 100,
+        clearColor: [0.02, 0.02, 0.03, 1],
+      },
+    },
+  );
+  world.spawn({
+    component: DirectionalLight,
+    data: {
+      direction: [0.25, -1, -0.45],
+      color: [1, 1, 1],
+      intensity: 1,
+      castShadow,
+      mapSize: 1024,
+      depthBias: 0.005,
+      normalBias: 0.05,
+      shadowDistance: 50,
+      pcfKernelSize: 3,
+    },
+  });
+
+  const spawnStaticCaster = (x: number): void => {
+    world.spawn(
+      { component: Transform, data: { ...identityTransform([x, 7, 5]), scale: [0.8, 0.8, 0.8] } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: { materials: [staticMat] } },
+    );
+  };
+  // 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]),
+      },
+    },
+  );
+  spawnStaticCaster(3);
+}
+
+async function readPixels(device: GPUDevice, texture: GPUTexture): Promise<Uint8Array> {
+  const buffer = device.createBuffer({
+    size: BYTES_PER_ROW * HEIGHT,
+    usage: BUFFER_USAGE_MAP_READ | BUFFER_USAGE_COPY_DST,
+  });
+  const encoder = device.createCommandEncoder();
+  encoder.copyTextureToBuffer(
+    { texture },
+    { buffer, bytesPerRow: BYTES_PER_ROW, rowsPerImage: HEIGHT },
+    { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+  );
+  device.queue.submit([encoder.finish()]);
+  await buffer.mapAsync(MAP_MODE_READ);
+  const pixels = new Uint8Array(buffer.getMappedRange().slice(0));
+  buffer.unmap();
+  buffer.destroy();
+  return pixels;
+}
+
+async function renderMixed(castShadow: boolean): Promise<MixedCapture> {
+  let device: GPUDevice | undefined;
+  let target: GPUTexture | undefined;
+  const originalRequestAdapter = globalThis.navigator.gpu.requestAdapter.bind(
+    globalThis.navigator.gpu,
+  );
+  globalThis.navigator.gpu.requestAdapter = async (options) => {
+    const adapter = await originalRequestAdapter(options);
+    if (adapter === null) return adapter;
+    const originalRequestDevice = adapter.requestDevice.bind(adapter);
+    adapter.requestDevice = async (descriptor) => {
+      const created = await originalRequestDevice(descriptor);
+      device ??= created;
+      return created;
+    };
+    return adapter;
+  };
+  const canvas = {
+    width: WIDTH,
+    height: HEIGHT,
+    getContext(kind: string): unknown {
+      if (kind !== 'webgpu') return null;
+      return {
+        configure(descriptor: { device: GPUDevice; format?: GPUTextureFormat }) {
+          target ??= descriptor.device.createTexture({
+            size: { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+            format: descriptor.format ?? 'rgba8unorm',
+            usage: TEXTURE_USAGE_RENDER_ATTACHMENT | TEXTURE_USAGE_COPY_SRC,
+            viewFormats: ['rgba8unorm-srgb'],
+          });
+        },
+        unconfigure() {},
+        getCurrentTexture(): GPUTexture {
+          if (target === undefined) throw new Error('render target requested before configure');
+          return target;
+        },
+      };
+    },
+    addEventListener() {},
+    removeEventListener() {},
+  } as unknown as HTMLCanvasElement;
+
+  let renderer: Renderer | undefined;
+  let unsubscribe: (() => void) | undefined;
+  const errors: string[] = [];
+  try {
+    const host = await constructRuntimeRendererHost(
+      canvas,
+      {},
+      {
+        shaderManifestUrl: ENGINE_MANIFEST_URL,
+      },
+    );
+    if (!host.ok) throw host.error;
+    renderer = host.value.renderer;
+    unsubscribe = renderer.subscribe((event) => {
+      if (event.kind === 'error') {
+        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 };
+  } finally {
+    globalThis.navigator.gpu.requestAdapter = originalRequestAdapter;
+    unsubscribe?.();
+    renderer?.dispose();
+    target?.destroy();
+    device?.destroy();
+  }
+}
+
+function regionDiff(a: Uint8Array, b: Uint8Array, x0: number, x1: number): number {
+  let changed = 0;
+  for (let y = Math.floor(HEIGHT * 0.32); y < HEIGHT; y += 1) {
+    for (let x = x0; x < x1; x += 1) {
+      const index = y * BYTES_PER_ROW + x * 4;
+      if (
+        Math.abs((a[index] ?? 0) - (b[index] ?? 0)) > 2 ||
+        Math.abs((a[index + 1] ?? 0) - (b[index + 1] ?? 0)) > 2 ||
+        Math.abs((a[index + 2] ?? 0) - (b[index + 2] ?? 0)) > 2
+      ) {
+        changed += 1;
+      }
+    }
+  }
+  return changed;
+}
+
+describe('mixed static/skinned shadow pipeline (Dawn)', () => {
+  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);
+    expect(shadow.errors).toEqual([]);
+    expect(baseline.errors).toEqual([]);
+    expect(shadow.pixels.length).toBeGreaterThan(0);
+    expect(baseline.pixels.length).toBe(shadow.pixels.length);
+
+    // Each caster owns a separate x-region. Comparing against the identical
+    // no-shadow scene proves the depth pass contributed in all three regions,
+    // rather than merely proving that a color frame was non-black.
+    const regions = [
+      [0, Math.floor(WIDTH / 3)],
+      [Math.floor(WIDTH / 3), Math.floor((2 * WIDTH) / 3)],
+      [Math.floor((2 * WIDTH) / 3), WIDTH],
+    ] as const;
+    for (const [x0, x1] of regions) {
+      expect(regionDiff(shadow.pixels, baseline.pixels, x0, x1)).toBeGreaterThan(0);
+    }
+  }, 120000);
+});

package/src/__tests__/sprite-cullmode-flip.dawn.test.ts

@@ -229,12 +229,11 @@ describe('feat-20260608 M2 m2-t5: sprite pipeline cullMode "none" lets H/V flipp
     const synth = buildSyntheticRgba();
     const synthPod = {
       kind: 'texture' as const,
-      width: synth.width,
-      height: synth.height,
+      shape: { viewDimension: '2d' as const, extent: { width: synth.width, height: synth.height } },
       format: 'rgba8unorm-srgb' as const,
       data: synth.data,
       colorSpace: 'srgb' as const,
-      mipmap: false,
+      mips: { kind: 'none' as const },
     };
     const textureHandle = worldFlip.allocSharedRef('TextureAsset', synthPod as never);
     const samplerHandle = worldFlip.allocSharedRef('SamplerAsset', {
@@ -382,12 +381,11 @@ describe('feat-20260608 M2 m2-t5: sprite pipeline cullMode "none" lets H/V flipp
     const synth = buildSyntheticRgba();
     const synthPod = {
       kind: 'texture' as const,
-      width: synth.width,
-      height: synth.height,
+      shape: { viewDimension: '2d' as const, extent: { width: synth.width, height: synth.height } },
       format: 'rgba8unorm-srgb' as const,
       data: synth.data,
       colorSpace: 'srgb' as const,
-      mipmap: false,
+      mips: { kind: 'none' as const },
     };
     const textureHandle = worldFlipBoth.allocSharedRef('TextureAsset', synthPod as never);
     const samplerHandle = worldFlipBoth.allocSharedRef('SamplerAsset', {

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

@@ -47,7 +47,7 @@ function makeSpec(shaderId: string): PipelineSpec {
 
 describe('sprite-lit BGL byte-identical to sprite (AC-07, w4/w5 close)', () => {
   describe('pbr-view BGL (light buffers; binding 1+2)', () => {
-    it('sprite-lit vs sprite share the same 10-entry pbr-view BGL under storage-buffer caps', () => {
+    it('sprite-lit vs sprite share the same 12-entry pbr-view BGL under storage-buffer caps', () => {
       const spriteSpec = makeSpec('forgeax::sprite');
       const spriteLitSpec = makeSpec('forgeax::sprite-lit');
       const sprite = buildBindGroupLayoutDescriptor(spriteSpec, {
@@ -59,7 +59,9 @@ describe('sprite-lit BGL byte-identical to sprite (AC-07, w4/w5 close)', () => {
         caps: { storageBuffer: true },
       });
       expect(JSON.stringify(spriteLit)).toBe(JSON.stringify(sprite));
-      expect(spriteLit.entries.length).toBe(10); // binding 10 is the shared Points/Lines view UBO
+      // binding 10 is the shared Points/Lines view UBO; bindings 11/12 are the
+      // optional SpotLight projector texture and sampler on capable devices.
+      expect(spriteLit.entries.length).toBe(12);
     });
 
     it('sprite-lit vs sprite share the same 10-entry pbr-view BGL under uniform fallback caps (AC-10)', () => {
@@ -118,24 +120,24 @@ describe('sprite-lit BGL byte-identical to sprite (AC-07, w4/w5 close)', () => {
   });
 
   describe('material BGL congruence (pbr-material-merged / unlit-material)', () => {
-    it('pbr-material-user-region entries are 13 (PBR layout reused by sprite & sprite-lit)', () => {
+    it('pbr-material-user-region entries are 17 (PBR layout reused by sprite & sprite-lit)', () => {
       // sprite + sprite-lit use the default standard-PBR user-region
-      // schema (5 user fields produce 7 BGL entries after std140 merge).
+      // schema (20 value fields + 8 texture fields produce 17 BGL entries).
       // Both share the same userRegion shape and therefore the same BGL.
       const base = buildPbrMaterialUserRegionEntries();
-      expect(base.length).toBe(13);
+      expect(base.length).toBe(17);
     });
 
-    it('pbr-material-merged stays 24 entries (sprite/sprite-lit do not change material BGL shape)', () => {
+    it('pbr-material-merged stays 26 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);
-      // mergeSkylightIntoMaterialBgl + lightmap injection must stay
+      expect(merged.entries.length).toBe(26);
+      // 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, 'lightmap')];
+      const expected = [...afterSky, ...appendInjection(afterSky, 'transmission')];
       expect(merged.entries).toEqual(expected);
     });
   });

package/src/__tests__/ssao-passes.test.ts

@@ -8,6 +8,8 @@
 import { RenderGraph } from '@forgeax/engine-render-graph';
 import type { RhiDevice } from '@forgeax/engine-rhi';
 import { describe, expect, it, vi } from 'vitest';
+import { DeviceScope } from '../../../render/src/device/device-scope';
+import type { BloomPersistentBundle } from '../../../render/src/record/render-context';
 import {
   recordBloomBlurHPass,
   recordBloomBlurVPass,
@@ -680,6 +682,31 @@ function makePostProcessRecordCtx(): {
     queue: { writeBuffer: vi.fn(() => ({ ok: true, value: undefined })) },
   };
   const sampler = { label: 'postprocess-sampler' };
+  const bloomScope = DeviceScope.create(1, 'runtime-ssao-bloom-fixture');
+  const ownBloomHandle = (
+    kind: 'pipeline' | 'binding' | 'post-effect' | 'buffer',
+    label: string,
+  ) => {
+    const handle = { label };
+    bloomScope._adopt(kind, handle, () => undefined);
+    return handle;
+  };
+  const bloomResources = {
+    scope: bloomScope,
+    generation: bloomScope.generation,
+    bloomBrightPipeline: ownBloomHandle('pipeline', 'bloom-bright-pipeline'),
+    bloomBlurHPipeline: ownBloomHandle('pipeline', 'bloom-blur-h-pipeline'),
+    bloomBlurVPipeline: ownBloomHandle('pipeline', 'bloom-blur-v-pipeline'),
+    bloomCompositePipeline: ownBloomHandle('pipeline', 'bloom-composite-pipeline'),
+    bloomBrightBindGroupLayout: ownBloomHandle('binding', 'bloom-bright-bgl'),
+    bloomBlurBindGroupLayout: ownBloomHandle('binding', 'bloom-blur-bgl'),
+    bloomCompositeBindGroupLayout: ownBloomHandle('binding', 'bloom-composite-bgl'),
+    bloomSampler: ownBloomHandle('post-effect', 'bloom-sampler'),
+    bloomBrightParamsBuffer: ownBloomHandle('buffer', 'bloom-bright-params'),
+    bloomBlurHParamsBuffer: ownBloomHandle('buffer', 'bloom-blur-h-params'),
+    bloomBlurVParamsBuffer: ownBloomHandle('buffer', 'bloom-blur-v-params'),
+    bloomCompositeParamsBuffer: ownBloomHandle('buffer', 'bloom-composite-params'),
+  } as unknown as BloomPersistentBundle;
   const ctx = {
     runtime: {
       device: { ...device, caps: { storageBuffer: true } },
@@ -702,23 +729,12 @@ function makePostProcessRecordCtx(): {
         skyboxBindGroupLayout: { label: 'skybox-bgl' },
         skyboxSampler: sampler,
         skyboxRotationBuffer: { label: 'skybox-rotation' },
-        bloomBrightPipeline: { label: 'bloom-bright-pipeline' },
-        bloomBrightBindGroupLayout: { label: 'bloom-bright-bgl' },
-        bloomBrightParamsBuffer: { label: 'bloom-bright-params' },
-        bloomBlurHPipeline: { label: 'bloom-blur-h-pipeline' },
-        bloomBlurVPipeline: { label: 'bloom-blur-v-pipeline' },
-        bloomBlurBindGroupLayout: { label: 'bloom-blur-bgl' },
-        bloomBlurHParamsBuffer: { label: 'bloom-blur-h-params' },
-        bloomBlurVParamsBuffer: { label: 'bloom-blur-v-params' },
-        bloomCompositePipeline: { label: 'bloom-composite-pipeline' },
-        bloomCompositeBindGroupLayout: { label: 'bloom-composite-bgl' },
-        bloomCompositeParamsBuffer: { label: 'bloom-composite-params' },
-        bloomSampler: sampler,
         fxaaPipeline: { label: 'fxaa-pipeline' },
         fxaaBindGroupLayout: { label: 'fxaa-bgl' },
         fxaaSampler: sampler,
       },
     },
+    bloomResources,
     frameState: { postProcessBgCache: new WeakMap() },
     bindGroupCounts: { createBindGroup: 0, keys: [] },
     camera: {