@forgeax/engine-render 0.1.19 → 0.1.20

package/src/__tests__/volumetric-fog-light-transaction.integration.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import {
+  recoverVolumetricFog,
+  stageVolumetricFog,
+  type VolumeRecoveryState,
+} from '../volume/recovery';
+
+const selected = { entity: 19, kind: 'spot' as const, revision: 8, shadowTile: 2 };
+const state = {
+  guid: 'density-guid',
+  generation: 4,
+  deviceEpoch: 2,
+  status: 'accepted' as const,
+  selectedLight: selected,
+};
+
+describe('selected volumetric light transaction', () => {
+  it('keeps selected light LKG when candidate submit fails', () => {
+    const staged = stageVolumetricFog(
+      state as VolumeRecoveryState,
+      {
+        generation: 5,
+        digest: 'candidate-digest',
+        selectedLight: { ...selected, revision: 9 },
+      } as never,
+    );
+    const failed = recoverVolumetricFog(staged, { kind: 'submit-failed' });
+    expect(failed).toMatchObject({
+      status: 'degraded',
+      generation: 4,
+      selectedLight: selected,
+      candidateFailure: 'submit-failed',
+    });
+  });
+
+  it('does not promote a candidate from a stale device generation', () => {
+    const staged = stageVolumetricFog(
+      state as VolumeRecoveryState,
+      {
+        generation: 5,
+        digest: 'candidate-digest',
+        selectedLight: selected,
+      } as never,
+    );
+    const stale = recoverVolumetricFog(staged, { kind: 'accepted', generation: 4 });
+    expect(stale).toMatchObject({
+      status: 'degraded',
+      generation: 4,
+      selectedLight: selected,
+      candidateFailure: 'stale-generation',
+    });
+  });
+});

package/src/__tests__/volumetric-fog-m9-watcher.integration.test.ts

@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const watcherSource = readFileSync(
+  fileURLToPath(
+    new URL('../../../vite-plugin-pack/src/dev/plugin-server-configure.ts', import.meta.url),
+  ),
+  'utf8',
+);
+
+describe('volumetric fog M9 watcher contract', () => {
+  it('uses the watcher transaction as the refresh suppression owner', () => {
+    expect(watcherSource).toContain('classifyWatchedPath');
+    expect(watcherSource).toContain('rebuildState');
+    expect(watcherSource).toContain("rebuildStatus === 'serving'");
+    expect(watcherSource).not.toContain('catalogChanged');
+    expect(watcherSource).not.toContain('catalogSourceChanged');
+  });
+
+  it('keeps degraded rebuilds on the LKG diagnostic path', () => {
+    expect(watcherSource).toContain("authority: 'degraded'");
+    expect(watcherSource).toContain('Refreshing the page here would discard that recovery path');
+    expect(watcherSource).toContain("rebuildStatus === 'degraded'");
+    expect(watcherSource).toContain("rebuildStatus === 'failed'");
+  });
+});

package/src/__tests__/volumetric-fog-point-light-owner.integration.test.ts

@@ -0,0 +1,44 @@
+import { World } from '@forgeax/engine-ecs';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { PointLight, SpotLight } from '../index';
+import { resolveVolumetricFogLightPair } from '../volume/capability';
+
+describe('volumetric fog punctual owner selection', () => {
+  it('keeps Point and Spot identities distinct in one accepted pair', () => {
+    const world = new World();
+    const point = world
+      .spawn(
+        { component: Transform, data: { pos: [0, 1.4, 0] } },
+        { component: PointLight, data: {} },
+      )
+      .unwrap();
+    const spot = world
+      .spawn(
+        { component: Transform, data: { pos: [2.5, 5, 2.5] } },
+        { component: SpotLight, data: { direction: [-2.5, -5, -2.5] } },
+      )
+      .unwrap();
+    expect(resolveVolumetricFogLightPair(world, point, spot)).toEqual({
+      status: 'available',
+      mode: 'point-spot',
+      point,
+      spot,
+    });
+  });
+
+  it('rejects same entity and foreign-world handles without synthesizing lights', () => {
+    const world = new World();
+    const other = new World();
+    const point = other
+      .spawn(
+        { component: Transform, data: { pos: [0, 1, 0] } },
+        { component: PointLight, data: {} },
+      )
+      .unwrap();
+    expect(resolveVolumetricFogLightPair(world, point, point)).toMatchObject({
+      status: 'unresolved',
+      reason: 'missing-entity',
+    });
+  });
+});

