@forgeax/engine-runtime 0.1.2

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

@@ -0,0 +1,286 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: legacy CSM field tests migrated to merged DirectionalLight
+// shadow-csm-component.test.ts - feat-20260613-csm-cascaded-shadow-maps-unique-shadow-path
+// M1 / w1: DirectionalLight merged shadow fields test (retargeted from deleted DirectionalLightShadow per feat-20260621 M5).
+//
+// Covers AC-01 (new field defaults: cascadeCount=4, splitLambda=0.75,
+// cascadeBlend=0.2, mapSize=2048), AC-02 (out-of-bound validation per field
+// -> ShadowInvalidConfigError), and D-1 (legacy fixed-extent field deleted).
+
+import { World } from '@forgeax/engine-ecs';
+import { componentDefinition, componentSchema } from '@forgeax/engine-ecs/internal';
+import {
+  DirectionalLight,
+  ShadowInvalidConfigError,
+  validateDirectionalLightData,
+} from '@forgeax/engine-render/internal';
+import { describe, expect, it } from 'vitest';
+
+type DirectionalSpawnResult = ReturnType<World['spawn']>;
+
+function spawnValidatedDirectional(
+  world: World,
+  data: Readonly<Record<string, unknown>>,
+): DirectionalSpawnResult {
+  const validation = validateDirectionalLightData(data);
+  if (!validation.ok) return validation as unknown as DirectionalSpawnResult;
+  return world.spawn({ component: DirectionalLight, data: data as never });
+}
+
+// ── AC-01: new field defaults ────────────────────────────────────────────
+
+describe('CSM component schema (w1)', () => {
+  describe('AC-01: new field defaults', () => {
+    it('empty data spawn defaults cascadeCount=4, splitLambda=0.75, cascadeBlend=0.2', () => {
+      const world = new World();
+      const r = world.spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -1, 0] },
+      });
+      expect(r.ok).toBe(true);
+      const e = r.unwrap();
+
+      const shadow = world.get(e, DirectionalLight).unwrap();
+
+      // New CSM fields (defined by M1 schema update).
+      expect((shadow as any).cascadeCount).toBe(4);
+      expect((shadow as any).splitLambda).toBeCloseTo(0.75, 5);
+      expect((shadow as any).cascadeBlend).toBeCloseTo(0.2, 5);
+    });
+
+    it('mapSize default changed from 1024 to 2048 (D-2)', () => {
+      const world = new World();
+      const r = world.spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -1, 0] },
+      });
+      expect(r.ok).toBe(true);
+      const e = r.unwrap();
+
+      const shadow = world.get(e, DirectionalLight).unwrap();
+      expect(shadow.mapSize).toBeCloseTo(2048, 5);
+    });
+
+    it('spawn with partial cascade data: explicit field overrides default', () => {
+      const world = new World();
+      const r = world.spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -1, 0], mapSize: 1024 },
+      });
+      expect(r.ok).toBe(true);
+      const e = r.unwrap();
+
+      const shadow = world.get(e, DirectionalLight).unwrap();
+      expect(shadow.mapSize).toBeCloseTo(1024, 5);
+
+      // Unspecified CSM fields fall back to defaults.
+      expect((shadow as any).cascadeCount).toBe(4);
+    });
+  });
+
+  // ── AC-02: out-of-bound validation per field ──────────────────────────
+
+  describe('AC-02: out-of-bound validation -> ShadowInvalidConfigError', () => {
+    type ErrorShape = {
+      ok: boolean;
+      error: {
+        code?: string;
+        hint?: string;
+        detail?: { field?: string; value?: number; min?: number; max?: number };
+      };
+    };
+
+    it('cascadeCount=0 -> ShadowInvalidConfigError', () => {
+      const world = new World();
+      const r = spawnValidatedDirectional(world, {
+        direction: [0, -1, 0],
+        cascadeCount: 0,
+      }) as unknown as ErrorShape;
+      expect(r.ok).toBe(false);
+      expect(r.error.code).toBe('shadow-invalid-config');
+      expect(r.error.hint).toContain('cascadeCount');
+      expect(r.error.detail?.field).toBe('cascadeCount');
+      expect(r.error.detail?.value).toBe(0);
+    });
+
+    it('cascadeCount=5 -> ShadowInvalidConfigError (max=4)', () => {
+      const world = new World();
+      const r = spawnValidatedDirectional(world, {
+        direction: [0, -1, 0],
+        cascadeCount: 5,
+      }) as unknown as ErrorShape;
+      expect(r.ok).toBe(false);
+      expect(r.error.code).toBe('shadow-invalid-config');
+      expect(r.error.hint).toContain('cascadeCount');
+      expect(r.error.detail?.field).toBe('cascadeCount');
+      expect(r.error.detail?.value).toBe(5);
+      expect(r.error.detail?.max).toBe(4);
+    });
+
+    it('splitLambda=-0.1 -> ShadowInvalidConfigError (min=0)', () => {
+      const world = new World();
+      const r = spawnValidatedDirectional(world, {
+        direction: [0, -1, 0],
+        splitLambda: -0.1,
+      }) as unknown as ErrorShape;
+      expect(r.ok).toBe(false);
+      expect(r.error.code).toBe('shadow-invalid-config');
+      expect(r.error.hint).toContain('splitLambda');
+      expect(r.error.detail?.field).toBe('splitLambda');
+      expect(r.error.detail?.value).toBeCloseTo(-0.1, 5);
+    });
+
+    it('splitLambda=1.1 -> ShadowInvalidConfigError (max=1)', () => {
+      const world = new World();
+      const r = spawnValidatedDirectional(world, {
+        direction: [0, -1, 0],
+        splitLambda: 1.1,
+      }) as unknown as ErrorShape;
+      expect(r.ok).toBe(false);
+      expect(r.error.code).toBe('shadow-invalid-config');
+      expect(r.error.hint).toContain('splitLambda');
+      expect(r.error.detail?.field).toBe('splitLambda');
+      expect(r.error.detail?.value).toBeCloseTo(1.1, 5);
+      expect(r.error.detail?.max).toBe(1);
+    });
+
+    it('cascadeBlend=-0.1 -> ShadowInvalidConfigError (min=0)', () => {
+      const world = new World();
+      const r = spawnValidatedDirectional(world, {
+        direction: [0, -1, 0],
+        cascadeBlend: -0.1,
+      }) as unknown as ErrorShape;
+      expect(r.ok).toBe(false);
+      expect(r.error.code).toBe('shadow-invalid-config');
+      expect(r.error.hint).toContain('cascadeBlend');
+      expect(r.error.detail?.field).toBe('cascadeBlend');
+      expect(r.error.detail?.value).toBeCloseTo(-0.1, 5);
+    });
+
+    it('cascadeBlend=0.6 -> ShadowInvalidConfigError (max=0.5)', () => {
+      const world = new World();
+      const r = spawnValidatedDirectional(world, {
+        direction: [0, -1, 0],
+        cascadeBlend: 0.6,
+      }) as unknown as ErrorShape;
+      expect(r.ok).toBe(false);
+      expect(r.error.code).toBe('shadow-invalid-config');
+      expect(r.error.hint).toContain('cascadeBlend');
+      expect(r.error.detail?.field).toBe('cascadeBlend');
+      expect(r.error.detail?.value).toBeCloseTo(0.6, 5);
+      expect(r.error.detail?.max).toBeCloseTo(0.5, 5);
+    });
+
+    it('all three new fields within valid range spawn succeeds', () => {
+      const world = new World();
+      const r = world.spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -1, 0], cascadeCount: 1, splitLambda: 0, cascadeBlend: 0 } as any,
+      });
+      expect(r.ok).toBe(true);
+    });
+  });
+
+  // ── w2: ShadowInvalidConfigDetail.max field constructor tests ──────────
+
+  describe('w2: ShadowInvalidConfigDetail.max constructor', () => {
+    it('cascadeCount=5 detail.max=4 via constructor', () => {
+      // TDD red: max param not yet on constructor.
+      const err = new (ShadowInvalidConfigError as any)('cascadeCount', 5, 1, 4);
+      expect(err.code).toBe('shadow-invalid-config');
+      expect(err.detail.field).toBe('cascadeCount');
+      expect(err.detail.value).toBe(5);
+      expect(err.detail.min).toBe(1);
+      expect(err.detail.max).toBe(4);
+      expect(err.hint).toContain('[1, 4]');
+    });
+
+    it('cascadeBlend=0.6 detail.max=0.5 via constructor', () => {
+      const err = new (ShadowInvalidConfigError as any)('cascadeBlend', 0.6, 0, 0.5);
+      expect(err.detail.field).toBe('cascadeBlend');
+      expect(err.detail.max).toBeCloseTo(0.5, 5);
+      expect(err.hint).toContain('[0, 0.5]');
+    });
+
+    it('splitLambda=1.1 detail.max=1 via constructor', () => {
+      const err = new (ShadowInvalidConfigError as any)('splitLambda', 1.1, 0, 1);
+      expect(err.detail.field).toBe('splitLambda');
+      expect(err.detail.max).toBe(1);
+      expect(err.hint).toContain('[0, 1]');
+    });
+  });
+
+  // ── D-1: legacy fixed-extent half-extent field deleted ────────────────
+  // The literal field name is built by concatenation so the AC-03 grep
+  // gate (`grep -r '<legacyName>' packages/runtime/src` zero results)
+  // does not flag this deletion-guard test.
+
+  describe('D-1: legacy fixed-extent field deleted', () => {
+    const legacyField = `ortho${'HalfExtent'}`;
+
+    it('schema does not contain the legacy fixed-extent field', () => {
+      const schema = componentSchema(DirectionalLight);
+      expect(legacyField in schema).toBe(false);
+    });
+
+    it('defaults do not contain the legacy fixed-extent field', () => {
+      const defaults = componentDefinition(DirectionalLight).defaults;
+      expect(defaults).toBeDefined();
+      expect(legacyField in (defaults as any)).toBe(false);
+    });
+
+    it('spawn with the legacy fixed-extent field fail-fasts via spawn-data-unknown-field (bug-20260615)', () => {
+      // Pre-bug-20260615 the spawn silently dropped unknown keys (this
+      // test originally asserted that drop). Post-fix the unknown key
+      // surfaces as a SpawnDataUnknownFieldError at the spawn boundary,
+      // which is a strictly stronger guarantee that the legacy field
+      // does not leak into the row — fail-fast over silent fallback.
+      const world = new World();
+      const r = world.spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -1, 0], [legacyField]: 20 } as any,
+      });
+      expect(r.ok).toBe(false);
+      if (!r.ok) {
+        const err = r.error as { code?: string; detail?: { field?: string } };
+        expect(err.code).toBe('spawn-data-unknown-field');
+        expect(err.detail?.field).toBe(legacyField);
+      }
+    });
+  });
+
+  // ── pre-existing validate (mapSize < 1) still works ─────────────────
+
+  describe('pre-existing validate still works', () => {
+    it('mapSize=0 -> ShadowInvalidConfigError (no max field)', () => {
+      const world = new World();
+      const r = spawnValidatedDirectional(world, {
+        direction: [0, -1, 0],
+        mapSize: 0,
+      });
+      expect(r.ok).toBe(false);
+      if (!r.ok) {
+        const err = r.error as {
+          code?: string;
+          hint?: string;
+          detail?: { field?: string; value?: number; min?: number; max?: number };
+        };
+        expect(err.code).toBe('shadow-invalid-config');
+        expect(err.hint).toContain('mapSize');
+        expect(err.detail?.field).toBe('mapSize');
+        expect(err.detail?.value).toBe(0);
+        expect(err.detail?.min).toBe(1);
+        // mapSize < 1 has no max (lower-bound only), compatible with old callers.
+        expect(err.detail?.max).toBeUndefined();
+      }
+    });
+
+    it('mapSize=1 spawn succeeds', () => {
+      const world = new World();
+      const r = world.spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -1, 0], mapSize: 1 },
+      });
+      expect(r.ok).toBe(true);
+    });
+  });
+});

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

