@forgeax/engine-render 0.1.21 → 0.1.23

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

package/src/__tests__/lighting-scene-roundtrip.integration.test.ts

@@ -0,0 +1,109 @@
+import { parseScenePayload } from '@forgeax/engine-assets-runtime';
+import { externalizeSceneAsset } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { LightProbe, RectAreaLight, SpotLight } from '../components';
+
+const IES_GUID = '019ffa97-4000-7000-8000-000000000001';
+const COOKIE_GUID = '019ffa97-4000-7000-8000-000000000002';
+
+function schemaOf(component: { readonly fields: Record<string, unknown> }) {
+  return Object.fromEntries(
+    Object.entries(component.fields).map(([name, field]) => [
+      name,
+      typeof field === 'string' ? field : (field as { readonly type: string }).type,
+    ]),
+  );
+}
+
+const schemas = new Map<string, Record<string, string>>([
+  [RectAreaLight.name, schemaOf(RectAreaLight)],
+  [SpotLight.name, schemaOf(SpotLight)],
+  [LightProbe.name, schemaOf(LightProbe)],
+]);
+
+describe('lighting scene payload roundtrip', () => {
+  it('round-trips public light fields and both Spot handle GUIDs', () => {
+    const scene = {
+      kind: 'scene' as const,
+      entities: [
+        {
+          localId: 7 as never,
+          components: {
+            RectAreaLight: {
+              color: [1, 0.5, 0.25],
+              intensity: 12,
+              width: 2,
+              height: 3,
+              range: 8,
+            },
+            LightProbe: { irradiance: new Float32Array(27).fill(0.25), radius: 4 },
+            SpotLight: {
+              direction: [0, -1, 0],
+              iesProfile: IES_GUID,
+              cookie: COOKIE_GUID,
+              rollDeg: 360,
+            },
+            Transform: { scale: [2, 3, 4] },
+          },
+        },
+      ],
+    };
+    const externalized = externalizeSceneAsset(scene, (name) => schemas.get(name));
+    expect(externalized.ok).toBe(true);
+    if (!externalized.ok) return;
+    expect(externalized.value.refs).toEqual([
+      {
+        guid: IES_GUID,
+        sourceField: { componentName: 'SpotLight', fieldName: 'iesProfile' },
+        sceneEntityId: 7,
+      },
+      {
+        guid: COOKIE_GUID,
+        sourceField: { componentName: 'SpotLight', fieldName: 'cookie' },
+        sceneEntityId: 7,
+      },
+    ]);
+    expect(externalized.value.payload.entities).toEqual([
+      {
+        localId: 7,
+        components: {
+          RectAreaLight: { color: [1, 0.5, 0.25], intensity: 12, width: 2, height: 3, range: 8 },
+          LightProbe: { irradiance: new Float32Array(27).fill(0.25), radius: 4 },
+          SpotLight: { direction: [0, -1, 0], iesProfile: 0, cookie: 1, rollDeg: 360 },
+          Transform: { scale: [2, 3, 4] },
+        },
+      },
+    ]);
+    const parsed = parseScenePayload(externalized.value.payload, [IES_GUID, COOKIE_GUID]);
+    expect(parsed).toMatchObject({
+      kind: 'scene',
+      entities: [
+        {
+          localId: 7,
+          components: {
+            SpotLight: { iesProfile: IES_GUID, cookie: COOKIE_GUID, rollDeg: 360 },
+            Transform: { scale: [2, 3, 4] },
+          },
+        },
+      ],
+    });
+  });
+
+  it('keeps absent Spot handles absent instead of creating refs', () => {
+    const scene = {
+      kind: 'scene' as const,
+      entities: [{ localId: 8 as never, components: { SpotLight: { rollDeg: 90 } } }],
+    };
+    const externalized = externalizeSceneAsset(scene, (name) => schemas.get(name));
+    expect(externalized).toEqual({
+      ok: true,
+      value: {
+        payload: {
+          kind: 'scene',
+          entities: [{ localId: 8, components: { SpotLight: { rollDeg: 90 } } }],
+        },
+        refs: [],
+      },
+    });
+  });
+});

package/src/__tests__/lod-bounds.unit.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type BoundsCandidate,
+  conservativeBounds,
+  conservativeVisibleCandidate,
+  encloseBounds,
+} from '../scene/visibility/bounds';
+
+describe('LOD conservative bounds', () => {
+  it('encloses root and lower-level bounds', () => {
+    expect(
+      encloseBounds([
+        conservativeBounds([-1, -1, -1], [1, 1, 1]),
+        conservativeBounds([-2, 0, -0.5], [0.5, 3, 0.5]),
+      ]),
+    ).toEqual({ min: [-2, -1, -1], max: [1, 3, 1] });
+  });
+
+  it('normalizes inverted bounds into a conservative enclosure', () => {
+    expect(conservativeBounds([2, 3, 4], [-2, -3, -4])).toEqual({
+      min: [-2, -3, -4],
+      max: [2, 3, 4],
+    });
+  });
+
+  it.each<BoundsCandidate>([
+    { bounds: undefined, transparent: false, deformed: false },
+    { bounds: undefined, transparent: true, deformed: false },
+    { bounds: undefined, transparent: false, deformed: true },
+  ])('keeps non-queryable candidates conservatively visible: %o', (candidate) => {
+    expect(conservativeVisibleCandidate(candidate)).toEqual({ visible: true, queryable: false });
+  });
+
+  it('marks stable opaque bounded candidates queryable', () => {
+    const bounds = conservativeBounds([-1, -1, -1], [1, 1, 1]);
+    expect(conservativeVisibleCandidate({ bounds, transparent: false, deformed: false })).toEqual({
+      visible: false,
+      queryable: true,
+      bounds,
+    });
+  });
+});