@forgeax/engine-render 0.1.21 → 0.1.24

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

package/src/__tests__/lod-cpu-lane.integration.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { projectCpuDirectCandidates } from '../scene/render-scene';
+import { primitiveKey, VisibilityFacetStore, viewKey } from '../scene/visibility/facet';
+
+describe('CPU direct LOD lane', () => {
+  it('emits exactly one selected candidate per view and primitive', () => {
+    const store = new VisibilityFacetStore();
+    const view = viewKey({
+      attachmentId: 'world-a',
+      cameraEntity: 1,
+      viewRole: 'main',
+      viewGeneration: 1,
+    });
+    const primitive = primitiveKey({
+      attachmentId: 'world-a',
+      worldGeneration: 2,
+      primitiveSlot: 3,
+      slotGeneration: 0,
+    });
+    store.activateView(view);
+    store.setCandidate(view, primitive, { level: 2, confidence: 0.9 });
+
+    expect(projectCpuDirectCandidates(store, [{ view, primitives: [primitive] }])).toEqual([
+      { view, primitive, candidate: { level: 2, confidence: 0.9 } },
+    ]);
+  });
+
+  it('keeps the direct candidate order stable when only selection changes', () => {
+    const store = new VisibilityFacetStore();
+    const view = viewKey({
+      attachmentId: 'world-a',
+      cameraEntity: 1,
+      viewRole: 'main',
+      viewGeneration: 1,
+    });
+    const first = primitiveKey({
+      attachmentId: 'world-a',
+      worldGeneration: 2,
+      primitiveSlot: 1,
+      slotGeneration: 0,
+    });
+    const second = primitiveKey({
+      attachmentId: 'world-a',
+      worldGeneration: 2,
+      primitiveSlot: 2,
+      slotGeneration: 0,
+    });
+    store.activateView(view);
+    store.setCandidate(view, first, { level: 1, confidence: 1 });
+    store.setCandidate(view, second, { level: 0, confidence: 1 });
+
+    const result = projectCpuDirectCandidates(store, [{ view, primitives: [first, second] }]);
+    expect(result.map((entry) => entry.primitive.primitiveSlot)).toEqual([1, 2]);
+  });
+});

package/src/__tests__/lod-cpu-no-change.perf.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { projectCpuDirectCandidates } from '../scene/render-scene';
+import { VisibilityFacetStore } from '../scene/visibility/facet';
+
+describe('CPU LOD no-change profile', () => {
+  it('does no renderable scan and emits no candidates for an unchanged frame', () => {
+    const store = new VisibilityFacetStore();
+    const before = store.inspect();
+    const candidates = projectCpuDirectCandidates(store, []);
+    const after = store.inspect();
+
+    expect(candidates).toEqual([]);
+    expect(after).toEqual(before);
+    expect({ renderableScans: 0, facetWrites: after.facetRows }).toEqual({
+      renderableScans: 0,
+      facetWrites: 0,
+    });
+  });
+});

package/src/__tests__/lod-gpu-frame-timing.unit.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createGpuFrameTiming,
+  recordGpuFrameTiming,
+  summarizeGpuFrameTiming,
+} from '../scene/visibility/gpu-frame-timing';
+
+describe('renderer-owned GPU frame timing protocol', () => {
+  it('joins first render pass and occlusion terminal marker on one submit', () => {
+    const timing = createGpuFrameTiming({ frameId: 12, deviceGeneration: 4 });
+    const recorded = recordGpuFrameTiming(timing, {
+      firstPassTimestampNs: 1_000,
+      occlusionResolveTimestampNs: 4_000,
+      submitted: true,
+      graphGeneration: 8,
+      submitId: 3,
+    });
+
+    expect(recorded.protocol).toEqual({
+      firstMarker: 'frame.first-pass',
+      terminalMarker: 'occlusion.resolve-copy',
+      sameGraph: true,
+      sameSubmit: true,
+    });
+    expect(summarizeGpuFrameTiming([recorded])).toEqual({ medianUs: 3, p95Us: 3, samples: 1 });
+  });
+
+  it('rejects an unsubmitted or cross-submit sample instead of reporting timing', () => {
+    const timing = createGpuFrameTiming({ frameId: 13, deviceGeneration: 4 });
+    expect(() =>
+      recordGpuFrameTiming(timing, {
+        firstPassTimestampNs: 1_000,
+        occlusionResolveTimestampNs: 4_000,
+        submitted: false,
+        graphGeneration: 9,
+        submitId: 4,
+      }),
+    ).toThrow(/submitted/i);
+    expect(() =>
+      recordGpuFrameTiming(timing, {
+        firstPassTimestampNs: 1_000,
+        occlusionResolveTimestampNs: 4_000,
+        submitted: true,
+        graphGeneration: 9,
+        submitId: 5,
+      }),
+    ).toThrow(/submit/i);
+  });
+});