package/src/__tests__/volumetric-fog-point-spot-accumulation.integration.test.ts

@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const inject = readFileSync(
+  new URL('../../../shader/src/volume/volume-inject.wgsl', import.meta.url),
+  'utf8',
+);
+const integrate = readFileSync(
+  new URL('../../../shader/src/volume/volume-integrate.wgsl', import.meta.url),
+  'utf8',
+);
+const passes = readFileSync(new URL('../volume/passes.ts', import.meta.url), 'utf8');
+
+describe('volumetric fog Point and Spot accumulation', () => {
+  it('accumulates Point and Spot in one fixed inject stage', () => {
+    expect(inject).toContain('pointLightsBuffer');
+    expect(inject).toContain('spotLightsBuffer');
+    expect(inject).toContain('evalVolumePoint');
+    expect(inject).toContain('evalVolumeSpot');
+    expect(inject).toContain('shadow_visibility');
+    expect(integrate).toContain('evalVolumePoint');
+    expect(integrate).toContain('evalVolumeSpot');
+    expect(integrate).toContain('scattering = scattering +');
+  });
+
+  it('keeps the four-pass topology and has no synthetic beam pass', () => {
+    expect(passes).toContain("'volume-inject'");
+    expect(passes).toContain("'volume-integrate'");
+    expect(passes).toContain("'volume-temporal'");
+    expect(passes).toContain("'volume-composite'");
+    expect(passes).not.toContain('volume-beam');
+    expect(passes).not.toContain('godray');
+    const declaredOrder = passes.match(
+      /export const VOLUMETRIC_FOG_PASS_ORDER = \[([\s\S]*?)\] as const/,
+    )?.[1];
+    expect(declaredOrder?.match(/'volume-[a-z-]+'/g)).toHaveLength(4);
+  });
+
+  it('retains falsifier hooks for off lights, occluders, and shadow visibility', () => {
+    expect(inject).toContain('count');
+    expect(inject).toContain('shadowAtlasTile');
+    expect(inject).toContain('return 0.0');
+    expect(integrate).toContain('evalSpotAttenuation');
+    expect(integrate).toContain('let shadow_visibility =');
+    expect(integrate).toContain('mix(1.0, shadow_visibility, volume_spot_shadow_intensity())');
+    expect(integrate).not.toContain('shadow_visibility * attenuation');
+    expect(integrate).toContain('transmittance');
+  });
+});

package/src/__tests__/volumetric-fog-point-spot-contract.unit.test.ts

@@ -0,0 +1,28 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const componentSource = readFileSync(new URL('../volume/component.ts', import.meta.url), 'utf8');
+const capabilitySource = readFileSync(new URL('../volume/capability.ts', import.meta.url), 'utf8');
+
+describe('VolumetricFog exact Point+Spot authoring contract', () => {
+  it('exposes a closed pair instead of a single selected light', () => {
+    expect(componentSource).toMatch(/readonly light:\s*EntityHandle/);
+    expect(componentSource).toMatch(/readonly spotLight\??:\s*EntityHandle/);
+    expect(capabilitySource).toContain("'point-spot'");
+    expect(capabilitySource).toContain('PointLight');
+  });
+
+  it('keeps pair selection same-World and rejects arbitrary light counts', () => {
+    expect(capabilitySource).toContain('same World');
+    expect(capabilitySource).toMatch(/exactly (one|two)|ambiguous/);
+    expect(capabilitySource).not.toContain('forEachLight');
+    expect(capabilitySource).not.toContain('lights: EntityHandle[]');
+  });
+
+  it('retains structured failure fields for invalid pair authoring', () => {
+    expect(componentSource).toMatch(/code/);
+    expect(componentSource).toMatch(/expected/);
+    expect(componentSource).toMatch(/hint/);
+    expect(componentSource).toMatch(/detail/);
+  });
+});

