@forgeax/engine-render 0.1.20 → 0.1.21

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__/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__/material-observation.integration.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+import {
+  projectMeshMaterialBindingObservation,
+  summarizeMeshMaterialBindings,
+} from '../mesh-material-bindings';
+
+const bindings = [
+  { handle: 11, source: 'renderer-override' as const },
+  { handle: 12, source: 'mesh-default' as const },
+  { handle: 0, source: 'engine-default' as const },
+];
+
+const failure = {
+  code: 'material-specialization-stale-generation',
+  expected: 'a stable material publication generation',
+  hint: 'retry the producer-owned material rebuild',
+  detail: { material: 'mat-a', dependencies: ['texture/a'] },
+};
+
+describe('resident MeshMaterialBindingObservation', () => {
+  it('projects sampler, readiness, mip, and nearest preparation failure without producer fields', () => {
+    const observation = projectMeshMaterialBindingObservation({
+      worldId: 2,
+      entityKey: 9,
+      bindings,
+      diagnostics: [],
+      residency: [
+        {
+          readiness: 'ready',
+          samplers: [{ handle: 101, resident: true }],
+          textures: [{ handle: 201, mipLevelCount: 4 }],
+        },
+        {
+          readiness: 'pending',
+          samplers: [{ handle: 102, resident: false }],
+          textures: [{ handle: 202, mipLevelCount: 1 }],
+        },
+        {
+          readiness: 'last-known-good',
+          samplers: [{ handle: 103, resident: true }],
+          textures: [{ handle: 203, mipLevelCount: 2 }],
+          preparationFailure: failure,
+        },
+      ],
+    });
+
+    expect(observation).toMatchObject({
+      worldId: 2,
+      entityKey: 9,
+      bindings,
+      residency: [
+        { readiness: 'ready', textures: [{ mipLevelCount: 4 }] },
+        { readiness: 'pending' },
+        { readiness: 'last-known-good', preparationFailure: failure },
+      ],
+    });
+    expect(observation).not.toHaveProperty('materialAsset');
+    expect(observation).not.toHaveProperty('producerReadiness');
+  });
+
+  it('recomputes aggregate counts from the retained observations', () => {
+    const first = projectMeshMaterialBindingObservation({
+      worldId: 0,
+      entityKey: 1,
+      bindings,
+      diagnostics: [],
+      residency: [
+        { readiness: 'ready', samplers: [], textures: [] },
+        { readiness: 'failed', samplers: [], textures: [], preparationFailure: failure },
+        { readiness: 'pending', samplers: [], textures: [] },
+      ],
+    });
+    expect(summarizeMeshMaterialBindings([first])).toEqual({
+      total: 3,
+      ready: 1,
+      pending: 1,
+      failed: 1,
+      lastKnownGood: 0,
+      textureCount: 0,
+      samplerCount: 0,
+    });
+
+    const rebuilt = projectMeshMaterialBindingObservation({
+      ...first,
+      residency: [
+        { readiness: 'ready', samplers: [], textures: [] },
+        { readiness: 'last-known-good', samplers: [], textures: [], preparationFailure: failure },
+        { readiness: 'ready', samplers: [], textures: [] },
+      ],
+    });
+    expect(summarizeMeshMaterialBindings([rebuilt])).toEqual({
+      total: 3,
+      ready: 2,
+      pending: 0,
+      failed: 0,
+      lastKnownGood: 1,
+      textureCount: 0,
+      samplerCount: 0,
+    });
+  });
+});

package/src/__tests__/pbr-view-layout.unit.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { buildPbrViewBglEntries } from '../pbr-pipeline';
+
+describe('PBR view bind-group layout', () => {
+  it('allows capture passes to select a per-face View UBO slot', () => {
+    const entries = buildPbrViewBglEntries({ storageBuffer: true });
+    const binding0 = entries[0];
+    expect(binding0?.binding).toBe(0);
+    expect(binding0?.buffer).toEqual({ type: 'uniform', hasDynamicOffset: true });
+    expect(
+      entries
+        .filter((entry) => entry.buffer?.hasDynamicOffset === true)
+        .map((entry) => entry.binding),
+    ).toEqual([0, 10]);
+  });
+});

