@forgeax/engine-runtime 0.1.20 → 0.1.21

package/src/__tests__/shadow-csm-extract.test.ts

@@ -6,16 +6,22 @@
 // This test asserts the extract stage:
 //   (a) castShadow:true  → CSM path runs (lightViewProj + cascades populated)
 //   (b) castShadow:false → CSM path skipped (no cascade output)
-//   (c) ExtractedLights carries depthBias/normalBias/pcfKernelSize
-//   (d) bias/PCF fields are undefined when castShadow:false
+//   (c) ExtractedLights carries depthBias/normalBias and accepted filter quality
+//   (d) bias/filter fields are undefined when castShadow:false
 // RED before m2-t2/m2-t3: extract still queries the deleted
 // castShadow: true; lightViewProj won't populate.
 
 import { World } from '@forgeax/engine-ecs';
+import { vec3 } from '@forgeax/engine-math';
 import { Camera, DirectionalLight } from '@forgeax/engine-render';
 import { Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
-import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
+import {
+  type CsmCameraData,
+  computeDirectionalCsm,
+  extractFrame,
+  prepareExtractContext,
+} from '../../../render/src/render-system-extract';
 
 function makeWorld(castShadow?: boolean): World {
   const world = new World();
@@ -26,7 +32,9 @@ function makeWorld(castShadow?: boolean): World {
       castShadow: castShadow ?? true,
       depthBias: 0.01,
       normalBias: 0.08,
-      pcfKernelSize: 5,
+      shadowFilter: 3,
+      shadowAngularRadius: 0.01,
+      maxPenumbraTexels: 48,
     },
   });
   world.spawn(
@@ -56,16 +64,16 @@ describe('ExtractedLights interface (M2 castShadow gate)', () => {
       }
     });
 