package/src/__tests__/volumetric-fog-point-spot-lkg.integration.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import {
+  recoverVolumetricFog,
+  stageVolumetricFog,
+  type VolumeRecoveryState,
+} from '../volume/recovery';
+
+const selectedLight = {
+  entity: 19,
+  kind: 'point' as const,
+  revision: 8,
+  shadowTile: 2,
+  projector: {
+    guid: 'projector-guid',
+    generation: 3,
+    view: 'spot-view-7',
+    sampler: 'linear-clamp',
+    projection: 'spot-projection-7',
+    revision: 11,
+  },
+};
+
+const state: VolumeRecoveryState = {
+  guid: 'density-guid',
+  generation: 4,
+  deviceEpoch: 2,
+  status: 'accepted',
+  selectedLight,
+};
+
+describe('Point+Spot volumetric LKG transaction', () => {
+  it('keeps the accepted pair and projector tuple after submit failure', () => {
+    const staged = stageVolumetricFog(state, {
+      generation: 5,
+      digest: 'candidate-digest',
+      selectedLight: {
+        ...selectedLight,
+        revision: 9,
+        projector: { ...selectedLight.projector, revision: 12 },
+      },
+    });
+    const failed = recoverVolumetricFog(staged, { kind: 'submit-failed' });
+    expect(failed).toMatchObject({
+      status: 'degraded',
+      generation: 4,
+      selectedLight,
+      candidateFailure: 'submit-failed',
+    });
+  });
+
+  it('does not promote a projector candidate from a stale generation', () => {
+    const staged = stageVolumetricFog(state, {
+      generation: 5,
+      digest: 'candidate-digest',
+      selectedLight,
+    });
+    const stale = recoverVolumetricFog(staged, { kind: 'accepted', generation: 4 });
+    expect(stale).toMatchObject({
+      status: 'degraded',
+      generation: 4,
+      selectedLight,
+      candidateFailure: 'stale-generation',
+    });
+  });
+});

package/src/__tests__/volumetric-fog-point-spot-selection.integration.test.ts

@@ -0,0 +1,49 @@
+import { World } from '@forgeax/engine-ecs';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { PointLight, SpotLight } from '../index';
+import { resolveSelectedVolumetricLight } from '../volume/capability';
+
+describe('VolumetricFog Point+Spot selection', () => {
+  it('resolves one PointLight and one SpotLight as one accepted pair', () => {
+    const world = new World();
+    const point = world
+      .spawn(
+        { component: Transform, data: { pos: [0, 1.4, 0] } },
+        { component: PointLight, data: {} },
+      )
+      .unwrap();
+    const spot = world
+      .spawn(
+        { component: Transform, data: { pos: [2.5, 5, 2.5] } },
+        { component: SpotLight, data: { direction: [-2.5, -5, -2.5] } },
+      )
+      .unwrap();
+
+    expect(resolveSelectedVolumetricLight(world, point)).toMatchObject({
+      status: 'available',
+      kind: 'point',
+      entity: point,
+    });
+    expect(resolveSelectedVolumetricLight(world, spot)).toMatchObject({
+      status: 'available',
+      kind: 'spot',
+      entity: spot,
+    });
+  });
+
+  it('does not accept a foreign-world or three-light combination', () => {
+    const world = new World();
+    const foreignWorld = new World();
+    const foreign = foreignWorld
+      .spawn(
+        { component: Transform, data: { pos: [0, 1, 0] } },
+        { component: PointLight, data: {} },
+      )
+      .unwrap();
+    expect(resolveSelectedVolumetricLight(world, foreign)).toMatchObject({
+      status: 'unresolved',
+      reason: 'missing-entity',
+    });
+  });
+});

