@forgeax/engine-render 0.1.21 → 0.1.24

package/src/__tests__/gpu-lod-schema.unit.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildGpuLodRows,
+  encodeGpuLodRows,
+  GPU_LOD_ROW_LAYOUT,
+  GPU_LOD_ROW_SCHEMA,
+} from '../scene/visibility/gpu-lod';
+
+describe('GPU LOD row schema', () => {
+  it('projects absolute coverage and stable draw-template ranges into rows', () => {
+    const rows = buildGpuLodRows({
+      generation: 7,
+      hysteresis: 0.1,
+      ranges: [
+        { firstIndex: 0, indexCount: 120, baseVertex: 0 },
+        { firstIndex: 120, indexCount: 60, baseVertex: 0 },
+        { firstIndex: 180, indexCount: 24, baseVertex: 0 },
+      ],
+      coverages: [1, 0.5, 0.2],
+      ready: [true, true, false],
+    });
+
+    expect(rows).toHaveLength(3);
+    expect(rows[1]).toMatchObject({
+      generation: 7,
+      level: 1,
+      screenCoverage: 0.5,
+      firstIndex: 120,
+      indexCount: 60,
+      ready: true,
+    });
+    expect(rows[2]?.ready).toBe(false);
+    expect(GPU_LOD_ROW_SCHEMA.fields.map((field) => field.name)).toEqual([
+      'generation',
+      'level',
+      'firstIndex',
+      'indexCount',
+      'baseVertex',
+      'screenCoverage',
+      'hysteresis',
+      'ready',
+    ]);
+    expect(GPU_LOD_ROW_LAYOUT.stride).toBe(32);
+  });
+
+  it('encodes the same bytes for CPU and GPU consumers', () => {
+    const rows = buildGpuLodRows({
+      generation: 3,
+      hysteresis: 0.05,
+      ranges: [
+        { firstIndex: 0, indexCount: 36, baseVertex: -2 },
+        { firstIndex: 36, indexCount: 12, baseVertex: -2 },
+      ],
+      coverages: [1, 0.25],
+      ready: [true, true],
+    });
+    const bytes = encodeGpuLodRows(rows);
+    expect(bytes.byteLength).toBe(GPU_LOD_ROW_LAYOUT.stride * rows.length);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    expect(view.getUint32(0, true)).toBe(3);
+    expect(view.getUint32(4, true)).toBe(0);
+    expect(view.getInt32(16, true)).toBe(-2);
+    expect(view.getFloat32(20, true)).toBe(1);
+    expect(view.getUint32(GPU_LOD_ROW_LAYOUT.stride + 28, true)).toBe(1);
+  });
+});

package/src/__tests__/gpu-lod-selector.unit.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { GPU_DRIVEN_VIEW_WGSL, selectGpuLodLane } from '../gpu-driven/view-gpu';
+
+describe('GPU LOD selector lane', () => {
+  it('contains the same absolute threshold and readiness inputs as the CPU reference', () => {
+    expect(GPU_DRIVEN_VIEW_WGSL).toContain('screenCoverage');
+    expect(GPU_DRIVEN_VIEW_WGSL).toContain('hysteresis');
+    expect(GPU_DRIVEN_VIEW_WGSL).toContain('ready');
+    expect(GPU_DRIVEN_VIEW_WGSL).toContain('selectLodLevel');
+  });
+
+  it('keeps GPU-driven candidates without authored bounds conservatively visible', () => {
+    expect(GPU_DRIVEN_VIEW_WGSL).toContain('if ((primitive.flags & 5u) != 5u) { return false; }');
+    expect(GPU_DRIVEN_VIEW_WGSL).toContain('if ((primitive.flags & 2u) == 0u) { return true; }');
+  });
+
+  it('selects the GPU lane only when all required storage capabilities exist', () => {
+    expect(selectGpuLodLane({ compute: true, storageBuffer: true, indirectDrawing: true })).toBe(
+      'gpu',
+    );
+    expect(selectGpuLodLane({ compute: false, storageBuffer: true, indirectDrawing: true })).toBe(
+      'cpu',
+    );
+    expect(selectGpuLodLane({ compute: true, storageBuffer: false, indirectDrawing: true })).toBe(
+      'cpu',
+    );
+  });
+});

