@forgeax/engine-render 0.1.20 → 0.1.23

package/src/__tests__/gpu-pass-timing.rhi-null.unit.test.ts

@@ -0,0 +1,125 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiCommandEncoder } from '@forgeax/engine-rhi';
+import { type RhiNullDevice, rhi } from '@forgeax/engine-rhi-null';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createGpuPassTimingSession } from '../record/gpu-pass-timing/session.js';
+import type { FrameReceipt } from '../render-contract.js';
+import { createGpuPassTimingObservationStore } from '../renderer.js';
+
+async function createNullDevice(): Promise<RhiNullDevice> {
+  const adapter = (await rhi.requestAdapter()).unwrap();
+  return (await adapter.requestDevice()).unwrap() as RhiNullDevice;
+}
+
+function receipt(frameId: number): FrameReceipt {
+  return {
+    frameId,
+    deviceGeneration: 1,
+    completed: Promise.resolve(ok(undefined)),
+  } as FrameReceipt;
+}
+
+describe('GPU pass timing RhiNull refusal and exact-zero evidence', () => {
+  it('keeps the real RhiNull draw path free of timing resources and commands', async () => {
+    const device = await createNullDevice();
+    const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+    const output = graph
+      .createTexture('output', { format: 'rgba8unorm', size: { width: 1, height: 1 } })
+      .unwrap();
+    const outputView = graph.view(output).unwrap();
+    graph
+      .addRasterPass('scene', {
+        accesses: [{ resource: outputView, usage: 'color-attachment' }],
+        colorAttachments: [{ view: outputView, loadOp: 'clear', storeOp: 'store' }],
+        encode: ({ pass }) => pass.draw(3, 1, 0, 0),
+      })
+      .unwrap();
+
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+    const querySetsBefore = device.bookkeeper
+      .allRecords()
+      .filter((record) => record.kind === 'QuerySet');
+    const encoder = device.createCommandEncoder({ label: 'rhi-null-off' }).unwrap();
+    expect(compiled.execute({ encoder }).ok).toBe(true);
+    const commandBuffer = encoder.finish().unwrap();
+    expect(device.queue.submit([commandBuffer]).ok).toBe(true);
+
+    expect(device.totalDrawCount).toBe(1);
+    expect(device.framePassNames).toEqual(['scene']);
+    expect(
+      device.bookkeeper.allRecords().filter((record) => record.kind === 'QuerySet'),
+    ).toHaveLength(querySetsBefore.length);
+    expect(
+      device.bookkeeper.allRecords().filter((record) => record.kind === 'Buffer'),
+    ).toHaveLength(0);
+    expect((await compiled.retire()).ok).toBe(true);
+  });
+
+  it('refuses opt-in before allocation and keeps repeated recovery attempts side-effect free', async () => {
+    const device = await createNullDevice();
+    const before = device.bookkeeper.recordCount();
+    const first = createGpuPassTimingSession(device, { retentionFrames: 8 });
+    const second = createGpuPassTimingSession(device, { retentionFrames: 8 });
+
+    expect(first).toMatchObject({
+      ok: false,
+      error: { code: 'timestamp-period-unavailable' },
+    });
+    expect(second).toMatchObject({
+      ok: false,
+      error: { code: 'timestamp-period-unavailable' },
+    });
+    expect(device.bookkeeper.recordCount()).toBe(before);
+    expect(device.bookkeeper.allRecords().some((record) => record.kind === 'QuerySet')).toBe(false);
+  });
+
+  it('reports unavailable observations without tick or duration fields', async () => {
+    const store = createGpuPassTimingObservationStore({
+      retentionFrames: 8,
+      currentDeviceGeneration: () => 1,
+    });
+    const current = receipt(1);
+    store.register(current, async () => ({
+      status: 'unavailable',
+      reason: {
+        code: 'timestamp-query-unsupported',
+        expected: 'the active device exposes timestamp-query',
+        hint: 'use a backend that supports timestamp-query',
+        detail: {},
+      },
+      capability: { timestampQuery: false, timestampPeriodNanoseconds: null },
+    }));
+
+    const observed = await store.observe(current, { include: ['timings'] });
+    expect(observed.ok).toBe(true);
+    if (!observed.ok) return;
+    expect(observed.value.timings).toMatchObject({
+      status: 'unavailable',
+      reason: { code: 'timestamp-query-unsupported' },
+    });
+    expect(observed.value.timings).not.toHaveProperty('tick');
+    expect(observed.value.timings).not.toHaveProperty('durationNanoseconds');
+    expect(JSON.stringify(observed.value)).not.toContain('durationNanoseconds');
+  });
+
+  it('marks a RhiNull artifact as refused rather than manufacturing GPU evidence', async () => {
+    const validatorModulePath = '../../bench/gpu-pass-timing/validator.js';
+    const { validateGpuPassTimingReport } = await import(validatorModulePath);
+    const refused = validateGpuPassTimingReport({
+      schemaVersion: '1.0',
+      benchmark: 'render-gpu-pass-timing',
+      source: { sourceHead: '0'.repeat(40), package: '@forgeax/engine-render' },
+      runner: { name: 'rhi-null-test', version: '1', os: 'test', browser: null },
+      backend: {
+        kind: 'null',
+        adapter: 'RhiNull',
+        driver: 'none',
+        browser: 'none',
+        realGpu: false,
+      },
+    });
+
+    expect(refused).toMatchObject({ ok: false, error: { code: 'artifact-not-real-gpu' } });
+  });
+});

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__/hdrp-group2-visibility.unit.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { GPU_SHADER_STAGE_FRAGMENT, GPU_SHADER_STAGE_VERTEX } from '../gpu-stage';
+import {
+  createHdrpBindGroupLayoutDescriptor,
+  createHdrpSkinBindGroupLayoutDescriptor,
+} from '../pbr-pipeline';
+
+describe('HDRP group(2) mesh visibility contract', () => {
+  it('exposes the mesh window to both vertex and fragment stages', () => {
+    const descriptor = createHdrpBindGroupLayoutDescriptor();
+    const mesh = descriptor.entries?.find((entry) => entry.binding === 0);
+    expect(mesh?.visibility).toBe(GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT);
+  });
+
+  it('keeps skin palettes vertex-only while sharing mesh visibility', () => {
+    const descriptor = createHdrpSkinBindGroupLayoutDescriptor();
+    const mesh = descriptor.entries?.find((entry) => entry.binding === 0);
+    const currentPalette = descriptor.entries?.find((entry) => entry.binding === 1);
+    const previousPalette = descriptor.entries?.find((entry) => entry.binding === 2);
+    expect(mesh?.visibility).toBe(GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT);
+    expect(currentPalette?.visibility).toBe(GPU_SHADER_STAGE_VERTEX);
+    expect(previousPalette?.visibility).toBe(GPU_SHADER_STAGE_VERTEX);
+  });
+});

