@forgeax/engine-runtime 0.1.2

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

@@ -0,0 +1,151 @@
+// shadow-csm-orthoz.test.ts - bug-20260619-csm-multi-cascade-directional-shadow-broken
+// M1 / AC-05 (RED): the per-cascade orthographic Z range must reach toward the
+// light so a caster sitting BETWEEN the light and the visible frustum slice is
+// captured in that cascade's depth map (classic "missing caster" CSM bug).
+//
+// This test drives the REAL extract cascade-fit path (NOT a local copy): it
+// builds a World, prepares its fresh context, calls extractFrame, and reads the actual per-cascade
+// lightViewProj matrix the engine produced at render-system-extract.ts:1581.
+// It then projects a world-space caster point offset toward the light source
+// through that matrix and asserts the resulting clip-space z is inside the
+// WebGPU depth clip volume [0,1].
+//
+// Why this is RED today: extract fits the ortho near/far to ONLY the visible
+// slice corners (`-maxZ / -minZ`), with no extension toward the light. An
+// occluder hovering between the sun and the shadow-receiving ground lands in
+// front of the ortho near plane in the cascade that covers that ground -> its
+// projected z < 0 -> clipped out -> never written to the cascade depth tile ->
+// the ground fragment (which `_pickCascadeLayer` routes to that same cascade)
+// reads "no occluder" -> no shadow. The N=4 case is worse than N=1 because the
+// thinner near slice gives an even tighter Z range. RC-2 (M3) extends the Z
+// toward the light and turns these green. Falsification for RC-2: comment out
+// the z-extend and these reassert RED.
+
+import { World } from '@forgeax/engine-ecs';
+import { mat4, vec3 } from '@forgeax/engine-math';
+import {
+  Camera,
+  DirectionalLight,
+  extractFrame,
+  prepareExtractContext,
+} from '@forgeax/engine-render/internal';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+
+// Light travelling down and toward +x/+z, so the source is up and toward -x/-z.
+const LIGHT_DIR: readonly [number, number, number] = [0.3, -1, 0.3];
+
+// A ground point inside the near cascade's footprint (verified XY-covered by
+// cascade 0 for both N=1 and N=4 with the camera/light below).
+const GROUND_PT: readonly [number, number, number] = [0, 0, -5];
+
+function setupWorld(cascadeCount: number): World {
+  const world = new World();
+  world.spawn({
+    component: DirectionalLight,
+    data: {
+      direction: [LIGHT_DIR[0], LIGHT_DIR[1], LIGHT_DIR[2]],
+      cascadeCount,
+      shadowDistance: 100,
+    },
+  });
+  world.spawn(
+    { component: Transform, data: { pos: [0, 0, 0] } },
+    { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+  );
+
+  return world;
+}
+
+// A world-space occluder above GROUND_PT, pushed toward the light source
+// (opposite the light travel direction). Physically: a box hovering between the
+// sun and the ground -- it MUST be in the cascade depth map for the ground
+// beneath it to be shadowed.
+function towardLightCaster(distanceTowardLight: number): vec3.Vec3 {
+  const lightDirN = vec3.normalize(vec3.create(), vec3.create(...LIGHT_DIR));
+  const groundPt = vec3.create(...GROUND_PT);
+  const offset = vec3.scale(vec3.create(), lightDirN, -distanceTowardLight);
+  return vec3.add(vec3.create(), groundPt, offset);
+}
+
+interface Projected {
+  inXY: boolean;
+  z: number;
+}
+
+function projectInto(lightViewProj: Float32Array, worldPt: vec3.Vec3): Projected {
+  const ndc = vec3.create();
+  mat4.transformVec3(ndc, lightViewProj, worldPt);
+  const x = ndc[0] ?? Number.NaN;
+  const y = ndc[1] ?? Number.NaN;
+  const z = ndc[2] ?? Number.NaN;
+  return { inXY: x >= -1 && x <= 1 && y >= -1 && y <= 1, z };
+}
+
+describe('CSM ortho-Z reaches toward the light (real extract fit, AC-05)', () => {
+  // N=4 is the primary RED case: the thin near slice gives a tight ortho Z, so a
+  // toward-light occluder over near-cascade ground is clipped (z < 0).
+  it('N=4: the cascade covering the ground also captures a toward-light caster (z in [0,1])', () => {
+    const world = setupWorld(4);
+    const frame = extractFrame(world, prepareExtractContext(world));
+    const lvp = frame.lights.lightViewProj;
+    expect(lvp).toBeDefined();
+    if (lvp === undefined) return;
+    const count = frame.lights.cascadeCount ?? 0;
+    expect(count).toBe(4);
+
+    const caster = towardLightCaster(6);
+    const ground = vec3.create(...GROUND_PT);
+    const volumeSet = frame.lights.directionalCsm;
+    expect(volumeSet?.volumes).toBe(volumeSet?.cascades);
+    expect(volumeSet?.revision).toBeGreaterThan(0);
+
+    // Find every cascade whose XY footprint covers the GROUND fragment -- that
+    // is the cascade `_pickCascadeLayer` will route the ground to. The caster
+    // sits directly above that ground, so the SAME cascade must also hold the
+    // caster's depth, otherwise the ground reads "unoccluded".
+    let coveredGroundCascades = 0;
+    for (let c = 0; c < count; c++) {
+      const m = lvp[c];
+      if (!(m instanceof Float32Array)) continue;
+      const volume = volumeSet?.volumes[c];
+      expect(volume?.lightViewProj).toBe(m);
+      expect(volume?.rasterLightBounds).toBe(volume?.clipLightBounds);
+      expect(volume?.depthLightRange).toEqual([
+        volume?.clipLightBounds[4],
+        volume?.clipLightBounds[5],
+      ]);
+      const g = projectInto(m, ground);
+      if (!g.inXY) continue;
+      coveredGroundCascades++;
+      const { z } = projectInto(m, caster);
+      expect(Number.isFinite(z)).toBe(true);
+      expect(z).toBeGreaterThanOrEqual(0);
+      expect(z).toBeLessThanOrEqual(1);
+    }
+    // Guard against a vacuous assertion: at least one cascade must cover the
+    // ground fragment.
+    expect(coveredGroundCascades).toBeGreaterThan(0);
+  });
+
+  it('N=4: near cascade (0) covers the ground and must admit the toward-light caster', () => {
+    const world = setupWorld(4);
+    const frame = extractFrame(world, prepareExtractContext(world));
+    const lvp = frame.lights.lightViewProj;
+    expect(lvp).toBeDefined();
+    if (lvp === undefined) return;
+
+    const m0 = lvp[0];
+    expect(m0).toBeInstanceOf(Float32Array);
+    if (!(m0 instanceof Float32Array)) return;
+
+    // Cascade 0 covers GROUND_PT in XY (precondition for this assertion to
+    // matter).
+    const ground = projectInto(m0, vec3.create(...GROUND_PT));
+    expect(ground.inXY).toBe(true);
+
+    const { z } = projectInto(m0, towardLightCaster(6));
+    expect(z).toBeGreaterThanOrEqual(0);
+    expect(z).toBeLessThanOrEqual(1);
+  });
+});

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

@@ -0,0 +1,142 @@
+// shadow-csm-pssm.test.ts - feat-20260613-csm-cascaded-shadow-maps-unique-shadow-path
+// M2 / w6: PSSM split function unit test (RED, test-first).
+//
+// PSSM formula (plan-strategy section 2 decision D-8):
+//   C_i = λ · n · (f/n)^(i/m) + (1-λ) · (n + i/m · (f-n))
+//   where i = 1..m, m = cascadeCount, n = nearPlane, f = farPlane
+//
+// Covers AC-04: split numerical correctness / monotonicity / λ degeneration /
+// near≈far error / N=1..4 end-to-end.
+
+import { pssmSplit } from '@forgeax/engine-render/internal';
+import { describe, expect, it } from 'vitest';
+
+// ── Hand-calculated anchors ────────────────────────────────────────────────
+//
+// λ=0.75, n=0.1, f=100, m=4:
+//   log  term: n·(f/n)^(i/4) = 0.1 · (1000)^(i/4)
+//   uniform term: n + i/4·(f-n) = 0.1 + i·24.975
+//
+//   i=1: log = 0.1·1000^0.25 = 0.1·5.6234 ≈ 0.5623
+//         uni = 0.1 + 1·24.975 = 25.075
+//         C1  = 0.75·0.5623 + 0.25·25.075 = 0.4217 + 6.2688 = 6.6905
+//
+//   i=2: log = 0.1·1000^0.5 = 0.1·31.6228 ≈ 3.1623
+//         uni = 0.1 + 2·24.975 = 50.05
+//         C2  = 0.75·3.1623 + 0.25·50.05 = 2.3717 + 12.5125 = 14.8842
+//
+//   i=3: log = 0.1·1000^0.75 = 0.1·177.8279 ≈ 17.7828
+//         uni = 0.1 + 3·24.975 = 75.025
+//         C3  = 0.75·17.7828 + 0.25·75.025 = 13.3371 + 18.7563 = 32.0934
+//
+//   i=4: log = 0.1·1000^1.0 = 100.0
+//         uni = 0.1 + 4·24.975 = 100.0
+//         C4  = 0.75·100 + 0.25·100 = 100.0
+//
+// Monotonicity: C1 < C2 < C3 < C4 = 100.0
+
+describe('PSSM split function (w6)', () => {
+  const EPS = 0.01;
+
+  // biome-ignore lint/style/noNonNullAssertion: Float32Array indexed access in test assertions
+  const at = (a: Float32Array, i: number): number => a[i]!;
+
+  // biome-ignore lint/style/noNonNullAssertion: Float32Array indexed access in test assertions
+  const prev = (a: Float32Array, i: number): number => a[i - 1]!;
+
+  describe('λ=1 (pure logarithmic)', () => {
+    it('produces exponentially spaced splits', () => {
+      const result = pssmSplit(0.1, 100, 4, 1.0);
+      expect(result.length).toBe(4);
+      expect(at(result, 0)).toBeCloseTo(0.5623, 2);
+      expect(at(result, 3)).toBeCloseTo(100.0, 4);
+      for (let i = 1; i < 4; i++) {
+        expect(at(result, i)).toBeGreaterThan(prev(result, i));
+      }
+    });
+  });
+
+  describe('λ=0 (pure uniform)', () => {
+    it('produces linearly spaced splits', () => {
+      const result = pssmSplit(0.1, 100, 4, 0);
+      expect(result.length).toBe(4);
+      expect(at(result, 0)).toBeCloseTo(25.075, 2);
+      expect(at(result, 1)).toBeCloseTo(50.05, 2);
+      expect(at(result, 2)).toBeCloseTo(75.025, 2);
+      expect(at(result, 3)).toBeCloseTo(100.0, 4);
+      for (let i = 1; i < 4; i++) {
+        expect(at(result, i)).toBeGreaterThan(prev(result, i));
+      }
+    });
+  });
+
+  describe('λ=0.75 (default PSSM blend)', () => {
+    it('produce monotonically increasing values between log and uniform', () => {
+      const result = pssmSplit(0.1, 100, 4, 0.75);
+      expect(result.length).toBe(4);
+      expect(at(result, 0)).toBeCloseTo(6.6905, 2);
+      expect(at(result, 1)).toBeCloseTo(14.8842, 2);
+      expect(at(result, 2)).toBeCloseTo(32.0934, 2);
+      expect(at(result, 3)).toBeCloseTo(100.0, 3);
+      for (let i = 1; i < 4; i++) {
+        expect(at(result, i)).toBeGreaterThan(prev(result, i));
+      }
+    });
+
+    it('split values lie between pure uniform and pure log', () => {
+      const blend = pssmSplit(0.1, 100, 4, 0.75);
+      const uniform = pssmSplit(0.1, 100, 4, 0);
+      const log = pssmSplit(0.1, 100, 4, 1.0);
+      for (let i = 0; i < 3; i++) {
+        const b = at(blend, i);
+        const u = at(uniform, i);
+        const l = at(log, i);
+        expect(b).toBeGreaterThan(Math.min(l, u) - EPS);
+        expect(b).toBeLessThan(Math.max(l, u) + EPS);
+      }
+    });
+  });
+
+  describe('N=1 (single cascade)', () => {
+    it('returns array with far plane only', () => {
+      const result = pssmSplit(0.1, 100, 1, 0.75);
+      expect(result.length).toBe(1);
+      expect(at(result, 0)).toBeCloseTo(100.0, 4);
+    });
+  });
+
+  describe('N=2..4 end-to-end', () => {
+    it('N=2 produces monotonic 2-element array', () => {
+      const result = pssmSplit(0.1, 100, 2, 0.75);
+      expect(result.length).toBe(2);
+      expect(at(result, 0)).toBeGreaterThan(0);
+      expect(at(result, 0)).toBeLessThan(at(result, 1));
+      expect(at(result, 1)).toBeCloseTo(100.0, 4);
+    });
+
+    it('N=3 produces monotonic 3-element array', () => {
+      const result = pssmSplit(0.1, 100, 3, 0.75);
+      expect(result.length).toBe(3);
+      for (let i = 1; i < 3; i++) {
+        expect(at(result, i)).toBeGreaterThan(prev(result, i));
+      }
+      expect(at(result, 2)).toBeCloseTo(100.0, 4);
+    });
+
+    it('N=4 produces monotonic 4-element array', () => {
+      const result = pssmSplit(0.1, 100, 4, 0.75);
+      expect(result.length).toBe(4);
+      for (let i = 1; i < 4; i++) {
+        expect(at(result, i)).toBeGreaterThan(prev(result, i));
+      }
+      expect(at(result, 3)).toBeCloseTo(100.0, 4);
+    });
+  });
+
+  describe('nearPlane ≈ farPlane degenerate', () => {
+    it('throws ShadowInvalidConfigError when farPlane <= nearPlane + epsilon', () => {
+      expect(() => pssmSplit(10, 10, 4, 0.75)).toThrow();
+      expect(() => pssmSplit(10, 10.0000001, 4, 0.75)).toThrow();
+    });
+  });
+});

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

@@ -0,0 +1,198 @@
+// shadow-csm-runtime-vary.dawn.test.ts - feat-20260613-csm-cascaded-shadow-maps-unique-shadow-path
+// M5 / w26: dynamic cascadeCount + mapSize via world.set dawn-node test.
+//
+// Covers AC-07 (runtime-mutable cascade fields take effect on the next
+// frame; shadow atlas RT rebuilds on mapSize change without device error)
+// + AC-10 (cascadeCount=1 degeneracy renders cleanly through the same
+// pathway).
+//
+// Strategy: spin up a renderer with a minimal directional-light + shadow
+// scene, draw N frames at cascadeCount=4, mutate to cascadeCount=2 via
+// world.set and draw, mutate to cascadeCount=4 again, then walk
+// mapSize 2048 -> 1024 -> 2048 the same way. Asserts every draw returns
+// `ok: true` and no device-lost / structured RhiError fires.
+//
+// best-effort: we do not pixel-readback (M3 atlas slot debugReadback was
+// retuned in w28 transitional); the gate is "render loop completes
+// without device error".
+
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import { Camera, DirectionalLight } from '@forgeax/engine-render/internal';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { createRenderer } from '../createRenderer';
+import { drawPublished } from './draw-published';
+
+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),
+)}`;
+
+// biome-ignore lint/suspicious/noExplicitAny: dawn-node detection guard
+const dawnReady = typeof navigator !== 'undefined' && (navigator as any).gpu !== undefined;
+
+const WIDTH = 320;
+const HEIGHT = 240;
+
+interface MockCanvas {
+  width: number;
+  height: number;
+  getContext(kind: string): unknown;
+}
+
+function createMockCanvas(): MockCanvas {
+  let renderTarget: GPUTexture | undefined;
+  let sharedDevice: GPUDevice | undefined;
+  return {
+    width: WIDTH,
+    height: HEIGHT,
+    getContext(kind: string): unknown {
+      if (kind !== 'webgpu') return null;
+      return {
+        configure(desc: { device: GPUDevice; format: GPUTextureFormat }): void {
+          sharedDevice = desc.device;
+          if (renderTarget === undefined) {
+            renderTarget = desc.device.createTexture({
+              size: { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+              format: desc.format,
+              usage: 0x10 | 0x01,
+              viewFormats: ['rgba8unorm-srgb'],
+            });
+          }
+        },
+        unconfigure(): void {},
+        getCurrentTexture(): GPUTexture {
+          if (renderTarget === undefined && sharedDevice !== undefined) {
+            renderTarget = sharedDevice.createTexture({
+              size: { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+              format: 'rgba8unorm',
+              usage: 0x10 | 0x01,
+              viewFormats: ['rgba8unorm-srgb'],
+            });
+          }
+          if (renderTarget === undefined) throw new Error('no render target');
+          return renderTarget;
+        },
+      };
+    },
+  };
+}
+
+interface SceneEntities {
+  world: World;
+  shadowEntity: EntityHandle;
+}
+
+function buildScene(initialCascadeCount: number, initialMapSize: number): SceneEntities {
+  const world = new World();
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 5, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+      { component: Camera, data: { fov: 1.0472, near: 0.1, far: 60 } },
+    )
+    .unwrap();
+  const shadowEntity = world
+    .spawn(
+      {
+        component: DirectionalLight,
+        data: {
+          direction: [0, -1, 0],
+          color: [1, 1, 1],
+          intensity: 1,
+        },
+      },
+      {
+        component: DirectionalLight,
+        data: {
+          direction: [0, -1, 0],
+          mapSize: initialMapSize,
+          shadowDistance: 50,
+          cascadeCount: initialCascadeCount,
+        },
+      },
+    )
+    .unwrap();
+  return { world, shadowEntity };
+}
+
+describe('CSM runtime cascade + mapSize variation (M5/w26)', () => {
+  it.skipIf(!dawnReady)("'dawn-binding-missing' -- dawn.node binding injection failed", () => {
+    expect(dawnReady).toBe(true);
+  });
+
+  it('cascadeCount 4 -> 2 -> 4 round-trip without device error', async () => {
+    if (!dawnReady) return;
+    const canvas = createMockCanvas();
+    const renderer = await createRenderer(
+      canvas as unknown as HTMLCanvasElement,
+      {},
+      { shaderManifestUrl: ENGINE_MANIFEST_URL },
+    );
+    const ready = await renderer.ready;
+    expect(ready.ok).toBe(true);
+    const { world, shadowEntity } = buildScene(4, 2048);
+
+    expect(drawPublished(renderer, world).ok).toBe(true);
+
+    world.set(shadowEntity, DirectionalLight, {
+      mapSize: 2048,
+      shadowDistance: 50,
+      cascadeCount: 2,
+    });
+    expect(drawPublished(renderer, world).ok).toBe(true);
+
+    world.set(shadowEntity, DirectionalLight, {
+      mapSize: 2048,
+      shadowDistance: 50,
+      cascadeCount: 4,
+    });
+    expect(drawPublished(renderer, world).ok).toBe(true);
+  });
+
+  it('mapSize 2048 -> 1024 -> 2048 RT rebuild without device error', async () => {
+    if (!dawnReady) return;
+    const canvas = createMockCanvas();
+    const renderer = await createRenderer(
+      canvas as unknown as HTMLCanvasElement,
+      {},
+      { shaderManifestUrl: ENGINE_MANIFEST_URL },
+    );
+    const ready = await renderer.ready;
+    expect(ready.ok).toBe(true);
+    const { world, shadowEntity } = buildScene(4, 2048);
+
+    expect(drawPublished(renderer, world).ok).toBe(true);
+
+    world.set(shadowEntity, DirectionalLight, {
+      mapSize: 1024,
+      shadowDistance: 50,
+      cascadeCount: 4,
+    });
+    expect(drawPublished(renderer, world).ok).toBe(true);
+
+    world.set(shadowEntity, DirectionalLight, {
+      mapSize: 2048,
+      shadowDistance: 50,
+      cascadeCount: 4,
+    });
+    expect(drawPublished(renderer, world).ok).toBe(true);
+  });
+
+  it('cascadeCount=1 renders through the unified pathway (AC-10)', async () => {
+    if (!dawnReady) return;
+    const canvas = createMockCanvas();
+    const renderer = await createRenderer(
+      canvas as unknown as HTMLCanvasElement,
+      {},
+      { shaderManifestUrl: ENGINE_MANIFEST_URL },
+    );
+    const ready = await renderer.ready;
+    expect(ready.ok).toBe(true);
+    const { world } = buildScene(1, 1024);
+    expect(drawPublished(renderer, world).ok).toBe(true);
+  });
+});