package/src/__tests__/lod-multi-view.integration.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import { projectCpuDirectCandidates } from '../scene/render-scene';
+import { primitiveKey, VisibilityFacetStore, viewKey } from '../scene/visibility/facet';
+
+describe('multi-view CPU LOD projection', () => {
+  it('keeps main, shadow, reflection, and probe decisions independent', () => {
+    const store = new VisibilityFacetStore();
+    const primitive = primitiveKey({
+      attachmentId: 'world-a',
+      worldGeneration: 1,
+      primitiveSlot: 4,
+      slotGeneration: 2,
+    });
+    const views = (['main', 'shadow', 'reflection', 'probe'] as const).map((viewRole, index) =>
+      viewKey({ attachmentId: 'world-a', cameraEntity: 5, viewRole, viewGeneration: index + 1 }),
+    );
+    for (const [index, view] of views.entries()) {
+      store.activateView(view);
+      store.setCandidate(view, primitive, { level: index, confidence: 1 - index * 0.1 });
+    }
+
+    const projected = projectCpuDirectCandidates(
+      store,
+      views.map((view) => ({ view, primitives: [primitive] })),
+    );
+
+    expect(projected.map((entry) => entry.candidate.level)).toEqual([0, 1, 2, 3]);
+    expect(projected).toHaveLength(4);
+  });
+
+  it('does not duplicate a primitive when views are projected together', () => {
+    const store = new VisibilityFacetStore();
+    const main = viewKey({
+      attachmentId: 'world-a',
+      cameraEntity: 1,
+      viewRole: 'main',
+      viewGeneration: 1,
+    });
+    const shadow = viewKey({
+      attachmentId: 'world-a',
+      cameraEntity: 2,
+      viewRole: 'shadow',
+      viewGeneration: 1,
+    });
+    const primitive = primitiveKey({
+      attachmentId: 'world-a',
+      worldGeneration: 1,
+      primitiveSlot: 0,
+      slotGeneration: 0,
+    });
+    store.activateView(main);
+    store.activateView(shadow);
+    store.setCandidate(main, primitive, { level: 0, confidence: 1 });
+    store.setCandidate(shadow, primitive, { level: 1, confidence: 1 });
+
+    const projected = projectCpuDirectCandidates(store, [
+      { view: main, primitives: [primitive] },
+      { view: shadow, primitives: [primitive] },
+    ]);
+    expect(projected.filter((entry) => entry.view.viewRole === 'main')).toHaveLength(1);
+    expect(projected.filter((entry) => entry.view.viewRole === 'shadow')).toHaveLength(1);
+  });
+});

package/src/__tests__/lod-occlusion-device-loss.integration.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type ConfidenceState,
+  recoverVisibilityAfterDeviceLoss,
+} from '../scene/visibility/occlusion-confidence';
+
+describe('LOD occlusion device recovery', () => {
+  it('keeps CPU projection visible, drops old generation evidence, and retries once', () => {
+    const hidden: ConfidenceState = {
+      status: 'hidden',
+      zeroStreak: 2,
+      successfulSubmits: 4,
+      queryable: true,
+      dirty: false,
+      lastResultGeneration: 7,
+    };
+    const recovered = recoverVisibilityAfterDeviceLoss(hidden, 8);
+    expect(recovered).toMatchObject({
+      status: 'visible',
+      queryable: true,
+      dirty: true,
+      successfulSubmits: 0,
+      lastResultGeneration: undefined,
+      retryCount: 1,
+    });
+  });
+});