package/src/__tests__/gpu-lod-silhouette.browser.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { runGpuLodSilhouetteEvidence } from './gpu-lod-evidence';
+
+const browserReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+describe.skipIf(!browserReady)('GPU LOD Browser silhouette evidence', () => {
+  it('publishes distinct composite silhouettes with matching identity', () => {
+    const evidence = runGpuLodSilhouetteEvidence();
+    expect(evidence.status).toBe('available');
+    expect(new Set(evidence.levelSignatures).size).toBe(3);
+    expect(evidence.identity.view).toContain('lod-evidence-view');
+  });
+});

package/src/__tests__/gpu-resource-store-stride.unit.test.ts

@@ -18,7 +18,6 @@ describe('GpuResidencyCache mesh stride', () => {
       },
       device.caps,
     );
-
     const mesh: MeshAsset = {
       kind: 'mesh',
       // The producer owns a canonical 20-float interleaved buffer:
@@ -56,4 +55,70 @@ describe('GpuResidencyCache mesh stride', () => {
     expect(entry?.layoutProjection.arrayStride).toBe(80);
     expect(entry?.vertexCount).toBe(4);
   });
+
+  it('packs lower-detail geometry into shared buffers with distinct ranges', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const store = new GpuResidencyCache();
+    store.configureGpuDevice(
+      device,
+      undefined,
+      () => {
+        throw new Error('cubemap registration is not part of this test');
+      },
+      device.caps,
+    );
+    const indexWrites: Uint8Array[] = [];
+    const queue = device.queue;
+    const writeBuffer = queue.writeBuffer.bind(queue);
+    queue.writeBuffer = (buffer, bufferOffset, data, dataOffset, size) => {
+      const bytes =
+        data instanceof ArrayBuffer
+          ? new Uint8Array(data)
+          : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+      if (bytes.byteLength === 12) indexWrites.push(new Uint8Array(bytes));
+      return writeBuffer(buffer, bufferOffset, data, dataOffset, size);
+    };
+    const attributes = {
+      position: new Float32Array(9),
+      normal: new Float32Array(9),
+      uv: new Float32Array(6),
+      tangent: new Float32Array(12),
+    };
+    const submesh = {
+      indexOffset: 0,
+      indexCount: 3,
+      vertexCount: 3,
+      topology: 'triangle-list' as const,
+      materialSlot: 0,
+    };
+    const root: MeshAsset = {
+      kind: 'mesh',
+      vertices: new Float32Array(36),
+      indices: new Uint16Array([0, 1, 2]),
+      attributes,
+      submeshes: [submesh],
+      materialSlots: [{ slotName: 'default' }],
+    };
+    const lower: MeshAsset = {
+      ...root,
+      vertices: new Float32Array(36).fill(2),
+      indices: new Uint16Array([0, 2, 1]),
+    };
+    const world = new World();
+    const handle = world.allocSharedRef('MeshAsset', root);
+    const resident = store.ensureResident(handle, root, 0, [lower]);
+    expect(resident.ok).toBe(true);
+    if (!resident.ok) return;
+    expect(resident.value.vboBytes).toBe(root.vertices.byteLength + lower.vertices.byteLength);
+    expect(resident.value.iboBytes).toBe(12);
+    expect(resident.value.lodRanges).toEqual([
+      [{ first: 0, count: 3, baseVertex: 0 }],
+      [{ first: 3, count: 3, baseVertex: 3 }],
+    ]);
+    const packedIndices = indexWrites.at(-1);
+    expect(packedIndices).toBeDefined();
+    if (packedIndices === undefined) return;
+    expect(new Uint16Array(packedIndices.buffer)).toEqual(new Uint16Array([0, 1, 2, 0, 2, 1]));
+  });
 });