-    it('splitPlanes is a Float32Array of length 4', () => {
+    it('splitPlanes is a Float32Array of four vec4 metric lanes', () => {
       const world = makeWorld(true);
       const frame = extractFrame(world, prepareExtractContext(world));
       const { splitPlanes } = frame.lights;
       expect(splitPlanes).toBeDefined();
       if (splitPlanes === undefined) return;
       expect(splitPlanes).toBeInstanceOf(Float32Array);
-      expect(splitPlanes.length).toBe(4);
+      expect(splitPlanes.length).toBe(16);
       for (let i = 0; i < 4; i++) {
-        const v = splitPlanes[i];
+        const v = splitPlanes[i * 4];
         expect(typeof v).toBe('number');
         expect(Number.isFinite(v)).toBe(true);
       }
@@ -95,7 +103,7 @@ describe('ExtractedLights interface (M2 castShadow gate)', () => {
     });
   });
 
-  describe('ExtractedLights carries bias/PCF from merged DirectionalLight', () => {
+  describe('ExtractedLights carries bias and accepted Directional quality', () => {
     it('depthBias populated when castShadow=true', () => {
       const world = makeWorld(true);
       const frame = extractFrame(world, prepareExtractContext(world));
@@ -108,18 +116,46 @@ describe('ExtractedLights interface (M2 castShadow gate)', () => {
       expect(frame.lights.normalBias).toBeCloseTo(0.08, 5);
     });
 
-    it('pcfKernelSize populated when castShadow=true', () => {
+    it('accepted Directional quality is populated when castShadow=true', () => {
       const world = makeWorld(true);
       const frame = extractFrame(world, prepareExtractContext(world));
-      expect(frame.lights.pcfKernelSize).toBe(5);
+      expect(frame.lights.directionalShadowQuality).toEqual({ kind: 'pcf', kernel: 5 });
     });
 
-    it('depthBias, normalBias, pcfKernelSize are undefined when castShadow=false', () => {
+    it('quality is undefined when castShadow=false', () => {
       const world = makeWorld(false);
       const frame = extractFrame(world, prepareExtractContext(world));
       expect(frame.lights.depthBias).toBeUndefined();
       expect(frame.lights.normalBias).toBeUndefined();
-      expect(frame.lights.pcfKernelSize).toBeUndefined();
+      expect(frame.lights.directionalShadowQuality).toBeUndefined();
+    });
+
+    it('withholds an invalid PCSS candidate and exposes a structured error', () => {
+      const world = new World();
+      const spawned = world.spawn({
+        component: DirectionalLight,
+        data: {
+          direction: [0, -1, 0],
+          shadowFilter: 4,
+          shadowAngularRadius: 999,
+          maxPenumbraTexels: 32,
+        },
+      });
+      expect(spawned.ok).toBe(true);
+      world.spawn(
+        { component: Transform, data: {} },
+        { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+      );
+
+      const frame = extractFrame(world, prepareExtractContext(world));
+      expect(frame.lights.directionalShadowError?.code).toBe('shadow-invalid-config');
+      expect(frame.lights.directionalShadowError?.detail).toMatchObject({
+        field: 'shadowAngularRadius',
+        actual: 999,
+      });
+      expect(frame.lights.directionalShadowQuality).toBeUndefined();
+      expect(frame.lights.directionalCsmConfig).toBeUndefined();
+      expect(frame.lights.lightViewProj).toBeUndefined();
     });
   });
 
@@ -174,24 +210,18 @@ describe('ExtractedLights interface (M2 castShadow gate)', () => {
     });
   });
 
-  // feat-20260621-learn-render-5-3-production-shadow-demos M0 / AC-14:
-  // extract reads DirectionalLightShadow.pcfKernelSize into the frame lights
-  // struct (symmetric with cascadeCount/cascadeBlend). Before M0 this field is
-  // dead (research F7): extract never read it, so frame.lights.pcfKernelSize
-  // is undefined regardless of the component value -- these cases are RED
-  // until M0-T-IMPL-EXTRACT lands.
-  describe('pcfKernelSize wiring (M0, AC-14; merged DirectionalLight)', () => {
-    function setupWorldWithPcf(pcfKernelSize: number): World {
+  describe('CSM fit derives world-scale metrics and accepts one quality projection', () => {
+    function setupWorldWithQuality(shadowFilter: number): World {
       const world = new World();
-      // feat-20260621: shadow fields merged onto DirectionalLight (castShadow
-      // defaults true); pcfKernelSize is read from the same component.
       world.spawn({
         component: DirectionalLight,
         data: {
           direction: [0, -1, 0],
           cascadeCount: 1,
           shadowDistance: 100,
-          pcfKernelSize,
+          shadowFilter,
+          shadowAngularRadius: 0.01,
+          maxPenumbraTexels: 32,
         },
       });
       world.spawn(
@@ -201,36 +231,115 @@ describe('ExtractedLights interface (M2 castShadow gate)', () => {
       return world;
     }
 
-    it('reads pcfKernelSize=1 from the merged component', () => {
-      const world = setupWorldWithPcf(1);
-      const frame = extractFrame(world, prepareExtractContext(world));
-      expect(frame.lights.pcfKernelSize).toBe(1);
-    });
-
-    it('reads pcfKernelSize=3 from the merged component', () => {
-      const world = setupWorldWithPcf(3);
+    it('projects PCSS quality from the same Directional query', () => {
+      const world = setupWorldWithQuality(4);
       const frame = extractFrame(world, prepareExtractContext(world));
-      expect(frame.lights.pcfKernelSize).toBe(3);
+      expect(frame.lights.directionalShadowQuality).toEqual({
+        kind: 'pcss',
+        preset: 'medium',
+        angularRadiusRadians: expect.closeTo(0.01, 0.000001),
+        maxPenumbraTexels: 32,
+      });
     });
 
-    it('reads pcfKernelSize=5 from the merged component', () => {
-      const world = setupWorldWithPcf(5);
-      const frame = extractFrame(world, prepareExtractContext(world));
-      expect(frame.lights.pcfKernelSize).toBe(5);
+    it('exposes four finite vec4 cascade metric lanes from the CSM fit', () => {
+      const camera: CsmCameraData = {
+        world: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
+        fov: Math.PI / 4,
+        aspect: 1,
+        near: 0.1,
+        far: 100,
+        projection: 'perspective',
+        orthoLeft: -1,
+        orthoRight: 1,
+        orthoBottom: -1,
+        orthoTop: 1,
+      };
+      for (const cascadeCount of [1, 2, 3, 4]) {
+        const result = computeDirectionalCsm(
+          vec3.create(0, -1, 0),
+          {
+            cascadeCount,
+            splitLambda: 0.75,
+            cascadeBlend: 0.2,
+            mapSize: 1024,
+            shadowDistance: 100,
+            shadowFilter: 3,
+            shadowAngularRadius: 0.01,
+            maxPenumbraTexels: 32,
+          },
+          camera,
+        );
+        expect(result).not.toBeNull();
+        const lanes = result?.splitPlanes ?? new Float32Array();
+        expect(lanes).toHaveLength(16);
+        for (let index = 0; index < cascadeCount; index += 1) {
+          expect(Number.isFinite(lanes[index * 4 + 1])).toBe(true);
+          expect(lanes[index * 4 + 1]).toBeGreaterThan(0);
+          expect(Number.isFinite(lanes[index * 4 + 2])).toBe(true);
+          expect(lanes[index * 4 + 2]).toBeGreaterThan(0);
+        }
+      }
     });
 
-    it('defaults pcfKernelSize to 3 when the component omits it', () => {
-      const world = new World();
-      world.spawn({
-        component: DirectionalLight,
-        data: { direction: [0, -1, 0], cascadeCount: 1 },
-      });
-      world.spawn(
-        { component: Transform, data: {} },
-        { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+    it('recomputes worldUnitsPerTexel when mapSize changes and rejects non-finite config', () => {
+      const camera: CsmCameraData = {
+        world: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
+        fov: Math.PI / 4,
+        aspect: 1,
+        near: 0.1,
+        far: 100,
+        projection: 'perspective',
+        orthoLeft: -1,
+        orthoRight: 1,
+        orthoBottom: -1,
+        orthoTop: 1,
+      };
+      const coarse = computeDirectionalCsm(
+        vec3.create(0, -1, 0),
+        {
+          cascadeCount: 1,
+          splitLambda: 0.75,
+          cascadeBlend: 0.2,
+          mapSize: 512,
+          shadowDistance: 100,
+          shadowFilter: 3,
+          shadowAngularRadius: 0.01,
+          maxPenumbraTexels: 32,
+        },
+        camera,
       );
-      const frame = extractFrame(world, prepareExtractContext(world));
-      expect(frame.lights.pcfKernelSize).toBe(3);
+      const fine = computeDirectionalCsm(
+        vec3.create(0, -1, 0),
+        {
+          cascadeCount: 1,
+          splitLambda: 0.75,
+          cascadeBlend: 0.2,
+          mapSize: 2048,
+          shadowDistance: 100,
+          shadowFilter: 3,
+          shadowAngularRadius: 0.01,
+          maxPenumbraTexels: 32,
+        },
+        camera,
+      );
+      expect(fine?.splitPlanes[1]).toBeCloseTo((coarse?.splitPlanes[1] ?? 0) / 4, 4);
+      expect(
+        computeDirectionalCsm(
+          vec3.create(0, -1, 0),
+          {
+            cascadeCount: 1,
+            splitLambda: 0.75,
+            cascadeBlend: 0.2,
+            mapSize: Number.NaN,
+            shadowDistance: 100,
+            shadowFilter: 3,
+            shadowAngularRadius: 0.01,
+            maxPenumbraTexels: 32,
+          },
+          camera,
+        ),
+      ).toBeNull();
     });
   });
 });

package/src/__tests__/shadow-csm-runtime-vary.dawn.test.ts

@@ -20,6 +20,8 @@ import { World } from '@forgeax/engine-ecs';
 import { Camera, DirectionalLight } from '@forgeax/engine-render';
 import { Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
+import { projectDirectionalShadowInspection } from '../../../render/src/assembly/directional-shadow-inspection';
+import { resolveDirectionalShadowBackendAdmission } from '../../../render/src/render-pipeline';
 import { constructRuntimeRendererHost } from '../renderer-host';
 import { drawPublished } from './draw-published';
 
@@ -34,6 +36,51 @@ const ENGINE_MANIFEST_URL = `data:application/json,${encodeURIComponent(
 // biome-ignore lint/suspicious/noExplicitAny: dawn-node detection guard
 const dawnReady = typeof navigator !== 'undefined' && (navigator as any).gpu !== undefined;
 
+describe('M3 RhiNull structural admission', () => {
+  it('requires the structural-only RhiNull projection and explicit no-pixel claim', async () => {
+    const module = (await import('../../../render/src/render-pipeline')) as Record<string, unknown>;
+    const resolver = module.resolveDirectionalShadowBackendAdmission;
+    expect(typeof resolver).toBe('function');
+    const result = (
+      resolver as (input: {
+        backendKind: 'null';
+        requested: 'pcssMedium' | 'pcssHigh';
+        candidate: 'accepted' | 'failed';
+      }) => { effective: string; fallbackReason?: string; pixelEvidence: string }
+    )({ backendKind: 'null', requested: 'pcssMedium', candidate: 'accepted' });
+    expect(result).toMatchObject({
+      effective: 'rhi-null-structural',
+      fallbackReason: 'rhi-null-structural',
+      pixelEvidence: 'not-available',
+    });
+  });
+
+  it('keeps RhiNull recovery structural and generation-scoped', () => {
+    const inspection = projectDirectionalShadowInspection({
+      admission: resolveDirectionalShadowBackendAdmission({
+        backendKind: 'null',
+        requested: 'pcssMedium',
+        candidate: 'accepted',
+      }),
+      cascadeCount: 4,
+      mapSize: 1024,
+      atlasBytes: 16_777_216,
+      writerPasses: 4,
+      blockerTaps: 0,
+      filterTapUpperBound: 0,
+      seamTapUpperBound: 0,
+      deviceGeneration: 4,
+      graphGeneration: 9,
+    });
+    expect(inspection).toMatchObject({
+      effective: 'rhi-null-structural',
+      pixelEvidence: 'not-available',
+      deviceGeneration: 4,
+      graphGeneration: 9,
+    });
+  });
+});
+
 const WIDTH = 320;
 const HEIGHT = 240;
 
@@ -200,4 +247,29 @@ describe('CSM runtime cascade + mapSize variation (M5/w26)', () => {
     const { world } = buildScene(1, 1024);
     expect(drawPublished(renderer, world).ok).toBe(true);
   });
+
+  it('castShadow true -> false -> true toggles the directional graph without device error', async () => {
+    if (!dawnReady) return;
+    const canvas = createMockCanvas();
+    const host = await constructRuntimeRendererHost(
+      canvas as unknown as HTMLCanvasElement,
+      {},
+      { shaderManifestUrl: ENGINE_MANIFEST_URL },
+    );
+    expect(host.ok).toBe(true);
+    if (!host.ok) throw host.error;
+    const { renderer } = host.value;
+    const { world, shadowEntity } = buildScene(4, 1024);
+
+    expect(drawPublished(renderer, world).ok).toBe(true);
+    world.set(shadowEntity, DirectionalLight, { castShadow: false });
+    expect(drawPublished(renderer, world).ok).toBe(true);
+    world.set(shadowEntity, DirectionalLight, {
+      castShadow: true,
+      mapSize: 1024,
+      shadowDistance: 50,
+      cascadeCount: 4,
+    });
+    expect(drawPublished(renderer, world).ok).toBe(true);
+  });
 });

package/src/__tests__/shadow-csm-shader.dawn.test.ts

@@ -20,8 +20,15 @@
 // regression in the kernel logic itself. The kernel is the executable AC-06
 // spec; w18 implementation must derive identical behavior.
 
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 
+const directionalShader = readFileSync(
+  fileURLToPath(new URL('../../../shader/src/lighting-directional.wgsl', import.meta.url)),
+  'utf8',
+);
+
 // biome-ignore lint/suspicious/noExplicitAny: dawn-node detection guard
 const dawnReady = typeof navigator !== 'undefined' && (navigator as any).gpu !== undefined;
 
@@ -228,6 +235,18 @@ describe('CSM shader cascade selection + atlas UV + blend (M5/w17)', () => {
     expect(dawnReady).toBe(true);
   });
 
+  it('production Directional PCSS uses raw depth and comparison without new bindings', () => {
+    expect(directionalShader).toContain('fn _samplePcssForCascade');
+    expect(directionalShader).toContain('shadow_load_raw_depth');
+    expect(directionalShader).toContain('shadow_sample_compare');
+    expect(directionalShader).toContain('PCSS_MEDIUM_RAW_TAPS : u32 = 8u');
+    expect(directionalShader).toContain('PCSS_MEDIUM_COMPARE_TAPS : u32 = 16u');
+    expect(directionalShader).toContain('PCSS_HIGH_RAW_TAPS : u32 = 16u');
+    expect(directionalShader).toContain('PCSS_HIGH_COMPARE_TAPS : u32 = 32u');
+    expect(directionalShader).not.toMatch(/@binding\(/);
+    expect(directionalShader).not.toMatch(/frameIndex|frame_index|taaJitter|taa_jitter|jitter/);
+  });
+
   describe('cascade selection by viewZ (AC-03 / AC-06)', () => {
     it('viewZ < splits[0] -> layer 0', async () => {
       const r = await runKernel({

package/src/__tests__/shadow-csm-ubo.test.ts

@@ -5,15 +5,17 @@
 // independent of runtime cascadeCount. Validates std140 byte offsets for
 // lightViewProj[4], splitPlanes[4], cascadeCount, cascadeBlend.
 //
-// feat-20260625-spot-light-shadow-mapping w25 (scope-amend webkit-fallback):
-// the View UBO grew 592 -> 784 B (148 -> 196 f32). The directional cascade
+// feat-20260827-directional-csm-pcss-quality M1: the View UBO keeps its
+// existing 960 B payload and 1024 B slot while the directional filter carrier
+// reuses the tail pad. The directional cascade
 // offsets [0..128] are byte-for-byte UNCHANGED; the per-spot fragment-read
 // `spotLightViewProj` array<mat4x4<f32>,4> (256 B) folded into the tail at
 // byte 528 (float 132), replacing the former zero tail-pad and removing the
 // standalone @group(0) binding 9 uniform buffer that overflowed the WebGL2
 // fallback fragment uniform-buffer budget.
 //
-// Layout (784 B std140, 196 f32):
+// Layout (960 B View payload, 1024 B slot; the directional prefix remains
+// byte-compatible with the 784 B Spot-matrix boundary):
 //   [  0.. 16) worldViewProj   mat4x4<f32>  (align 16, size 64)
 //   [ 16.. 19) lightDir        vec3<f32>    (align 16, 12 + 4 pad)
 //   [ 20.. 22) lightColor      vec3<f32>    (align 16, 12 + 4 pad)
@@ -31,30 +33,27 @@
 //   [125]      cascadeBlend    f32          (align 4, size 4)
 //   [126]      depthBias       f32          (align 4, size 4)
 //   [127]      normalBias      f32          (align 4, size 4)
-//   [128]      pcfKernelSize   f32          (align 4, size 4)
-//   [129..131] align padding   f32[3]       (mat4 array align 16)
+//   [128..131] directionalShadowFilter vec4<f32> (profile, radius, penumbra, reserved)
 //   [132..195] spotLightViewProj array<mat4x4<f32>,4> (align 16, size 256)
 
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 
-const VIEW_UBO_FLOAT_COUNT = 196;
-const VIEW_UBO_BYTES = 784;
+const VIEW_UBO_FLOAT_COUNT = 240;
+const VIEW_UBO_BYTES = 960;
 // feat-20260625 w25: spot lightViewProj array folded into the View UBO tail.
-const OFFSET_SPOT_LIGHT_VIEW_PROJ = 132; // byte 528 (16 B-aligned after pcfKernelSize)
+const OFFSET_SPOT_LIGHT_VIEW_PROJ = 132; // byte 528 (16 B-aligned after filter carrier)
 const SPOT_LVP_LANE_COUNT = 4;
 const SPOT_LVP_FLOATS_PER_LANE = 16;
 
-// feat-20260621-merge-directionallightshadow-into-directionallight M3:
+// feat-20260827-directional-csm-pcss-quality M1:
 // the merged DirectionalLight's shadow tail-pad slots — depthBias [126]/byte504,
-// normalBias [127]/byte508, pcfKernelSize [128]/byte512 (zero byte-layout growth;
-// three previously-zero tail-pad floats are consumed). The 5.3-production-shadow-
-// demos AC-14 pcfKernelSize lane moved from [126] to [128] when depthBias/normalBias
-// merged in ahead of it.
+// normalBias [127]/byte508, and the four-float directional filter carrier
+// [128..131]. The Spot matrix array remains at [132..195].
 const OFFSET_DEPTH_BIAS = 126; // byte 504
 const OFFSET_NORMAL_BIAS = 127; // byte 508
-const OFFSET_PCF_KERNEL_SIZE = 128; // byte 512
+const OFFSET_DIRECTIONAL_FILTER = 128; // byte 512
 
 const F32_BYTES = 4;
 
@@ -79,30 +78,30 @@ const SPLIT_STRIDE_FLOATS = 4;
 
 describe('View UBO std140 layout (w14)', () => {
   describe('size invariants', () => {
-    it('UBO total size is 784 B (196 f32)', () => {
-      expect(VIEW_UBO_FLOAT_COUNT).toBe(196);
+    it('UBO total size is 960 B (240 f32)', () => {
+      expect(VIEW_UBO_FLOAT_COUNT).toBe(240);
       expect(VIEW_UBO_BYTES).toBe(VIEW_UBO_FLOAT_COUNT * F32_BYTES);
-      expect(VIEW_UBO_BYTES).toBe(784);
+      expect(VIEW_UBO_BYTES).toBe(960);
     });
 
     it('UBO size is fixed — independent of cascadeCount', () => {
-      // The host always allocates 784 B regardless of whether cascadeCount
+      // The host always allocates 960 B regardless of whether cascadeCount
       // is 1, 2, 3, or 4 at runtime. This validates AC-08.
       const sizeForN1 = VIEW_UBO_FLOAT_COUNT * F32_BYTES; // cascadeCount=1
       const sizeForN4 = VIEW_UBO_FLOAT_COUNT * F32_BYTES; // cascadeCount=4
       expect(sizeForN1).toBe(sizeForN4);
-      expect(sizeForN1).toBe(784);
+      expect(sizeForN1).toBe(960);
     });
 
     it('spotLightViewProj array lands at byte 528 (float 132), 16 B-aligned, last field', () => {
       // feat-20260625 w25: the 4-lane spot perspective matrix array folds into
-      // the View UBO tail after pcfKernelSize (float 128 / byte 512), 16 B-aligned
+      // the View UBO tail after the directional filter carrier, 16 B-aligned
       // so it starts at byte 528 (float 132). It is the last struct field.
       expect(OFFSET_SPOT_LIGHT_VIEW_PROJ * F32_BYTES).toBe(528);
       expect((OFFSET_SPOT_LIGHT_VIEW_PROJ * F32_BYTES) % 16).toBe(0);
       const spotArrayEndFloat =
         OFFSET_SPOT_LIGHT_VIEW_PROJ + SPOT_LVP_LANE_COUNT * SPOT_LVP_FLOATS_PER_LANE;
-      expect(spotArrayEndFloat).toBe(VIEW_UBO_FLOAT_COUNT);
+      expect(spotArrayEndFloat).toBe(196);
       expect(spotArrayEndFloat * F32_BYTES).toBe(784);
     });
   });
@@ -220,15 +219,8 @@ describe('View UBO std140 layout (w14)', () => {
   });
 });
 
-// feat-20260621-learn-render-5-3-production-shadow-demos M0 / AC-14: the host
-// record stage must write pcfKernelSize into the tail-pad slot [126], and the
-// WGSL View struct must declare the matching `pcfKernelSize : f32` immediately
-// after cascadeBlend (single SSOT, append-at-tail, plan-strategy D-0). These
-// are read against the real source the compiler/host use (mirrors the
-// shadow-csm-tile-consistency antipattern guard: never re-declare and test a
-// formula against itself). RED until M0-T-IMPL-RECORD + M0-T-IMPL-WGSL-STRUCT
-// land; the slot was previously a zero tail-pad float (no record write existed).
-describe('pcfKernelSize tail-pad slot wiring (M0, AC-14)', () => {
+// M1-T05: read the real host and WGSL sources so the frozen ABI cannot drift.
+describe('directional filter carrier tail-pad wiring (M1-T05)', () => {
   const recordSrc = readFileSync(
     fileURLToPath(new URL('../../../render/src/record/view-ubo.ts', import.meta.url)),
     'utf8',
@@ -238,26 +230,25 @@ describe('pcfKernelSize tail-pad slot wiring (M0, AC-14)', () => {
     'utf8',
   );
 
-  it('shadow tail floats [126..128] at fixed offsets, before the spot matrix array', () => {
+  it('shadow tail floats [126..131] at fixed offsets, before the spot matrix array', () => {
     expect(OFFSET_DEPTH_BIAS * F32_BYTES).toBe(504);
     expect(OFFSET_NORMAL_BIAS * F32_BYTES).toBe(508);
-    expect(OFFSET_PCF_KERNEL_SIZE * F32_BYTES).toBe(512);
+    expect(OFFSET_DIRECTIONAL_FILTER * F32_BYTES).toBe(512);
     expect(OFFSET_DEPTH_BIAS).toBeGreaterThan(OFFSET_CASCADE_BLEND);
-    expect(OFFSET_PCF_KERNEL_SIZE).toBeLessThan(VIEW_UBO_FLOAT_COUNT);
-    // feat-20260625 w25: the shadow bias floats stay at [126..128]; the spot
-    // matrix array follows them at float 132 (byte 528). The struct grew to
-    // 196 f32 / 784 B to carry the folded-in spot matrices (was 148 / 592).
-    expect(OFFSET_PCF_KERNEL_SIZE).toBeLessThan(OFFSET_SPOT_LIGHT_VIEW_PROJ);
-    expect(VIEW_UBO_FLOAT_COUNT).toBe(196);
-    expect(VIEW_UBO_BYTES).toBe(784);
+    expect(OFFSET_DIRECTIONAL_FILTER + 4).toBe(OFFSET_SPOT_LIGHT_VIEW_PROJ);
+    expect(OFFSET_DIRECTIONAL_FILTER).toBeLessThan(OFFSET_SPOT_LIGHT_VIEW_PROJ);
+    expect(VIEW_UBO_FLOAT_COUNT).toBe(240);
+    expect(VIEW_UBO_BYTES).toBe(960);
   });
 
-  it('record writes the merged shadow tail-pad floats [126]/[127]/[128]', () => {
+  it('record writes the merged shadow tail-pad floats [126]/[127]/[128..131]', () => {
     expect(recordSrc).toMatch(/viewPayload\[126\]\s*=\s*lights\.depthBias/);
     expect(recordSrc).toMatch(/viewPayload\[127\]\s*=\s*lights\.normalBias/);
-    expect(recordSrc).toMatch(
-      /viewPayload\[128\]\s*=\s*clampPcfKernelSize\(lights\.pcfKernelSize\)/,
-    );
+    expect(recordSrc).toMatch(/viewPayload\[128\]/);
+    expect(recordSrc).toMatch(/viewPayload\[129\]/);
+    expect(recordSrc).toMatch(/viewPayload\[130\]/);
+    expect(recordSrc).toMatch(/viewPayload\[131\]/);
+    expect(recordSrc).not.toMatch(/lights\.pcfKernelSize/);
   });
 
   it('record carries the folded spot matrices in the complete View UBO payload (w25)', () => {
@@ -269,10 +260,15 @@ describe('pcfKernelSize tail-pad slot wiring (M0, AC-14)', () => {
     expect(recordSrc).toMatch(/SPOT_LVP_BASE_FLOAT\s*=\s*132/);
   });
 
-  it('common.wgsl View struct declares depthBias/normalBias/pcfKernelSize after cascadeBlend', () => {
+  it('common.wgsl View struct declares the directional filter vec4 after biases', () => {
     const m = wgslSrc.match(
-      /cascadeBlend\s*:\s*f32\s*,\s*depthBias\s*:\s*f32\s*,\s*normalBias\s*:\s*f32\s*,\s*pcfKernelSize\s*:\s*f32\s*,/,
+      /cascadeBlend\s*:\s*f32\s*,\s*depthBias\s*:\s*f32\s*,\s*normalBias\s*:\s*f32\s*,\s*directionalShadowFilter\s*:\s*vec4<f32>\s*,/,
     );
     expect(m).not.toBeNull();
   });
+
+  it('keeps one View binding and removes the retired spot matrix binding', () => {
+    expect(wgslSrc.match(/@group\(0\) @binding\(0\) var<uniform> view/g)).toHaveLength(1);
+    expect(wgslSrc).not.toMatch(/@group\(0\)\s*@binding\(9\)/);
+  });
 });

package/src/__tests__/shadow-csm-viewport.browser.test.ts

@@ -11,6 +11,8 @@
 // D-6: pass names shadowCascade0..3.
 
 import { describe, expect, it } from 'vitest';
+import { projectDirectionalShadowInspection } from '../../../render/src/assembly/directional-shadow-inspection';
+import { resolveDirectionalShadowBackendAdmission } from '../../../render/src/render-pipeline';
 
 const browserReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
 
@@ -83,3 +85,30 @@ describe('CSM per-cascade viewport (w30)', () => {
     });
   });
 });
+
+describe('M3 Browser backend admission', () => {
+  it('declares WebGL2 PCSS fallback without changing the atlas viewport contract', () => {
+    const inspection = projectDirectionalShadowInspection({
+      admission: resolveDirectionalShadowBackendAdmission({
+        backendKind: 'wgpu-webgl2',
+        requested: 'pcssHigh',
+        candidate: 'accepted',
+      }),
+      cascadeCount: 4,
+      mapSize: 2048,
+      atlasBytes: 67_108_864,
+      writerPasses: 4,
+      blockerTaps: 0,
+      filterTapUpperBound: 25,
+      seamTapUpperBound: 25,
+      deviceGeneration: 1,
+      graphGeneration: 1,
+    });
+    expect(inspection).toMatchObject({
+      effective: 'pcf5',
+      fallbackReason: 'webgl2-unsupported',
+      cascadeCount: 4,
+      mapSize: 2048,
+    });
+  });
+});