package/src/__tests__/instances-culling.integration.test.ts

@@ -0,0 +1,94 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { Camera } from '../components/camera';
+import { Instances } from '../components/instances';
+import { MeshFilter } from '../components/mesh-filter';
+import { MeshRenderer } from '../components/mesh-renderer';
+import { GPU_DRIVEN_VIEW_WGSL } from '../gpu-driven/view-gpu';
+import { extractFrames } from '../render-system-extract';
+
+const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+
+function translated(x: number): Float32Array {
+  const matrix = new Float32Array(IDENTITY);
+  matrix[12] = x;
+  return matrix;
+}
+
+function spawnCamera(world: World): void {
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 5] } },
+      { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+    )
+    .unwrap();
+}
+
+function spawnInstancedCube(world: World, entityX: number, instanceX: number) {
+  return world
+    .spawn(
+      { component: Transform, data: { pos: [entityX, 0, 0] } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: {} },
+      { component: Instances, data: { transforms: translated(instanceX) } },
+    )
+    .unwrap();
+}
+
+describe('Instances CPU/GPU culling ownership', () => {
+  it('keeps an instance visible when the entity origin is outside the camera frustum', () => {
+    const world = new World();
+    registerPropagateTransforms(world);
+    spawnCamera(world);
+    const entity = spawnInstancedCube(world, 20, -20);
+    world.update(0).unwrap();
+
+    const frame = extractFrames([world], 0);
+
+    expect(frame.renderables.map((renderable) => renderable.entityKey)).toContain(entity);
+    expect(frame.frustumStats).toEqual({ culled: 0, total: 1 });
+  });
+
+  it('recomputes the union after entity and instance transforms change', () => {
+    const world = new World();
+    registerPropagateTransforms(world);
+    spawnCamera(world);
+    const entity = spawnInstancedCube(world, 20, -20);
+    world.update(0).unwrap();
+    expect(extractFrames([world], 0).renderables).toHaveLength(1);
+
+    world.set(entity, Transform, { pos: [40, 0, 0] }).unwrap();
+    world.set(entity, Instances, { transforms: translated(-40) }).unwrap();
+    world.update(0).unwrap();
+
+    const frame = extractFrames([world], 0);
+    expect(frame.renderables).toHaveLength(1);
+    expect(frame.renderables[0]?.instances?.instanceCount).toBe(1);
+  });
+
+  it('does not make an empty instance array visible or feed it to the GPU as one identity instance', () => {
+    const world = new World();
+    registerPropagateTransforms(world);
+    spawnCamera(world);
+    const entity = world
+      .spawn(
+        { component: Transform, data: { pos: [20, 0, 0] } },
+        { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+        { component: MeshRenderer, data: {} },
+        { component: Instances, data: { transforms: new Float32Array() } },
+      )
+      .unwrap();
+    world.update(0).unwrap();
+
+    const frame = extractFrames([world], 0);
+    expect(
+      frame.renderables.find((renderable) => renderable.entityKey === entity)?.instances,
+    ).toMatchObject({ instanceCount: 0 });
+    expect(GPU_DRIVEN_VIEW_WGSL).toContain('candidate.instanceOrdinal');
+    expect(GPU_DRIVEN_VIEW_WGSL).toContain(
+      'currentWorld * transforms[instance.transformIndex].currentWorld',
+    );
+  });
+});

package/src/__tests__/instances-derived-bounds.unit.test.ts

@@ -0,0 +1,118 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { deriveInstancesUnionBounds, InstanceBoundsCache } from '../instances-derived-bounds';
+
+const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+
+function translated(x: number, y = 0, z = 0): Float32Array {
+  const matrix = new Float32Array(IDENTITY);
+  matrix[12] = x;
+  matrix[13] = y;
+  matrix[14] = z;
+  return matrix;
+}
+
+const meshAabb = new Float32Array([-1, -1, -1, 1, 1, 1]);
+const entityWorld = new Float32Array(IDENTITY);
+
+describe('Instances renderer-derived union bounds', () => {
+  it('unions every transformed mesh corner in entity world space', () => {
+    expect(
+      deriveInstancesUnionBounds({
+        meshAabb,
+        entityWorld,
+        transforms: new Float32Array([...IDENTITY, ...translated(5, 2, -3)]),
+      }),
+    ).toEqual(new Float32Array([-1, -1, -4, 6, 3, 1]));
+  });
+
+  it('does not manufacture a visible bound for empty or malformed input', () => {
+    expect(
+      deriveInstancesUnionBounds({ meshAabb, entityWorld, transforms: new Float32Array() }),
+    ).toBeUndefined();
+    expect(
+      deriveInstancesUnionBounds({
+        meshAabb,
+        entityWorld,
+        transforms: new Float32Array([...IDENTITY, 1, 2]),
+      }),
+    ).toBeUndefined();
+    expect(
+      deriveInstancesUnionBounds({
+        meshAabb,
+        entityWorld,
+        transforms: new Float32Array([...IDENTITY.slice(0, 15), Number.NaN]),
+      }),
+    ).toBeUndefined();
+  });
+
+  it('invalidates one cached projection when mesh, entity, or matrix generation changes', () => {
+    const cache = new InstanceBoundsCache();
+    const input = {
+      entityKey: 7,
+      meshGeneration: 1,
+      transformGeneration: 1,
+      matrixGeneration: 1,
+      meshAabb,
+      entityWorld,
+      transforms: new Float32Array(IDENTITY),
+    };
+    const first = cache.get(input);
+    expect(first).toEqual(meshAabb);
+    expect(cache.get(input)).toBe(first);
+
+    const matrixChanged = cache.get({ ...input, matrixGeneration: 2, transforms: translated(9) });
+    expect(matrixChanged).not.toBe(first);
+    expect(matrixChanged?.[0]).toBe(8);
+
+    const entityChanged = cache.get({
+      ...input,
+      transformGeneration: 2,
+      entityWorld: translated(10),
+    });
+    expect(entityChanged).not.toBe(first);
+    expect(entityChanged?.[0]).toBe(9);
+
+    const meshChanged = cache.get({
+      ...input,
+      meshGeneration: 2,
+      meshAabb: new Float32Array([-2, -1, -1, 2, 1, 1]),
+    });
+    expect(meshChanged).not.toBe(first);
+    expect(meshChanged).toEqual(new Float32Array([-2, -1, -1, 2, 1, 1]));
+
+    const reused = cache.get({ ...input, meshGeneration: 3 });
+    expect(reused).not.toBe(first);
+  });
+
+  it('does not alias equal entity keys from different worlds in one composite scene', () => {
+    const cache = new InstanceBoundsCache();
+    const first = cache.get({
+      worldId: 1,
+      entityKey: 7,
+      meshGeneration: 1,
+      transformGeneration: 1,
+      matrixGeneration: 1,
+      meshAabb,
+      entityWorld,
+      transforms: new Float32Array(IDENTITY),
+    });
+    const second = cache.get({
+      worldId: 2,
+      entityKey: 7,
+      meshGeneration: 1,
+      transformGeneration: 1,
+      matrixGeneration: 1,
+      meshAabb,
+      entityWorld: translated(20),
+      transforms: new Float32Array(IDENTITY),
+    });
+    expect(second).not.toBe(first);
+    expect(second?.[0]).toBe(19);
+  });
+
+  it('keeps bounds renderer-derived; the public Instances schema has no bounds field', () => {
+    const source = readFileSync(new URL('../components/instances.ts', import.meta.url), 'utf8');
+    expect(source).not.toMatch(/\bbounds\s*:/);
+  });
+});

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