package/src/__tests__/gpu-scene.dawn.test.ts

@@ -146,9 +146,16 @@ describe('GpuScene Dawn residency', () => {
         true,
       ),
     ).toBe(0);
+    const firstTransformIndex = views.primitive.getUint32(
+      gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.primitive, 'transformIndex'),
+      true,
+    );
+    expect(firstTransformIndex).toBe(1);
     expect(
       views.transform.getFloat32(
-        gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.transform, 'currentWorld') + 12 * 4,
+        firstTransformIndex * GPU_SCENE_LAYOUTS.transform.stride +
+          gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.transform, 'currentWorld') +
+          12 * 4,
         true,
       ),
     ).toBe(3);

package/src/__tests__/gpu-scene.unit.test.ts

@@ -88,7 +88,7 @@ describe('GpuScene', () => {
       { kind: 'create', snapshot: snapshot(1) },
       { kind: 'create', snapshot: snapshot(2) },
     ]);
-    expect(created.scene.sync(initial).unwrap()).toMatchObject({ ranges: 5, bytes: 1344 });
+    expect(created.scene.sync(initial).unwrap()).toMatchObject({ ranges: 5, bytes: 1088 });
     const writesAfterInitial = queue.writes.length;
 
     created.scene.sync(projection.apply([])).unwrap();
@@ -98,11 +98,57 @@ describe('GpuScene', () => {
       { kind: 'update-transform', worldId: 0, entityKey: 0, world: snapshot(0, 4).transform.world },
       { kind: 'update-transform', worldId: 0, entityKey: 2, world: snapshot(2, 8).transform.world },
     ]);
-    expect(created.scene.sync(dirty).unwrap()).toMatchObject({ ranges: 10 });
+    expect(created.scene.sync(dirty).unwrap()).toMatchObject({
+      ranges: 2,
+      bytes: 2 * GPU_SCENE_LAYOUTS.transform.stride,
+    });
     expect(queue.writes.length).toBeGreaterThan(writesAfterInitial);
     expect(created.scene.inspect()).toMatchObject({ noChangeFrames: 1 });
   });
 