package/src/__tests__/volumetric-fog-point-spot-temporal.unit.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { resolveVolumeTemporalReset, type VolumeTemporalSignature } from '../volume/temporal';
+
+const projector = {
+  guid: 'projector-guid',
+  generation: 3,
+  view: 'spot-view-7',
+  sampler: 'linear-clamp',
+  projection: 'spot-projection-7',
+  revision: 11,
+} as const;
+
+const signature: VolumeTemporalSignature = {
+  cameraRevision: 4,
+  fogRevision: 2,
+  lightRevision: 7,
+  densityGeneration: 3,
+  width: 1280,
+  height: 720,
+  lightKind: 'point',
+  lightEntity: 19,
+  pointLightEntity: 19,
+  spotLightEntity: 23,
+  projector,
+};
+
+describe('Point+Spot volumetric temporal identity', () => {
+  it('keeps history for the same accepted pair and projector tuple', () => {
+    expect(resolveVolumeTemporalReset(signature, signature)).toEqual({ reset: false });
+  });
+
+  it.each([
+    ['projector GUID', { ...projector, guid: 'new-projector-guid' }],
+    ['projector generation', { ...projector, generation: 4 }],
+    ['projector view', { ...projector, view: 'spot-view-8' }],
+    ['projector sampler', { ...projector, sampler: 'nearest-clamp' }],
+    ['projector projection', { ...projector, projection: 'spot-projection-8' }],
+    ['projector revision', { ...projector, revision: 12 }],
+  ] as const)('resets history when %s changes', (_name, nextProjector) => {
+    expect(
+      resolveVolumeTemporalReset(signature, { ...signature, projector: nextProjector }),
+    ).toEqual({ reset: true, reason: 'light-revision' });
+  });
+
+  it('resets history when either selected pair entity changes', () => {
+    expect(resolveVolumeTemporalReset(signature, { ...signature, spotLightEntity: 24 })).toEqual({
+      reset: true,
+      reason: 'light-revision',
+    });
+    expect(resolveVolumeTemporalReset(signature, { ...signature, pointLightEntity: 20 })).toEqual({
+      reset: true,
+      reason: 'light-revision',
+    });
+  });
+});

package/src/__tests__/volumetric-fog-projector-contract.unit.test.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const spotSource = readFileSync(new URL('../components/spot-light.ts', import.meta.url), 'utf8');
+const errorSource = readFileSync(new URL('../errors/render.ts', import.meta.url), 'utf8');
+
+describe('SpotLight projector contract', () => {
+  it('exposes an optional GUID-backed TextureAsset projector field', () => {
+    expect(spotSource).toMatch(/projector\??:/);
+    expect(spotSource).toMatch(/TextureAsset/);
+    expect(spotSource).not.toContain('whiteTexture');
+    expect(spotSource).not.toContain('cookieRegistry');
+  });
+
+  it('distinguishes absent projector from authored failure', () => {
+    expect(spotSource).toContain('absent');
+    expect(errorSource).toMatch(/projector/);
+    expect(errorSource).toMatch(/expected/);
+    expect(errorSource).toMatch(/hint/);
+    expect(errorSource).toMatch(/detail/);
+  });
+});

package/src/__tests__/volumetric-fog-projector-inspection.unit.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+import { ProjectorBindingError } from '../errors/render';
+
+describe('projector inspection', () => {
+  it('distinguishes absent projector from an authored failure', () => {
+    const absent = { status: 'absent' as const };
+    const failure = new ProjectorBindingError('density-projector', 'invalid');
+    expect(absent.status).toBe('absent');
+    expect(failure.code).toBe('projector-binding-failed');
+    expect(failure.detail.guid).toBe('density-projector');
+  });
+});

package/src/__tests__/volumetric-fog-projector-surface-volume.integration.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest';
+
+describe('surface and volume projector tuple', () => {
+  it('rejects mismatched revision and accepts the same tuple', () => {
+    const surface = { guid: 'g', generation: 2, revision: 7 };
+    const volume = { guid: 'g', generation: 2, revision: 7 };
+    const drifted = { guid: 'g', generation: 2, revision: 8 };
+    expect(volume).toEqual(surface);
+    expect(drifted).not.toEqual(surface);
+  });
+});

package/src/__tests__/volumetric-fog-projector-transaction.integration.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { ProjectorBindingError } from '../errors/render';
+
+describe('projector publication transaction', () => {
+  it('uses one accepted identity for both surface and volume', () => {
+    const identity = { guid: 'projector-guid', generation: 4, revision: 9 };
+    const surface = identity;
+    const volume = identity;
+    expect(surface).toBe(volume);
+    expect(surface).toEqual({ guid: 'projector-guid', generation: 4, revision: 9 });
+  });
+
+  it('keeps pending and bind failure structured', () => {
+    const pending = new ProjectorBindingError('projector-guid', 'pending');
+    const failed = new ProjectorBindingError('projector-guid', 'bind-failed');
+    expect(pending).toMatchObject({
+      code: 'projector-binding-failed',
+      detail: { status: 'pending' },
+    });
+    expect(failed).toMatchObject({
+      expected: expect.any(String),
+      hint: expect.any(String),
+      detail: { status: 'bind-failed' },
+    });
+  });
+});

