@forgeax/engine-runtime 0.1.19 → 0.1.21

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,
+    });
+  });
+});

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

@@ -1,8 +1,8 @@
 // shadow-fields-observable.dawn.test.ts
 // feat-20260621-merge-directionallightshadow-into-directionallight M6
 //
-// Observability gate: proves depthBias, normalBias, pcfKernelSize --
-// three merged DirectionalLight shadow fields -- produce real pixel A/B diffs.
+// Observability gate: proves depthBias, normalBias, and the directional filter
+// carrier -- three merged DirectionalLight shadow fields -- produce real pixel A/B diffs.
 //
 // Root cause of prior "0 diff everywhere" failure: (a) materials without
 // ShadowCaster pass (nothing written into shadow depth atlas), (b) floor
@@ -33,12 +33,70 @@ 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();
 })();
 const ENGINE_MANIFEST_URL = `data:application/json,${encodeURIComponent(JSON.stringify(ENGINE_MANIFEST))}`;
 
+describe('M3 Dawn candidate admission', () => {
+  it('requires accepted production candidate to preserve the requested PCSS profile', 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: 'webgpu';
+        requested: 'pcssMedium' | 'pcssHigh';
+        candidate: 'accepted' | 'failed';
+      }) => { effective: string; status: string; pixelEvidence: string }
+    )({ backendKind: 'webgpu', requested: 'pcssHigh', candidate: 'accepted' });
+    expect(result).toMatchObject({
+      effective: 'pcssHigh',
+      status: 'accepted',
+      pixelEvidence: 'available',
+    });
+  });
+
+  it('requires the same bounded Directional inspection projection used by Dawn', async () => {
+    const module = (await import(
+      '../../../render/src/assembly/directional-shadow-inspection'
+    )) as Record<string, unknown>;
+    const project = module.projectDirectionalShadowInspection;
+    expect(typeof project).toBe('function');
+    const result = (project as (input: Record<string, unknown>) => Record<string, unknown>)({
+      admission: {
+        requested: 'pcssMedium',
+        effective: 'pcssMedium',
+        status: 'accepted',
+        pixelEvidence: 'available',
+      },
+      cascadeCount: 4,
+      mapSize: 1024,
+      atlasBytes: 16_777_216,
+      writerPasses: 4,
+      blockerTaps: 8,
+      filterTapUpperBound: 16,
+      seamTapUpperBound: 48,
+      deviceGeneration: 1,
+      graphGeneration: 3,
+    });
+    expect(result).toMatchObject({
+      requested: 'pcssMedium',
+      effective: 'pcssMedium',
+      blockerTaps: 8,
+      filterTapUpperBound: 16,
+      seamTapUpperBound: 48,
+    });
+    expect(Object.keys(result)).not.toContain('perPixel');
+  });
+});
+
 // Helper types
 interface WriteCapture {
   f32: Float32Array;
@@ -172,7 +230,9 @@ function spawnScene(
       depthBias,
       normalBias,
       shadowDistance: 50,
-      pcfKernelSize: pcf,
+      shadowFilter: pcf === 1 ? 1 : pcf === 3 ? 2 : 3,
+      shadowAngularRadius: 0.00465,
+      maxPenumbraTexels: 32,
     },
   });
   world.spawn(
@@ -432,15 +492,15 @@ async function renderConfigWithSpy(
 
 describe('M6 shadow fields observability', () => {
   // --- Gate A: structural WGSL check ---
-  it('composed default-standard-pbr WGSL reads view.depthBias, view.normalBias, view.pcfKernelSize', () => {
+  it('composed default-standard-pbr WGSL reads view.depthBias, view.normalBias, and directionalShadowFilter', () => {
     const wgsl = composedStandardPbr();
     expect(wgsl).toContain('depthBias');
     expect(wgsl).toContain('normalBias');
-    expect(wgsl).toContain('pcfKernelSize');
+    expect(wgsl).toContain('directionalShadowFilter');
   });
 
-  // --- Gate B: UBO spy — slots [126]=depthBias, [127]=normalBias, [128]=pcfKernelSize ---
-  it('View UBO slots [126]=depthBias, [127]=normalBias, [128]=pcfKernelSize', async () => {
+  // --- Gate B: UBO spy — slots [126]=depthBias, [127]=normalBias, [128]=filter profile ---
+  it('View UBO slots [126]=depthBias, [127]=normalBias, [128]=filter profile', async () => {
     if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') return;
     const { captured } = await renderConfigWithSpy(true, 0.123, 0.456, 3);
     const vw = captured.filter((c) => c.f32.length >= 148);
@@ -450,22 +510,22 @@ describe('M6 shadow fields observability', () => {
     const f32 = last.f32;
     expect(Math.abs((f32[126] ?? Number.NaN) - 0.123)).toBeLessThan(0.001);
     expect(Math.abs((f32[127] ?? Number.NaN) - 0.456)).toBeLessThan(0.001);
-    expect(f32[128]).toBe(3);
+    expect(f32[128]).toBe(2);
   }, 60000);
 
-  // --- Gate D: pcfKernelSize clamp (9 -> 5; cap matches WGSL MAX_PCF_HALF=2) ---
-  it('pcfKernelSize=9 clamped to 5 in View UBO[128]', async () => {
+  // --- Gate D: pcf5 maps to the accepted profile carrier ---
+  it('pcf5 maps to profile 3 in View UBO[128]', async () => {
     if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') return;
-    const { captured } = await renderConfigWithSpy(true, 0.005, 0.05, 9);
+    const { captured } = await renderConfigWithSpy(true, 0.005, 0.05, 5);
     const vw9 = captured.filter((c) => c.f32.length >= 148);
     expect(vw9.length).toBeGreaterThan(0);
     const last9 = vw9[vw9.length - 1];
     if (last9 === undefined) throw new Error('no view UBO write captured');
-    expect(last9.f32[128]).toBe(5);
+    expect(last9.f32[128]).toBe(3);
   }, 60000);
 
-  // --- Gate D: validate() rejections ---
-  it('validate() accepts pcfKernelSize=9 (odd), rejects 2 (even) and 0', () => {
+  // --- Gate D: Directional filter validation ---
+  it('validate() accepts pcf5 and rejects an unknown directional filter', () => {
     const valid = validateDirectionalLightData({
       direction: [0, -1, 0],
       castShadow: true,
@@ -474,7 +534,7 @@ describe('M6 shadow fields observability', () => {
       cascadeBlend: 0.2,
       mapSize: 2048,
       shadowDistance: 50,
-      pcfKernelSize: 9,
+      shadowFilter: 3,
     });
     expect(valid.ok).toBe(true);
 
@@ -486,7 +546,7 @@ describe('M6 shadow fields observability', () => {
       cascadeBlend: 0.2,
       mapSize: 2048,
       shadowDistance: 50,
-      pcfKernelSize: 2,
+      shadowFilter: 99,
     });
     expect(even.ok).toBe(false);
     if (!even.ok) expect(even.error.code).toBe('shadow-invalid-config');
@@ -499,7 +559,7 @@ describe('M6 shadow fields observability', () => {
       cascadeBlend: 0.2,
       mapSize: 2048,
       shadowDistance: 50,
-      pcfKernelSize: 0,
+      shadowFilter: 0,
     });
     expect(zero.ok).toBe(false);
     if (!zero.ok) expect(zero.error.code).toBe('shadow-invalid-config');
@@ -514,6 +574,16 @@ describe('M6 shadow fields observability', () => {
     expect(d.diff).toBeGreaterThan(0);
   }, 60000);
 
+  it('castShadow=false emits a zero directional cascade count in the View UBO', async () => {
+    if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') return;
+    const { captured } = await renderConfigWithSpy(false, 0.005, 0.05, 3);
+    const viewWrites = captured.filter((capture) => capture.f32.length >= 148);
+    expect(viewWrites.length).toBeGreaterThan(0);
+    const last = viewWrites[viewWrites.length - 1];
+    if (last === undefined) throw new Error('no view UBO write captured');
+    expect(last.f32[124]).toBe(0);
+  }, 60000);
+
   // --- Gate C: pixel A/B — depthBias 0.0 vs 0.5 ---
   it('pixel A/B: depthBias 0.0 vs 0.5', async () => {
     if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') return;
@@ -532,8 +602,8 @@ describe('M6 shadow fields observability', () => {
     expect(d.diff).toBeGreaterThan(0);
   }, 60000);
 
-  // --- Gate C: pixel A/B — pcfKernelSize 1 vs 5 (cap; MAX_PCF_HALF=2) ---
-  it('pixel A/B: pcfKernelSize 1 vs 5', async () => {
+  // --- Gate C: pixel A/B — directional filter profile 1 vs 3 ---
+  it('pixel A/B: directional filter profile 1 vs 3', async () => {
     if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') return;
     const pxA = await renderConfig(true, 0.005, 0.05, 1);
     const pxB = await renderConfig(true, 0.005, 0.05, 5);
@@ -582,45 +652,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: directional filter 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

@@ -203,7 +203,9 @@ function spawnMixedScene(world: World, castShadow: boolean): void {
       depthBias: 0.005,
       normalBias: 0.05,
       shadowDistance: 50,
-      pcfKernelSize: 3,
+      shadowFilter: 2,
+      shadowAngularRadius: 0.00465,
+      maxPenumbraTexels: 32,
     },
   });
 
@@ -312,7 +314,9 @@ async function renderMixed(castShadow: boolean): Promise<MixedCapture> {
     if (!host.ok) throw host.error;
     renderer = host.value.renderer;
     unsubscribe = renderer.subscribe((event) => {
-      if (event.kind === 'error') errors.push(event.error.code);
+      if (event.kind === 'error') {
+        errors.push(event.error.code);
+      }
     });
     const world = new World();
     spawnMixedScene(world, castShadow);

package/src/__tests__/skylight-lazy-projection.test.ts

@@ -260,10 +260,10 @@ describe('driveLazyEquirectProjection — lazy projection state machine (M3 / w2
     const world = new World();
     const handle = catalogEquirect(world, equirectPod());
     const reg = new RhiErrorListenerRegistry();
-    const fired: Array<{ code: string; handle: number | undefined }> = [];
+    const fired: Array<{ code: string; handle: number | undefined; hint?: string }> = [];
     reg.add((e) => {
       if (e.code === 'equirect-projection-failed') {
-        fired.push({ code: e.code, handle: e.detail.handle });
+        fired.push({ code: e.code, handle: e.detail.handle, hint: e.hint });
       } else {
         fired.push({ code: e.code, handle: undefined });
       }
@@ -281,9 +281,12 @@ describe('driveLazyEquirectProjection — lazy projection state machine (M3 / w2
 
     // Frame 2: status:'failed' observed -> fire the structured error ONCE.
     driveLazyEquirectProjection(internals, world, frameState, handle as unknown as number);
-    expect(fired).toEqual([
-      { code: 'equirect-projection-failed', handle: handle as unknown as number },
-    ]);
+    expect(fired).toHaveLength(1);
+    expect(fired[0]).toMatchObject({
+      code: 'equirect-projection-failed',
+      handle: handle as unknown as number,
+    });
+    expect(fired[0]?.hint).toContain('declare Skylight');
 
     // Frame 3+: the latch keeps the channel quiet -- no re-fire, no retry
     // (the store's status:'failed' short-circuit + the frameState latch).

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)', () => {