package/src/__tests__/lod-occlusion-final-decision.integration.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import {
+  decideVisibility,
+  type VisibilityDecisionInput,
+} from '../scene/visibility/occlusion-confidence';
+
+const visibleInput: VisibilityDecisionInput = {
+  authorVisible: true,
+  validBounds: true,
+  frustumVisible: true,
+  lodReady: true,
+  occlusion: { status: 'visible', queryable: true },
+};
+
+describe('LOD and occlusion final decision', () => {
+  it('evaluates author, bounds, frustum, LOD, then shared confidence', () => {
+    expect(decideVisibility(visibleInput)).toMatchObject({ draw: true, stage: 'occlusion' });
+    expect(decideVisibility({ ...visibleInput, authorVisible: false })).toMatchObject({
+      draw: false,
+      stage: 'author',
+    });
+    expect(decideVisibility({ ...visibleInput, validBounds: false })).toMatchObject({
+      draw: true,
+      stage: 'bounds',
+    });
+    expect(decideVisibility({ ...visibleInput, frustumVisible: false })).toMatchObject({
+      draw: false,
+      stage: 'frustum',
+    });
+    expect(decideVisibility({ ...visibleInput, lodReady: false })).toMatchObject({
+      draw: true,
+      stage: 'lod',
+    });
+    expect(
+      decideVisibility({ ...visibleInput, occlusion: { status: 'hidden', queryable: true } }),
+    ).toMatchObject({ draw: false, stage: 'occlusion' });
+    expect(
+      decideVisibility({ ...visibleInput, occlusion: { status: 'hidden', queryable: false } }),
+    ).toMatchObject({ draw: true, stage: 'occlusion' });
+  });
+
+  it('returns the same decision shape for CPU and GPU lanes', () => {
+    const cpu = decideVisibility({ ...visibleInput, lane: 'cpu' });
+    const gpu = decideVisibility({ ...visibleInput, lane: 'gpu' });
+    expect(gpu).toEqual(cpu);
+  });
+});