+  it('skips previous-transform upload when temporal demand is absent', () => {
+    const queue = new RecordingQueue();
+    const created = GpuScene.create(createDevice(queue), 1).unwrap();
+    if (created.status !== 'available') return;
+    const projection = new RenderScene();
+    created.scene.sync(projection.apply([{ kind: 'create', snapshot: snapshot(0, 2) }])).unwrap();
+
+    const writesBefore = queue.writes.length;
+    const bytesBefore = created.scene.inspect().uploadBytes;
+    created.scene.commitTemporalFrame(false).unwrap();
+    expect(queue.writes).toHaveLength(writesBefore);
+    expect(created.scene.inspect().uploadBytes).toBe(bytesBefore);
+
+    created.scene.commitTemporalFrame(true).unwrap();
+    expect(queue.writes).toHaveLength(writesBefore + 1);
+    expect(created.scene.inspect().uploadBytes).toBe(
+      bytesBefore + created.scene.inspect().tables.transform.bytes,
+    );
+  });
+
+  it('preserves the prior root transform on transform-only updates', () => {
+    const queue = new RecordingQueue();
+    const created = GpuScene.create(createDevice(queue), 1).unwrap();
+    if (created.status !== 'available') return;
+    const projection = new RenderScene();
+    created.scene.sync(projection.apply([{ kind: 'create', snapshot: snapshot(0, 2) }])).unwrap();
+
+    const dirty = projection.apply([
+      { kind: 'update-transform', worldId: 0, entityKey: 0, world: snapshot(0, 9).transform.world },
+    ]);
+    created.scene.sync(dirty).unwrap();
+
+    const transformWrite = queue.writes.at(-1);
+    expect(transformWrite).toBeDefined();
+    if (transformWrite === undefined) return;
+    const transform = GPU_SCENE_LAYOUTS.transform;
+    const currentTranslation = gpuSceneFieldOffset(transform, 'currentWorld') + 12 * 4;
+    const previousTranslation = gpuSceneFieldOffset(transform, 'previousWorld') + 12 * 4;
+    const bytes = transformWrite.bytes;
+    expect(new DataView(bytes.buffer).getFloat32(currentTranslation, true)).toBe(9);
+    expect(new DataView(bytes.buffer).getFloat32(previousTranslation, true)).toBe(2);
+  });
+
   it('clears removed slots, grows without losing the CPU mirror, and rebuilds a fresh table', () => {
     const queue = new RecordingQueue();
     const created = GpuScene.create(createDevice(queue), 2).unwrap();
@@ -117,7 +163,7 @@ describe('GpuScene', () => {
         ]),
       )
       .unwrap();
-    expect(created.scene.inspect()).toMatchObject({ capacity: 8, capacityGrows: 1 });
+    expect(created.scene.inspect()).toMatchObject({ capacity: 4, capacityGrows: 1 });
 
     const beforeRemove = queue.writes.length;
     created.scene.sync(projection.apply([{ kind: 'remove', worldId: 0, entityKey: 1 }])).unwrap();

package/src/__tests__/ibl/face-uniforms.unit.test.ts

@@ -38,9 +38,11 @@ describe('IBL face uniform RHI contract', () => {
     const badFace = writeFaceUniforms(device, bufferResult.value, 6, new Float32Array(16));
     const badMatrix = writeFaceUniforms(device, bufferResult.value, 0, new Float32Array(15));
     const badSubPass = writePrefilterUniforms(device, bufferResult.value, 30, 0.5, 128);
+    const badMipCount = writePrefilterUniforms(device, bufferResult.value, 0, 0.5, 128, 0);
 
     expect(badFace).toMatchObject({ ok: false, error: { code: 'webgpu-runtime-error' } });
     expect(badMatrix).toMatchObject({ ok: false, error: { code: 'webgpu-runtime-error' } });
     expect(badSubPass).toMatchObject({ ok: false, error: { code: 'webgpu-runtime-error' } });
+    expect(badMipCount).toMatchObject({ ok: false, error: { code: 'webgpu-runtime-error' } });
   });
 });

package/src/__tests__/ibl-residency-publication.unit.test.ts

