@forgeax/engine-render 0.1.19 → 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__/ktx2-basis-gpu-consumer.dawn.test.ts

@@ -343,12 +343,11 @@ async function textureFor(
       selected,
       texture: {
         kind: 'texture',
-        width: mip.width,
-        height: mip.height,
+        shape: { viewDimension: '2d', extent: { width: mip.width, height: mip.height } },
         format: selected,
         data: mip.data,
         colorSpace: input.colorSpace,
-        mipmap: false,
+        mips: { kind: 'none' },
       },
     };
   }
@@ -377,12 +376,11 @@ async function textureFor(
     selected,
     texture: {
       kind: 'texture',
-      width: mip.width,
-      height: mip.height,
+      shape: { viewDimension: '2d', extent: { width: mip.width, height: mip.height } },
       format: selected,
       data: mip.data,
       colorSpace: input.colorSpace,
-      mipmap: false,
+      mips: { kind: 'none' },
     },
   };
 }
@@ -392,6 +390,8 @@ async function readbackTexture(
   texture: TextureAsset,
   gpuTexture: { readonly handle: Texture },
 ): Promise<Uint8Array> {
+  const width = texture.shape.extent.width;
+  const height = texture.shape.extent.height;
   const hdr = texture.format === 'rgba16float' || texture.format.startsWith('bc6h');
   const outputFormat: GPUTextureFormat = hdr ? 'rgba16float' : 'rgba8unorm-srgb';
   const outputBytesPerPixel = hdr ? 8 : 4;
@@ -447,7 +447,7 @@ async function readbackTexture(
   });
   if (!bindings.ok) throw new Error(`${bindings.error.code}:${bindings.error.hint}`);
   const normalizedTexture = device.createTexture({
-    size: { width: texture.width, height: texture.height, depthOrArrayLayers: 1 },
+    size: { width, height, depthOrArrayLayers: 1 },
     format: outputFormat,
     usage: 0x10 | 0x01,
   } as never);
@@ -457,7 +457,7 @@ async function readbackTexture(
   if (!normalizedView.ok)
     throw new Error(`${normalizedView.error.code}:${normalizedView.error.hint}`);
   const readback = device.createBuffer({
-    size: 256 * texture.height,
+    size: 256 * height,
     usage: GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_MAP_READ,
   });
   if (!readback.ok) throw new Error(`${readback.error.code}:${readback.error.hint}`);
@@ -483,9 +483,9 @@ async function readbackTexture(
       buffer: readback.value as unknown as GPUBuffer,
       offset: 0,
       bytesPerRow: 256,
-      rowsPerImage: texture.height,
+      rowsPerImage: height,
     },
-    { width: texture.width, height: texture.height, depthOrArrayLayers: 1 },
+    { width, height, depthOrArrayLayers: 1 },
   );
   const command = encoder.value.finish();
   if (!command.ok) throw new Error(`${command.error.code}:${command.error.hint}`);
@@ -497,11 +497,11 @@ async function readbackTexture(
   const range = mapped.value.getMappedRange();
   if (!range.ok) throw new Error(`${range.error.code}:${range.error.hint}`);
   const mappedBytes = new Uint8Array(range.value);
-  const bytes = new Uint8Array(texture.width * texture.height * outputBytesPerPixel);
-  for (let row = 0; row < texture.height; row += 1) {
+  const bytes = new Uint8Array(width * height * outputBytesPerPixel);
+  for (let row = 0; row < height; row += 1) {
     bytes.set(
-      mappedBytes.subarray(row * 256, row * 256 + texture.width * outputBytesPerPixel),
-      row * texture.width * outputBytesPerPixel,
+      mappedBytes.subarray(row * 256, row * 256 + width * outputBytesPerPixel),
+      row * width * outputBytesPerPixel,
     );
   }
   mapped.value.unmap();

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__/mesh-buffer-usage-surface.unit.test.ts

@@ -71,7 +71,7 @@ describe('render buffer usage owner', () => {
     expect(GPU_BUFFER_USAGE_UNIFORM).toBe(0x40);
     expect(GPU_BUFFER_USAGE_STORAGE).toBe(0x80);
     expect(GPU_BUFFER_USAGE_MAP_READ).toBe(0x01);
-    expect(ownerSource.match(/export const GPU_BUFFER_USAGE_/g)).toHaveLength(8);
+    expect(ownerSource.match(/export const GPU_BUFFER_USAGE_/g)).toHaveLength(9);
   });
 
   it('routes mesh descriptor, update, and bootstrap consumers through the owner', () => {

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;