package/src/__tests__/lod-occlusion-inspection.integration.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, it } from 'vitest';
+import { resolveInspectionBuild } from '../render-system';
+import { inspectLodOcclusion } from '../scene/visibility/inspection';
+
+describe('LOD occlusion inspection lifecycle', () => {
+  it('uses the build-tool revision for inspection submits', () => {
+    expect(resolveInspectionBuild({ build: 'merge-ref-123' })).toBe('merge-ref-123');
+    expect(resolveInspectionBuild({ build: undefined })).toBe('render-system');
+  });
+
+  it('publishes one detached row per World attachment for a single submit', () => {
+    const inspection = inspectLodOcclusion({
+      root: { guid: '018e7a4d-1234-7abc-8def-000000000002', sourceKey: 'assets/lod-scene.gltf' },
+      view: { attachmentId: 'world-a', cameraEntity: 1, viewRole: 'main', viewGeneration: 4 },
+      slot: { primitiveSlot: 2, slotGeneration: 9 },
+      generation: 10,
+      count: { candidates: 2, visible: 1, occluded: 1 },
+      lodHistogram: [{ level: 0, count: 2 }],
+      queryLatencyUs: { median: 4, p95: 8, last: 3 },
+      pagePressure: { used: 1, capacity: 3 },
+      fallback: { active: false },
+      degradation: { active: false },
+      samples: [],
+      submit: { frameId: 10, build: 'test-build', deviceGeneration: 2 },
+      budget: {
+        configuredQueryBudget: 2048,
+        effectiveQueryBudget: 2048,
+        settleSubmits: 98,
+        retestSubmits: 44,
+        expirySubmits: 88,
+      },
+      worlds: [
+        {
+          attachmentId: 'world-a',
+          rows: [
+            {
+              root: {
+                guid: '018e7a4d-1234-7abc-8def-000000000002',
+                sourceKey: 'assets/lod-scene.gltf',
+              },
+              view: {
+                attachmentId: 'world-a',
+                cameraEntity: 1,
+                viewRole: 'main',
+                viewGeneration: 4,
+              },
+              slot: { primitiveSlot: 2, slotGeneration: 9 },
+              generation: 10,
+              count: { candidates: 2, visible: 1, occluded: 1 },
+              lodHistogram: [{ level: 0, count: 2 }],
+              queryLatencyUs: { median: 4, p95: 8, last: 3 },
+              pagePressure: { used: 1, capacity: 3 },
+              fallback: { active: false },
+              degradation: { active: false },
+              samples: [],
+            },
+          ],
+        },
+        {
+          attachmentId: 'world-b',
+          rows: [],
+        },
+      ],
+    });
+
+    expect(inspection.schema).toBe('forgeax::lod-occlusion-inspection::v2');
+    expect(inspection.submit).toEqual({ frameId: 10, build: 'test-build', deviceGeneration: 2 });
+    expect(inspection.budget.effectiveQueryBudget).toBe(2048);
+    expect(inspection.worlds.map((world) => world.attachmentId)).toEqual(['world-a', 'world-b']);
+    expect(inspection.worlds[0]?.attribution).toEqual({
+      status: 'unavailable',
+      reason: 'projection-only',
+    });
+    expect(inspection.worlds[0]?.rows[0]?.count).toEqual({
+      candidates: 2,
+      visible: 1,
+      occluded: 1,
+    });
+    expect(Object.isFrozen(inspection.worlds)).toBe(true);
+    expect(Object.isFrozen(inspection.worlds[0]?.rows)).toBe(true);
+  });
+
+  it('only accepts same-submit World attribution with the parent submit identity', () => {
+    const submit = { frameId: 12, build: 'test-build', deviceGeneration: 2 };
+    const row = {
+      root: { guid: '018e7a4d-1234-7abc-8def-000000000002', sourceKey: 'assets/lod-scene.gltf' },
+      view: {
+        attachmentId: 'world-a',
+        cameraEntity: 1,
+        viewRole: 'main' as const,
+        viewGeneration: 4,
+      },
+      slot: { primitiveSlot: 2, slotGeneration: 9 },
+      generation: 12,
+      count: { candidates: 2, visible: 1, occluded: 1 },
+      lodHistogram: [{ level: 0, count: 2 }],
+      queryLatencyUs: { median: 4, p95: 8, last: 3 },
+      pagePressure: { used: 1, capacity: 3 },
+      fallback: { active: false as const },
+      degradation: { active: false as const },
+      samples: [],
+    };
+    const inspection = inspectLodOcclusion({
+      ...row,
+      submit,
+      worlds: [
+        {
+          attachmentId: 'world-a',
+          attribution: { status: 'same-submit', submit },
+          rows: [row],
+        },
+      ],
+    });
+
+    expect(inspection.worlds[0]?.attribution).toEqual({
+      status: 'same-submit',
+      submit,
+    });
+    expect(() =>
+      inspectLodOcclusion({
+        ...row,
+        submit,
+        worlds: [
+          {
+            attachmentId: 'world-a',
+            attribution: {
+              status: 'same-submit',
+              submit: { ...submit, frameId: submit.frameId + 1 },
+            },
+            rows: [row],
+          },
+        ],
+      }),
+    ).toThrow('world attribution must reference the parent inspection submit');
+  });
+
+  it('joins reordered World rows by attachment identity, not array position', () => {
+    const submit = { frameId: 20, build: 'test-build', deviceGeneration: 3 };
+    const row = (attachmentId: string, primitiveSlot: number, candidates: number) => ({
+      root: { guid: `asset-${attachmentId}`, sourceKey: `world:${attachmentId}` },
+      view: {
+        attachmentId,
+        cameraEntity: 1,
+        viewRole: 'main' as const,
+        viewGeneration: 7,
+      },
+      slot: { primitiveSlot, slotGeneration: 11 },
+      generation: 20,
+      count: { candidates, visible: candidates - 1, occluded: 1 },
+      lodHistogram: [{ level: 1, count: candidates }],
+      queryLatencyUs: { median: 3, p95: 5, last: 2 },
+      pagePressure: { used: 2, capacity: 12 },
+      fallback: { active: false as const },
+      degradation: { active: false as const },
+      samples: [],
+    });
+    const inspection = inspectLodOcclusion({
+      ...row('world-a', 4, 3),
+      submit,
+      worlds: [
+        {
+          attachmentId: 'world-b',
+          attribution: { status: 'same-submit', submit },
+          rows: [row('world-b', 9, 5)],
+        },
+        {
+          attachmentId: 'world-a',
+          attribution: { status: 'same-submit', submit },
+          rows: [row('world-a', 4, 3)],
+        },
+      ],
+    });
+
+    const byAttachment = new Map(
+      inspection.worlds.map((world) => [world.attachmentId, world] as const),
+    );
+    expect(byAttachment.get('world-a')?.rows[0]?.slot).toEqual({
+      primitiveSlot: 4,
+      slotGeneration: 11,
+    });
+    expect(byAttachment.get('world-b')?.rows[0]?.count.candidates).toBe(5);
+    expect(byAttachment.get('world-b')?.attribution).toEqual({
+      status: 'same-submit',
+      submit,
+    });
+  });
+
+  it('keeps identity and generation attached to a failed publication without suppressing draw', () => {
+    const inspection = inspectLodOcclusion({
+      root: { guid: '018e7a4d-1234-7abc-8def-000000000002', sourceKey: 'assets/lod-scene.gltf' },
+      view: { attachmentId: 'main', cameraEntity: 1, viewRole: 'main', viewGeneration: 4 },
+      slot: { primitiveSlot: 2, slotGeneration: 9 },
+      generation: 10,
+      count: { candidates: 100_000, visible: 100_000, occluded: 0 },
+      lodHistogram: [{ level: 0, count: 100_000 }],
+      queryLatencyUs: { median: 0, p95: 0, last: 0 },
+      pagePressure: { used: 3, capacity: 3 },
+      fallback: {
+        active: true,
+        reason: 'page-exhausted',
+        error: {
+          code: 'occlusion-query-unavailable',
+          expected: 'a bounded query page reservation',
+          hint: 'keep the candidate visible and retry on the next submitted frame',
+          detail: { capacity: 3 },
+        },
+      },
+      degradation: { active: true, reason: 'all-visible' },
+      samples: [],
+    });
+
+    expect(inspection.fallback.active).toBe(true);
+    expect(inspection.degradation).toEqual({ active: true, reason: 'all-visible' });
+    expect(inspection.count.visible).toBe(inspection.count.candidates);
+    expect(inspection.generation).toBe(10);
+  });
+});

package/src/__tests__/lod-occlusion-inspection.schema.test-d.ts

@@ -0,0 +1,14 @@
+import { expectTypeOf, test } from 'vitest';
+import type { LodOcclusionInspection } from '../scene/visibility/inspection';
+
+test('LOD occlusion inspection is detached JSON-safe POD', () => {
+  const inspection = {} as LodOcclusionInspection;
+  expectTypeOf(inspection.root.guid).toEqualTypeOf<string>();
+  expectTypeOf(inspection.samples).toEqualTypeOf<
+    readonly LodOcclusionInspection['samples'][number][]
+  >();
+  // @ts-expect-error live GPU handles must not cross the inspection boundary
+  inspection.device;
+  // @ts-expect-error mutable renderer state must not cross the inspection boundary
+  inspection.mutableState;
+});