package/src/__tests__/point-shadow-inspection.unit.test.ts

@@ -0,0 +1,60 @@
+import { vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import { inspectPointShadow } from '../point-shadow-inspection';
+import type { PointShadowSnapshot } from '../render-system-extract';
+import { SHADOW_ATLAS_DEFAULT_LAYERS } from '../shadow-atlas';
+
+function snapshots(...layers: number[]): PointShadowSnapshot[] {
+  return layers.map((shadowAtlasLayer, entity) => ({
+    entity,
+    position: vec3.create(0, 0, 0),
+    mapSize: 512,
+    nearPlane: 0.1,
+    farPlane: 25,
+    shadowAtlasLayer,
+    shadowMatrices: new Float32Array(96),
+  }));
+}
+
+describe('point-shadow inspection', () => {
+  it('derives requested, admitted, shadowed, and occupancy from one layer projection', () => {
+    expect(inspectPointShadow(snapshots(0, 1, 2, 3, -1), SHADOW_ATLAS_DEFAULT_LAYERS)).toEqual({
+      status: 'over-budget',
+      requested: SHADOW_ATLAS_DEFAULT_LAYERS + 1,
+      admitted: SHADOW_ATLAS_DEFAULT_LAYERS,
+      shadowed: SHADOW_ATLAS_DEFAULT_LAYERS,
+      shadowAtlasOccupancy: SHADOW_ATLAS_DEFAULT_LAYERS,
+      shadowAtlasCapacity: SHADOW_ATLAS_DEFAULT_LAYERS,
+    });
+  });
+
+  it('reports disabled shadow production without inventing a fallback admission', () => {
+    expect(inspectPointShadow([], SHADOW_ATLAS_DEFAULT_LAYERS)).toEqual({
+      status: 'inactive',
+      requested: 0,
+      admitted: 0,
+      shadowed: 0,
+      shadowAtlasOccupancy: 0,
+      shadowAtlasCapacity: SHADOW_ATLAS_DEFAULT_LAYERS,
+    });
+  });
+
+  it('treats an invalid layer as non-admitted and keeps the request visible', () => {
+    expect(inspectPointShadow(snapshots(-1, 7), SHADOW_ATLAS_DEFAULT_LAYERS)).toMatchObject({
+      status: 'over-budget',
+      requested: 2,
+      admitted: 0,
+      shadowed: 0,
+      shadowAtlasOccupancy: 0,
+    });
+  });
+
+  it('does not call a partially admitted request ready', () => {
+    expect(inspectPointShadow(snapshots(0, -1), SHADOW_ATLAS_DEFAULT_LAYERS)).toMatchObject({
+      status: 'over-budget',
+      requested: 2,
+      admitted: 1,
+      shadowed: 1,
+    });
+  });
+});

package/src/__tests__/public-surface.test-d.ts

@@ -1,9 +1,13 @@
 import type {
   FrameObservationRequest,
   FrameReceipt,
+  RenderError as PublicRenderError,
+  ReflectionProbeInspection,
+  ReflectionProbeSelectionInspection,
   RendererState,
   RenderFrameInput,
   RenderInspection,
+  RenderIntentInvalidDetail,
   RenderWorldLease,
 } from '@forgeax/engine-render';
 import {
@@ -15,6 +19,7 @@ import {
   visibilityStateFromU32,
 } from '@forgeax/engine-render';
 import { GlyphText, Tilemap } from '@forgeax/engine-render/authoring';
+import { expectTypeOf } from 'vitest';
 
 void Camera;
 void Atmosphere;
@@ -52,6 +57,11 @@ const alive: RendererState = 'alive';
 void alive;
 
 declare const inspection: RenderInspection;
+const reflectionInspection: ReflectionProbeInspection = inspection.reflectionProbes;
+const reflectionSelection: ReflectionProbeSelectionInspection = reflectionInspection.selection;
+void reflectionSelection;
+type IntentError = Extract<PublicRenderError, { readonly code: 'render-intent-invalid' }>;
+expectTypeOf<IntentError['detail']>().toEqualTypeOf<RenderIntentInvalidDetail>();
 const backendKind: RenderInspection['capabilities']['backendKind'] =
   inspection.capabilities.backendKind;
 void backendKind;

package/src/__tests__/reflection-probe-authoring.unit.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import {
+  REFLECTION_PROBE_UPDATE_ON_CHANGE,
+  ReflectionProbe,
+  reflectionProbeUpdateIntentFromF32,
+} from '../components/reflection-probe';
+import { RenderIntentInvalidError } from '../errors/render';
+import {
+  admitReflectionProbe,
+  DEFAULT_REFLECTION_PROBE_LIMITS,
+  estimateReflectionProbeBytes,
+  type ReflectionProbeInput,
+  validateReflectionProbeInput,
+} from '../reflection/projection';
+
+const invalidInputs: readonly ReflectionProbeInput[] = [
+  { halfExtents: [0, 1, 1], priority: 0, intensity: 1, resolution: 256 },
+  { halfExtents: [1, 1, 1], priority: Number.NaN, intensity: 1, resolution: 256 },
+  { halfExtents: [1, 1, 1], priority: 0, intensity: -1, resolution: 256 },
+  { halfExtents: [1, 1, 1], priority: 0, intensity: 1, resolution: 0 },
+];
+
+describe('ReflectionProbe authoring and admission', () => {
+  it('exposes bounded axis-aligned probe vocabulary', () => {
+    expect(ReflectionProbe.fields.halfExtents.type).toBe('array<f32, 3>');
+    expect(ReflectionProbe.fields.priority.type).toBe('f32');
+    expect(ReflectionProbe.fields.intensity.type).toBe('f32');
+    expect(ReflectionProbe.fields.resolution.type).toBe('u32');
+    expect(ReflectionProbe.fields.updateIntent.type).toBe('f32');
+    expect(ReflectionProbe.fields.invalidationVersion.type).toBe('u32');
+    expect(reflectionProbeUpdateIntentFromF32(REFLECTION_PROBE_UPDATE_ON_CHANGE)).toBe('on-change');
+  });
+
+  it('reports invalid update intent through the structured render error contract', () => {
+    expect(() => reflectionProbeUpdateIntentFromF32(99)).toThrowError(RenderIntentInvalidError);
+    try {
+      reflectionProbeUpdateIntentFromF32(99);
+    } catch (error) {
+      expect(error).toBeInstanceOf(RenderIntentInvalidError);
+      if (!(error instanceof RenderIntentInvalidError)) return;
+      expect(error.code).toBe('render-intent-invalid');
+      expect(error.expected).toBe('ReflectionProbe.updateIntent is one of 0, 1, or 2');
+      expect(error.hint).toBe('set ReflectionProbe.updateIntent to 0, 1, or 2');
+      expect(error.detail).toEqual({
+        component: 'ReflectionProbe',
+        field: 'updateIntent',
+        value: 99,
+        allowed: [0, 1, 2],
+      });
+    }
+  });
+
+  it.each(invalidInputs)('rejects invalid authoring input %#', (input) => {
+    expect(validateReflectionProbeInput(input).ok).toBe(false);
+  });
+
+  it('admits the profile boundary and rejects the first over-budget probe', () => {
+    const probe = { halfExtents: [1, 1, 1] as const, priority: 0, intensity: 1, resolution: 256 };
+    const bytes = estimateReflectionProbeBytes(probe.resolution);
+    expect(bytes * DEFAULT_REFLECTION_PROBE_LIMITS.maxProbes).toBeLessThanOrEqual(
+      DEFAULT_REFLECTION_PROBE_LIMITS.maxBytes,
+    );
+    expect(admitReflectionProbe(probe, { acceptedCount: 15, acceptedBytes: bytes * 15 })).toEqual({
+      ok: true,
+      acceptedBytes: bytes * 16,
+    });
+    expect(admitReflectionProbe(probe, { acceptedCount: 16, acceptedBytes: bytes * 16 }).ok).toBe(
+      false,
+    );
+  });
+});