package/src/__tests__/volumetric-fog-recovery.integration.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import {
+  recoverVolumetricFog,
+  stageVolumetricFog,
+  type VolumeRecoveryState,
+} from '../volume/recovery';
+
+const state: VolumeRecoveryState = {
+  guid: 'density-guid',
+  generation: 4,
+  deviceEpoch: 2,
+  status: 'accepted',
+};
+
+describe('volumetric fog recovery transaction', () => {
+  it('keeps accepted LKG when candidate upload or submit fails', () => {
+    const staged = stageVolumetricFog(state, { generation: 5, digest: 'candidate-digest' });
+    expect(staged).toMatchObject({ status: 'candidate', candidateGeneration: 5 });
+    const failed = recoverVolumetricFog(staged, { kind: 'submit-failed' });
+    expect(failed).toMatchObject({
+      status: 'degraded',
+      generation: 4,
+      lkgGeneration: 4,
+      candidateFailure: 'submit-failed',
+    });
+  });
+
+  it('clears device-bound resources and rebuilds the same GUID after device loss', () => {
+    const lost = recoverVolumetricFog(state, { kind: 'device-lost', deviceEpoch: 3 });
+    expect(lost).toMatchObject({
+      status: 'recovering',
+      guid: 'density-guid',
+      deviceEpoch: 3,
+      generation: 4,
+    });
+    expect(lost).not.toHaveProperty('acceptedGeneration', 5);
+  });
+
+  it('rejects stale generations instead of silently publishing a new LKG', () => {
+    const stale = recoverVolumetricFog(state, { kind: 'accepted', generation: 3 });
+    expect(stale).toMatchObject({
+      status: 'degraded',
+      generation: 4,
+      candidateFailure: 'stale-generation',
+    });
+  });
+});

package/src/__tests__/volumetric-fog-selected-light-resolution.integration.test.ts

@@ -0,0 +1,63 @@
+import { World } from '@forgeax/engine-ecs';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { DirectionalLight, SpotLight } from '../index';
+import { resolveSelectedVolumetricLight } from '../volume/capability';
+
+describe('selected volumetric light resolution', () => {
+  it('selects a real DirectionalLight or SpotLight entity', () => {
+    const world = new World();
+    const directional = world
+      .spawn({ component: DirectionalLight, data: { direction: [0, -1, 0] } })
+      .unwrap();
+    const spot = world
+      .spawn(
+        { component: Transform, data: { pos: [0, 2, 0] } },
+        { component: SpotLight, data: { direction: [0, -1, 0] } },
+      )
+      .unwrap();
+
+    expect(resolveSelectedVolumetricLight(world, directional)).toMatchObject({
+      status: 'available',
+      entity: directional,
+      kind: 'directional',
+    });
+    expect(resolveSelectedVolumetricLight(world, spot)).toMatchObject({
+      status: 'available',
+      entity: spot,
+      kind: 'spot',
+    });
+  });
+
+  it('returns closed reasons for missing, wrong-component, and ambiguous entities', () => {
+    const world = new World();
+    const ordinary = world.spawn().unwrap();
+    const both = world
+      .spawn(
+        { component: Transform, data: { pos: [0, 2, 0] } },
+        { component: DirectionalLight, data: { direction: [0, -1, 0] } },
+        { component: SpotLight, data: { direction: [0, -1, 0] } },
+      )
+      .unwrap();
+    const otherWorld = new World();
+    otherWorld.spawn();
+    otherWorld.spawn();
+    otherWorld.spawn();
+    const foreign = otherWorld
+      .spawn({ component: DirectionalLight, data: { direction: [0, -1, 0] } })
+      .unwrap();
+
+    expect(resolveSelectedVolumetricLight(world, ordinary)).toMatchObject({
+      status: 'unresolved',
+      reason: 'wrong-component',
+    });
+    expect(resolveSelectedVolumetricLight(world, both)).toMatchObject({
+      status: 'unresolved',
+      reason: 'ambiguous',
+    });
+    expect(resolveSelectedVolumetricLight(world, foreign)).toMatchObject({
+      status: 'unresolved',
+      reason: 'missing-entity',
+    });
+  });
+});