@@ -0,0 +1,113 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const source = readFileSync(new URL('../device/gpu-residency.ts', import.meta.url), 'utf8');
+const iblSource = readFileSync(new URL('../ibl/IblPipelineCache.ts', import.meta.url), 'utf8');
+
+describe('IBL residency publication', () => {
+  it('publishes ready and the idempotent cube only after submission succeeds', () => {
+    const precomputeCall = source.indexOf('const runResult = await runIblPrecompute({');
+    const precomputeSuccess = source.indexOf('if (!runResult.ok)', precomputeCall);
+    const sourceReady = source.indexOf("status: 'ready'", precomputeCall);
+    const cubeRegistration = source.indexOf('const cubeHandle = regResult.value;', precomputeCall);
+    const mapPublication = source.indexOf(
+      'this.cubemapIdempotentMap.set(sourceId, cubeHandle);',
+      precomputeCall,
+    );
+    expect(precomputeCall).toBeGreaterThan(-1);
+    expect(precomputeSuccess).toBeGreaterThan(precomputeCall);
+    expect(sourceReady).toBeGreaterThan(precomputeSuccess);
+    expect(cubeRegistration).toBeGreaterThan(precomputeSuccess);
+    expect(mapPublication).toBeGreaterThan(precomputeSuccess);
+  });
+
+  it('keeps pending publication before asynchronous pipeline work', () => {
+    const pending = source.indexOf("status: 'pending'");
+    const precompute = source.indexOf('const runResult = await runIblPrecompute({');
+    expect(pending).toBeGreaterThan(-1);
+    expect(pending).toBeLessThan(precompute);
+  });
+
+  it('promotes the IBL candidate only after the completion fence', () => {
+    const runStart = iblSource.indexOf('export async function runIblPrecompute(');
+    const fence = iblSource.indexOf('await device.queue.onSubmittedWorkDone()', runStart);
+    const promotion = iblSource.indexOf(
+      'cache.irradianceTexture = promoted.irradianceTexture',
+      runStart,
+    );
+    const ready = source.indexOf("status: 'ready'", source.indexOf('_uploadCubemapFromEquirect'));
+    expect(runStart).toBeGreaterThan(-1);
+    expect(fence).toBeGreaterThan(runStart);
+    expect(promotion).toBeGreaterThan(fence);
+    expect(ready).toBeGreaterThan(fence);
+    expect(iblSource.slice(runStart, fence)).not.toContain('cache.irradianceTexture =');
+    expect(iblSource.slice(runStart, fence)).not.toContain('cache.prefilterTexture =');
+    expect(iblSource.slice(runStart, fence)).not.toContain('cache.brdfLutTexture =');
+  });
+
+  it('awaits precompute before residency publication', () => {
+    const call = source.indexOf('const runResult = await runIblPrecompute({');
+    const success = source.indexOf('if (!runResult.ok)', call);
+    const ready = source.indexOf("status: 'ready'", call);
+    const map = source.indexOf('this.cubemapIdempotentMap.set(sourceId, cubeHandle);', call);
+    expect(call).toBeGreaterThan(-1);
+    expect(success).toBeGreaterThan(call);
+    expect(ready).toBeGreaterThan(success);
+    expect(map).toBeGreaterThan(success);
+  });
+
+  it('keeps candidate and transient resources under the DeviceScope owner', () => {
+    expect(iblSource).toContain("scope._adopt('texture', texture");
+    expect(source).toContain("scope._adopt('texture', equirectGpuTex");
+    expect(source).toContain("scope._adopt('buffer', faceBuf");
+    expect(source).toContain("scope._adopt('buffer', prefBuf");
+    expect(source).toContain("scope._adopt('buffer', cubeVertex");
+    const fence = iblSource.indexOf('await device.queue.onSubmittedWorkDone()');
+    const candidateWrites = iblSource.indexOf('candidate.irradianceTexture = adoptIblTexture');
+    expect(candidateWrites).toBeLessThan(fence);
+  });
+
+  it('fences each IBL stage before recording the next stage', () => {
+    const runStart = iblSource.indexOf('export async function runIblPrecompute(');
+    const stages = ['equirect-to-cube', 'prefilter', 'brdf-lut'];
+    let previous = runStart;
+    for (const stage of stages) {
+      const marker = iblSource.indexOf(`await submitStage('${stage}'`, previous);
+      expect(marker).toBeGreaterThan(previous);
+      previous = marker;
+    }
+    expect(iblSource.match(/await submitStage\('/g)).toHaveLength(stages.length);
+    expect(iblSource).toContain('await device.queue.onSubmittedWorkDone()');
+    expect(
+      iblSource.indexOf('cache.irradianceTexture = promoted.irradianceTexture'),
+    ).toBeGreaterThan(previous);
+  });
+
+  it('does not promote or increment counters after a failed stage', () => {
+    const runStart = iblSource.indexOf('export async function runIblPrecompute(');
+    const promotion = iblSource.indexOf(
+      'cache.irradianceTexture = promoted.irradianceTexture',
+      runStart,
+    );
+    const counters = iblSource.indexOf('cache.irradianceBakeCount += 1', runStart);
+    const stageFailure = iblSource.indexOf('return err(badAlloc', runStart);
+    expect(stageFailure).toBeGreaterThan(runStart);
+    expect(stageFailure).toBeLessThan(promotion);
+    expect(promotion).toBeLessThan(counters);
+    expect(iblSource).toContain('stage}-device-scope-generation');
+  });
+
+  it('fences each irradiance face before the next face', () => {
+    const runStart = iblSource.indexOf('export async function runIblPrecompute(');
+    const irradianceStart = iblSource.indexOf('// (b) irradiance convolve', runStart);
+    const prefilterStart = iblSource.indexOf('// (c) prefilter env', irradianceStart);
+    const faceMarkers = iblSource.match(/submitStage\(`irradiance-face-\$\{face\}`/g) ?? [];
+    expect(faceMarkers).toHaveLength(1);
+    expect(iblSource.slice(irradianceStart, prefilterStart)).toMatch(
+      /await submitStage\(`irradiance-face-\$\{face\}`, true\)/,
+    );
+    expect(iblSource.slice(irradianceStart, prefilterStart)).not.toContain(
+      "await submitStage('irradiance', true)",
+    );
+  });
+});

package/src/__tests__/light-buffer-layout.unit.test.ts

@@ -1,6 +1,13 @@
 import type { Vec3 } from '@forgeax/engine-math';
 import { describe, expect, it } from 'vitest';
-import { packSpotLight } from '../light-buffer-layout';
+import {
+  DIRECT_LIGHT_SLOT_LAYOUT,
+  DIRECT_LIGHT_SLOT_METADATA_SENTINEL,
+  DIRECT_LIGHT_SLOT_PROJECTOR_FLAG,
+  DIRECT_LIGHT_SLOT_TILE_MASK,
+  DirectLightSlotKind,
+  packDirectLightSlot,
+} from '../light-buffer-layout';
 import type { SpotLightSnapshot } from '../render-system-extract';
 
 const snapshot: SpotLightSnapshot = {
@@ -12,6 +19,7 @@ const snapshot: SpotLightSnapshot = {
   invRangeSquared: 0.25,
   cosInner: 0.98,
   cosOuter: 0.7,
+  rollDeg: 17,
   castShadow: false,
   lightViewProj: undefined,
   mapSize: 2048,
@@ -20,21 +28,123 @@ const snapshot: SpotLightSnapshot = {
   shadowAtlasTile: -1,
 };
 
+const point = {
+  kind: 'point',
+  position: [1, 2, 3],
+  color: [4, 5, 6],
+  invRangeSquared: 0.25,
+  shadowAtlasLayer: -1,
+  iesProfileSlice: undefined,
+  cookieSlice: undefined,
+};
+
+const spot = {
+  kind: 'spot',
+  position: [7, 8, 9],
+  color: [10, 11, 12],
+  invRangeSquared: 0.125,
+  direction: [0, -1, 0],
+  cosInner: 0.9,
+  cosOuter: 0.6,
+  shadowAtlasTile: 3,
+  iesProfileSlice: 5,
+  cookieSlice: 7,
+};
+
+const rect = {
+  kind: 'rect-area',
+  position: [-1, -2, -3],
+  color: [0.25, 0.5, 0.75],
+  invRangeSquared: 0.01,
+  halfWidth: 2,
+  halfHeight: 3,
+  axisX: [1, 0, 0],
+  axisY: [0, 1, 0],
+  shadowAtlasTile: -1,
+  iesProfileSlice: undefined,
+  cookieSlice: undefined,
+};
+
 describe('direct light snapshot buffer layout', () => {
   it('packs the normalized snapshot without changing its public semantics', () => {
-    const packed = packSpotLight(snapshot);
+    const packed = packDirectLightSlot(snapshot);
 
     expect([...packed.slice(0, 7)]).toEqual([2, 3, 4, 0.25, 4, 2, 1]);
     expect(packed[7]).toBeCloseTo(0.98, 5);
     expect([...packed.slice(8, 11)]).toEqual([0, 1, 0]);
     expect(packed[11]).toBeCloseTo(0.7, 5);
+    expect(packed[15]).toBe(17);
   });
 
   it('does not introduce a pipeline-specific intensity multiplier', () => {
-    const packed = packSpotLight(snapshot);
+    const packed = packDirectLightSlot(snapshot);
 
     expect(packed[4]).toBe(snapshot.color[0]);
     expect(packed[5]).toBe(snapshot.color[1]);
     expect(packed[6]).toBe(snapshot.color[2]);
   });
 });
+
+describe('DirectLightSlot ABI', () => {
+  it('locks the five-row 80-byte host contract and closed kind values', () => {
+    expect(DIRECT_LIGHT_SLOT_LAYOUT.byteSize).toBe(80);
+    expect(DIRECT_LIGHT_SLOT_LAYOUT.rowByteOffsets).toEqual([0, 16, 32, 48, 64]);
+    expect(DIRECT_LIGHT_SLOT_LAYOUT.metadataByteOffset).toBe(64);
+    expect(DIRECT_LIGHT_SLOT_LAYOUT.kindByteOffset).toBe(64);
+    expect(DIRECT_LIGHT_SLOT_LAYOUT.shadowByteOffset).toBe(68);
+    expect(DIRECT_LIGHT_SLOT_LAYOUT.iesProfileByteOffset).toBe(72);
+    expect(DIRECT_LIGHT_SLOT_LAYOUT.cookieByteOffset).toBe(76);
+    expect(DIRECT_LIGHT_SLOT_LAYOUT.rollDegByteOffset).toBe(60);
+    expect(DIRECT_LIGHT_SLOT_METADATA_SENTINEL).toBe(0xffffffff);
+    expect(DirectLightSlotKind).toEqual({ POINT: 0, SPOT: 1, RECT_AREA: 2 });
+  });
+
+  it('packs Point, Spot, and Rect fields into the same five rows', () => {
+    const packedPoint = packDirectLightSlot(point as never);
+    const packedSpot = packDirectLightSlot(spot as never);
+    const packedRect = packDirectLightSlot(rect as never);
+
+    for (const packed of [packedPoint, packedSpot, packedRect]) {
+      expect(packed).toBeInstanceOf(Float32Array);
+      expect(packed.byteLength).toBe(80);
+    }
+
+    expect([...packedPoint.slice(0, 4)]).toEqual([1, 2, 3, 0.25]);
+    expect([...packedSpot.slice(4, 7)]).toEqual([10, 11, 12]);
+    expect([...packedSpot.slice(8, 11)]).toEqual([0, -1, 0]);
+    expect([...packedRect.slice(8, 16)]).toEqual([0, 1, 0, 3, 1, 0, 0, 0]);
+  });
+
+  it('uses 0xffffffff for absent shadow and modifier identities', () => {
+    const pointWords = new Uint32Array(packDirectLightSlot(point as never).buffer);
+    const rectWords = new Uint32Array(packDirectLightSlot(rect as never).buffer);
+
+    expect(pointWords[16]).toBe(DirectLightSlotKind.POINT);
+    expect(pointWords[17]).toBe(DIRECT_LIGHT_SLOT_METADATA_SENTINEL);
+    expect(pointWords[18]).toBe(DIRECT_LIGHT_SLOT_METADATA_SENTINEL);
+    expect(pointWords[19]).toBe(DIRECT_LIGHT_SLOT_METADATA_SENTINEL);
+    expect(rectWords[16]).toBe(DirectLightSlotKind.RECT_AREA);
+    expect(rectWords[17]).toBe(DIRECT_LIGHT_SLOT_METADATA_SENTINEL);
+    expect(rectWords[18]).toBe(DIRECT_LIGHT_SLOT_METADATA_SENTINEL);
+    expect(rectWords[19]).toBe(DIRECT_LIGHT_SLOT_METADATA_SENTINEL);
+  });
+
+  it('marks only the selected projector without changing the slot ABI', () => {
+    const projector = {
+      ...snapshot,
+      projectorAsset: {} as never,
+      lightViewProj: new Float32Array(16),
+      projectorSlice: 3,
+    };
+    const selected = new Uint32Array(packDirectLightSlot(projector as never, true).buffer);
+    const notSelected = new Uint32Array(packDirectLightSlot(projector as never, false).buffer);
+
+    const selectedShadowMetadata = selected[17];
+    expect(selectedShadowMetadata).toBe(DIRECT_LIGHT_SLOT_PROJECTOR_FLAG | 0);
+    if (selectedShadowMetadata === undefined) return;
+    expect(selectedShadowMetadata & DIRECT_LIGHT_SLOT_TILE_MASK).toBe(0);
+    expect(selected[19]).toBe(3);
+    expect(notSelected[17]).toBe(DIRECT_LIGHT_SLOT_METADATA_SENTINEL);
+    expect(notSelected[19]).toBe(DIRECT_LIGHT_SLOT_METADATA_SENTINEL);
+  });
+});

package/src/__tests__/light-inspection.unit.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { createLightResourceUnavailable } from '../errors/render';
+import { projectLightInspection } from '../inspection-types';
+import {
+  createExtendedLightingState,
+  projectExtendedLightingInspection,
+  recordExtendedLightingFailure,
+} from '../prepare/extended-lighting/state';
+
+describe('light inspection projection', () => {
+  it('returns readonly POD state and generation-deduped failures', () => {
+    const inspection = projectLightInspection({
+      generation: 5,
+      candidate: 'loading',
+      accepted: 'ready',
+      lastKnownGood: 'ready',
+      failure: undefined,
+      failureKeys: ['cookie:5'],
+      resourceCount: 3,
+      uploadBytes: 128,
+    });
+    expect(inspection).toEqual({
+      generation: 5,
+      candidate: 'loading',
+      accepted: 'ready',
+      lastKnownGood: 'ready',
+      failure: undefined,
+      failureKeys: ['cookie:5'],
+      resourceCount: 3,
+      uploadBytes: 128,
+    });
+    expect(Object.isFrozen(inspection)).toBe(true);
+  });
+
+  it('deduplicates one structured failure per entity, feature, and generation', () => {
+    const state = createExtendedLightingState(5);
+    const failure = createLightResourceUnavailable({
+      entity: 7,
+      feature: 'cookie',
+      generation: 5,
+      sourceKey: 'cookie-four-quadrants',
+      reason: 'format',
+      expected: 'rgba8unorm',
+      actual: 'rgba16float',
+      hint: 'repair the source and retry the same GUID',
+    });
+
+    const recorded = recordExtendedLightingFailure(state, failure);
+    expect(recordExtendedLightingFailure(recorded, failure)).toBe(recorded);
+    expect(projectExtendedLightingInspection(recorded)).toMatchObject({
+      failure: 'light-resource-unavailable',
+      failureKeys: ['7:cookie:5'],
+    });
+  });
+});

package/src/__tests__/light-resource-error.unit.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createLightResourceUnavailable,
+  type LightResourceFailureReason,
+  LightResourceUnavailableError,
+} from '../errors/render';
+
+describe('light resource unavailable error', () => {
+  it('keeps a closed, property-addressable detail', () => {
+    const reasons: LightResourceFailureReason[] = ['asset', 'format', 'capability', 'capacity'];
+    for (const reason of reasons) {
+      const error = createLightResourceUnavailable({
+        entity: 7,
+        feature: 'cookie',
+        generation: 4,
+        sourceKey: 'cookie-four-quadrants',
+        reason,
+        expected: 'accepted uploaded resource',
+        actual: 'missing',
+        hint: 'retry the same GUID after producer recovery',
+      });
+      expect(error).toBeInstanceOf(LightResourceUnavailableError);
+      expect(error.code).toBe('light-resource-unavailable');
+      expect(error.detail.reason).toBe(reason);
+      expect(error.hint).toContain('retry');
+    }
+  });
+
+  it('does not make recovery consumers parse the message', () => {
+    const error = createLightResourceUnavailable({
+      entity: 1,
+      feature: 'ies',
+      generation: 2,
+      sourceKey: 'ies-asymmetric',
+      reason: 'capacity',
+      expected: 'slice <= 32',
+      actual: '33',
+      hint: 'repair capacity and retry the same GUID',
+    });
+    expect(error.detail.sourceKey).toBe('ies-asymmetric');
+    expect(error.detail.generation).toBe(2);
+  });
+});