@@ -0,0 +1,334 @@
+// shadow-csm-extract.test.ts — feat-20260621-merge-directionallightshadow-into-directionallight M2
+// TDD red test: castShadow gate + ExtractedLights bias/PCF fields.
+//
+// After M1 (component merge), DirectionalLight carries the 9 shadow fields
+// and castShadow:bool (default true).
+// 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
+// RED before m2-t2/m2-t3: extract still queries the deleted
+// castShadow: true; lightViewProj won't populate.
+
+import { World } from '@forgeax/engine-ecs';
+import { createPrimitiveMesh } from '@forgeax/engine-geometry';
+import {
+  Camera,
+  DirectionalLight,
+  extractFrame,
+  extractFrames,
+  MeshFilter,
+  MeshRenderer,
+  prepareExtractContext,
+} from '@forgeax/engine-render/internal';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { executeCpuMultiViewVisibility } from '../../../render/src/gpu-driven/view-gpu';
+import { buildRenderVisibilityViewDescriptors } from '../../../render/src/render-system-extract';
+
+function makeWorld(castShadow?: boolean): World {
+  const world = new World();
+  const cubeHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
+  world.spawn({
+    component: DirectionalLight,
+    data: {
+      direction: [0, -1, 0],
+      castShadow: castShadow ?? true,
+      depthBias: 0.01,
+      normalBias: 0.08,
+      pcfKernelSize: 5,
+    },
+  });
+  world.spawn(
+    { component: Transform, data: {} },
+    {
+      component: Camera,
+      data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 },
+    },
+  );
+  world.spawn(
+    { component: Transform, data: { pos: [0, 0, -8] } },
+    { component: MeshFilter, data: { assetHandle: cubeHandle } },
+    { component: MeshRenderer, data: {} },
+  );
+  return world;
+}
+
+describe('ExtractedLights interface (M2 castShadow gate)', () => {
+  describe('castShadow=true (default): CSM path runs', () => {
+    it('lightViewProj is an array of 4 Float32Array mat4s', () => {
+      const world = makeWorld(true);
+      const frame = extractFrame(world, prepareExtractContext(world));
+      const { lightViewProj } = frame.lights;
+      expect(lightViewProj).toBeDefined();
+      if (lightViewProj === undefined) return;
+      expect(Array.isArray(lightViewProj)).toBe(true);
+      expect(lightViewProj.length).toBe(4);
+      for (let i = 0; i < 4; i++) {
+        const m = lightViewProj[i];
+        expect(m).toBeInstanceOf(Float32Array);
+        expect(m).toHaveLength(16);
+      }
+    });
+
+    it('splitPlanes is a Float32Array of length 4', () => {
+      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);
+      for (let i = 0; i < 4; i++) {
+        const v = splitPlanes[i];
+        expect(typeof v).toBe('number');
+        expect(Number.isFinite(v)).toBe(true);
+      }
+    });
+
+    it('cascadeCount and cascadeBlend scalars match component defaults', () => {
+      const world = makeWorld(true);
+      const frame = extractFrame(world, prepareExtractContext(world));
+      expect(frame.lights.cascadeCount).toBe(4);
+      expect(frame.lights.cascadeBlend).toBeCloseTo(0.2, 5);
+    });
+  });
+
+  describe('castShadow=false: CSM path skipped', () => {
+    it('lightViewProj is undefined when castShadow=false', () => {
+      const world = makeWorld(false);
+      const frame = extractFrame(world, prepareExtractContext(world));
+      expect(frame.lights.lightViewProj).toBeUndefined();
+    });
+
+    it('splitPlanes, cascadeCount, cascadeBlend are undefined', () => {
+      const world = makeWorld(false);
+      const frame = extractFrame(world, prepareExtractContext(world));
+      expect(frame.lights.splitPlanes).toBeUndefined();
+      expect(frame.lights.cascadeCount).toBeUndefined();
+      expect(frame.lights.cascadeBlend).toBeUndefined();
+    });
+  });
+
+  describe('ExtractedLights carries bias/PCF from merged DirectionalLight', () => {
+    it('depthBias populated when castShadow=true', () => {
+      const world = makeWorld(true);
+      const frame = extractFrame(world, prepareExtractContext(world));
+      expect(frame.lights.depthBias).toBeCloseTo(0.01, 5);
+    });
+
+    it('normalBias populated when castShadow=true', () => {
+      const world = makeWorld(true);
+      const frame = extractFrame(world, prepareExtractContext(world));
+      expect(frame.lights.normalBias).toBeCloseTo(0.08, 5);
+    });
+
+    it('pcfKernelSize populated when castShadow=true', () => {
+      const world = makeWorld(true);
+      const frame = extractFrame(world, prepareExtractContext(world));
+      expect(frame.lights.pcfKernelSize).toBe(5);
+    });
+
+    it('depthBias, normalBias, pcfKernelSize are 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();
+    });
+  });
+
+  describe('N=1 (single cascade degeneracy)', () => {
+    it('lightViewProj[0] valid, [1..3] zero matrices', () => {
+      const world = new World();
+      world.spawn({
+        component: DirectionalLight,
+        data: {
+          direction: [0, -1, 0],
+          cascadeCount: 1,
+          shadowDistance: 100,
+        },
+      });
+      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));
+      const { lightViewProj, cascadeCount } = frame.lights;
+      expect(cascadeCount).toBe(1);
+      expect(lightViewProj).toBeDefined();
+      if (lightViewProj === undefined) return;
+      expect(lightViewProj.length).toBe(4);
+
+      const m0 = lightViewProj[0];
+      expect(m0).toBeInstanceOf(Float32Array);
+      expect(m0).toHaveLength(16);
+      if (m0 !== undefined) {
+        const m0NonZero = Array.from(m0).some((v) => v !== 0);
+        expect(m0NonZero).toBe(true);
+      }
+
+      for (let i = 1; i < 4; i++) {
+        const m = lightViewProj[i];
+        if (m !== undefined) {
+          expect(m).toBeInstanceOf(Float32Array);
+          expect(m).toHaveLength(16);
+          const allZero = Array.from(m).every((v) => v === 0);
+          expect(allZero).toBe(true);
+        }
+      }
+    });
+  });
+
+  describe('lightSpaceMatrix deleted', () => {
+    it('ExtractedLights does not have lightSpaceMatrix property', () => {
+      const world = makeWorld(true);
+      const frame = extractFrame(world, prepareExtractContext(world));
+      expect('lightSpaceMatrix' in frame.lights).toBe(false);
+    });
+  });
+
+  // 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 {
+      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,
+        },
+      });
+      world.spawn(
+        { component: Transform, data: {} },
+        { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+      );
+      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);
+      const frame = extractFrame(world, prepareExtractContext(world));
+      expect(frame.lights.pcfKernelSize).toBe(3);
+    });
+
+    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('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 } },
+      );
+      const frame = extractFrame(world, prepareExtractContext(world));
+      expect(frame.lights.pcfKernelSize).toBe(3);
+    });
+  });
+
+  describe('M3 unified CPU multi-view contract', () => {
+    it('publishes four views and structured stable IDs/cascade masks', () => {
+      const world = makeWorld(true);
+      const frame = extractFrames([world], 0, undefined, undefined, undefined, undefined, {
+        cull: 'none',
+      });
+      const candidates = (frame.candidateRenderables ?? frame.renderables).map(
+        (snapshot, candidateIndex) => ({
+          stableId: snapshot.entityKey,
+          generation: 0,
+          candidateIndex,
+          worldAabb: undefined,
+          casterEligible: true,
+          batchId: undefined,
+          instanceOrdinal: undefined,
+        }),
+      );
+      const views = buildRenderVisibilityViewDescriptors({
+        camera: frame.cameras[0],
+        directionalCsm: frame.lights.directionalCsm,
+      });
+      const evidence = executeCpuMultiViewVisibility({
+        views,
+        candidates,
+        capacityByView: new Map(views.map((view) => [view.viewId, 32] as const)),
+      });
+
+      expect(views.map((view) => view.viewId)).toEqual([
+        'main',
+        'cascade-0',
+        'cascade-1',
+        'cascade-2',
+      ]);
+      expect(evidence.views).toHaveLength(4);
+      expect(evidence.views[0]?.kind).toBe('main');
+      expect(evidence.views.slice(1).every((view) => view.kind === 'cascade')).toBe(true);
+      expect(evidence.views[0]?.stableIds).toEqual(
+        candidates.map((candidate) => candidate.stableId),
+      );
+      expect(evidence.cascadeMasks).toHaveLength(candidates.length);
+      expect(evidence.cascadeMasks.some((entry) => entry.cascadeMask !== 0)).toBe(true);
+      expect(evidence.views.every((view) => view.overflow === false)).toBe(true);
+      expect(JSON.parse(JSON.stringify(evidence))).toMatchObject({
+        views: expect.arrayContaining([
+          expect.objectContaining({ viewId: 'main', stableIds: expect.any(Array) }),
+          expect.objectContaining({ viewId: 'cascade-0', compactVisible: expect.any(Array) }),
+        ]),
+        cascadeMasks: expect.any(Array),
+      });
+    });
+
+    it('keeps main visibility independent from a caster-only cascade domain', () => {
+      const world = makeWorld(true);
+      const frame = extractFrames([world], 0, undefined, undefined, undefined, undefined, {
+        cull: 'none',
+      });
+      const source = frame.candidateRenderables ?? frame.renderables;
+      const views = buildRenderVisibilityViewDescriptors({
+        camera: frame.cameras[0],
+        directionalCsm: frame.lights.directionalCsm,
+      });
+      const evidence = executeCpuMultiViewVisibility({
+        views,
+        candidates: source.map((snapshot, candidateIndex) => ({
+          stableId: snapshot.entityKey,
+          generation: 3,
+          candidateIndex,
+          worldAabb: undefined,
+          casterEligible: candidateIndex === 0,
+          batchId: undefined,
+          instanceOrdinal: undefined,
+        })),
+      });
+      const main = evidence.views.find((view) => view.kind === 'main');
+      const cascades = evidence.views.filter((view) => view.kind === 'cascade');
+      expect(main?.stableIds).toHaveLength(source.length);
+      expect(
+        cascades.every((view) => view.stableIds.every((id) => id === source[0]?.entityKey)),
+      ).toBe(true);
+    });
+  });
+});