package/src/__tests__/volumetric-fog-spot-closure.integration.test.ts

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const main = readFileSync(
+  new URL('../../../../apps/hello/volumetric-fog/src/main.ts', import.meta.url),
+  'utf8',
+);
+const smoke = readFileSync(
+  new URL('../../../../apps/hello/volumetric-fog/scripts/smoke-browser.mjs', import.meta.url),
+  'utf8',
+);
+
+describe('volumetric fog Spot closure', () => {
+  it('uses exactly one real SpotLight as the VolumetricFog source', () => {
+    expect(main).toContain('spawnVolumetricSpot');
+    expect(main).toContain('light: selectedLight');
+    expect(main).not.toContain('component: DirectionalLight');
+  });
+
+  it('keeps browser cases on the real renderer and includes shadow falsifiers', () => {
+    expect(smoke).toContain('diagnostic-ceiling-only');
+    expect(smoke).toContain('diagnostic-ceiling-occluder');
+    expect(smoke).toContain('diagnostic-no-shadow');
+    expect(smoke).toContain('perFramePassNames');
+  });
+});

package/src/__tests__/volumetric-fog-spot-contract.test-d.ts

@@ -0,0 +1,21 @@
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { expectTypeOf } from 'vitest';
+import type { VolumetricFogAuthoring } from '../volume/component';
+
+// M6 requires the selected light to be an entity from the same World.  This
+// intentionally fails against the pre-M6 optional synthetic-light shape.
+expectTypeOf<VolumetricFogAuthoring>().toHaveProperty('light');
+expectTypeOf<VolumetricFogAuthoring['light']>().toEqualTypeOf<EntityHandle>();
+
+type CandidateKind = 'directional' | 'spot';
+const candidate: CandidateKind = 'spot';
+void candidate;
+
+// The old synthetic light API must not be part of the public volume surface.
+type Capability = typeof import('../volume/capability');
+type SyntheticNames = Extract<
+  keyof Capability,
+  'VolumetricFogDirectionalLight' | 'VolumetricFogCsmSnapshot' | 'resolveVolumetricFogLight'
+>;
+const noSyntheticNames: never = null as unknown as SyntheticNames;
+void noSyntheticNames;

package/src/__tests__/volumetric-fog-spot-contract.unit.test.ts

@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const componentSource = readFileSync(new URL('../volume/component.ts', import.meta.url), 'utf8');
+const capabilitySource = readFileSync(new URL('../volume/capability.ts', import.meta.url), 'utf8');
+
+describe('VolumetricFog selected-light contract', () => {
+  it('requires a same-World Entity light and keeps only real light candidates', () => {
+    expect(componentSource).toMatch(/readonly light:\s*EntityHandle/);
+    expect(componentSource).toContain('type EntityHandle');
+    expect(componentSource).toContain('DirectionalLight');
+    expect(componentSource).toContain('SpotLight');
+  });
+
+  it('does not retain the synthetic directional resolver or snapshot exports', () => {
+    expect(capabilitySource).not.toContain('VolumetricFogDirectionalLight');
+    expect(capabilitySource).not.toContain('VolumetricFogCsmSnapshot');
+    expect(capabilitySource).toContain('resolveSelectedVolumetricLight');
+    expect(capabilitySource).toContain('resolveVolumetricFogLightPair');
+    expect(capabilitySource).not.toContain('resolveVolumetricFogLight(');
+  });
+
+  it('documents closed reasons for unresolved light identity', () => {
+    expect(componentSource).toMatch(/same-World|wrong-World|wrong component|light/i);
+    expect(componentSource).toMatch(/same-World|wrong-World|wrong component|light/i);
+  });
+});

package/src/__tests__/volumetric-fog-spot-frame-optics.integration.test.ts

@@ -0,0 +1,14 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const frame = readFileSync(new URL('../record/frame.ts', import.meta.url), 'utf8');
+
+describe('volumetric Spot frame optics', () => {
+  it('passes extracted colorTimesIntensity through once', () => {
+    expect(frame).toMatch(
+      /const lightColor = selectedSpot\?\.color \?\? lights\.directional\?\.color/,
+    );
+    expect(frame).toContain('params.set(lightColor, 24);');
+    expect(frame).not.toContain('channel * selectedSpot.intensity');
+  });
+});