@forgeax/engine-render 0.1.20 → 0.1.21

package/src/__tests__/bloom-lifecycle.integration.test.ts

@@ -1,9 +1,13 @@
+import { mat4, vec3 } from '@forgeax/engine-math';
 import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
 import type { RhiDevice } from '@forgeax/engine-rhi';
 import { rhi } from '@forgeax/engine-rhi-null';
 import { ok } from '@forgeax/engine-types';
 import { beforeAll, describe, expect, it } from 'vitest';
 import { DeviceScope, LifecycleTransaction } from '../device/device-scope';
+import { prepareStandardLighting } from '../pipeline/standard-lighting/prepare';
+import { deriveStandardTopologyInput } from '../pipeline/standard-lighting/topology';
+import { selectStandardClusterTransport } from '../pipeline/standard-lighting/transport';
 import { standardPipeline } from '../pipeline/standard-pipeline';
 import { DEFAULT_STANDARD_PROFILE, STANDARD_PIPELINE_ID } from '../pipeline/standard-profile';
 import type { RenderPipelineFrame, RenderPipelineTopology } from '../render-pipeline';
@@ -18,11 +22,11 @@ beforeAll(async () => {
   device = result.value;
 });
 
-function build(bloom: 'off' | 'on', lighting: 'direct' | 'clustered') {
+function build(bloom: 'off' | 'on') {
   const topology: RenderPipelineTopology = {
     pipelineId: STANDARD_PIPELINE_ID,
-    standardProfile: { ...DEFAULT_STANDARD_PROFILE, lighting },
-    config: lighting === 'clustered' ? { ssao: { enabled: false } } : undefined,
+    standardProfile: DEFAULT_STANDARD_PROFILE,
+    config: { ssao: { enabled: false } },
     surface: {
       width: 320,
       height: 180,
@@ -31,15 +35,15 @@ function build(bloom: 'off' | 'on', lighting: 'direct' | 'clustered') {
     },
     camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom },
     shadow: {
-      mapSize: 64,
-      cascadeCount: 1,
+      directional: { mapSize: 64, cascadeCount: 1 },
+      spotMapSize: 64,
       pointCount: 0,
       pointFaceSize: 64,
       spotCount: 0,
     },
     lane: {
-      compute: lighting === 'clustered',
-      storageBuffer: lighting === 'clustered',
+      compute: true,
+      storageBuffer: true,
       multisample: false,
       maxColorAttachments: 8,
     },
@@ -47,9 +51,33 @@ function build(bloom: 'off' | 'on', lighting: 'direct' | 'clustered') {
     gpuDrivenTopologySignature: '',
   };
   const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+  const prepared = prepareStandardLighting({
+    directional: undefined,
+    local: [{ kind: 'point' as const, shadowed: false, position: vec3.create(0, 0, -4), range: 2 }],
+    view: mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]),
+    projection: mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100),
+    near: 0.1,
+    far: 100,
+    grid: { x: 4, y: 3, z: 4 },
+    lightCount: DEFAULT_STANDARD_PROFILE.lightCount,
+    renderPath: 'forward',
+  });
+  if (!prepared.ok) throw prepared.error;
+  const transport = selectStandardClusterTransport(
+    { compute: true, storageBuffer: true, membershipPipelineReady: true },
+    prepared.value,
+  );
+  if (!transport.ok) throw transport.error;
+  const standardLighting = deriveStandardTopologyInput({
+    kind: 'clustered',
+    prepared: prepared.value,
+    transport: transport.value,
+  });
+  if (!standardLighting.ok) throw standardLighting.error;
   const built = standardPipeline.build(
     {
       graph,
+      standardLighting: standardLighting.value,
       projectGpuDriven: () => ok(undefined),
       contributeFeatures: () => ok(undefined),
     },
@@ -71,10 +99,10 @@ function bloomSummary(info: ReturnType<typeof build>) {
 }
 
 describe('Standard Bloom lifecycle contract', () => {
-  it.each(['direct', 'clustered'] as const)('supports on -> off -> on for %s', (lighting) => {
-    const on = bloomSummary(build('on', lighting));
-    const off = bloomSummary(build('off', lighting));
-    const recovered = bloomSummary(build('on', lighting));
+  it('supports on -> off -> on for the Standard clustered graph', () => {
+    const on = bloomSummary(build('on'));
+    const off = bloomSummary(build('off'));
+    const recovered = bloomSummary(build('on'));
     expect(on.passes).toHaveLength(4);
     expect(on.resources.length).toBeGreaterThan(0);
     expect(off).toEqual({ passes: [], resources: [] });
@@ -82,7 +110,7 @@ describe('Standard Bloom lifecycle contract', () => {
   });
 
   it('keeps post order scene -> Bloom -> output transform -> FXAA -> debug', () => {
-    const names = build('on', 'clustered').passes.map((pass) => pass.name);
+    const names = build('on').passes.map((pass) => pass.name);
     const order = [
       'forward',
       'bloom-bright',
@@ -117,7 +145,7 @@ describe('Standard Bloom lifecycle contract', () => {
   });
 
   it('FALSIFY rejects an injected Bloom contribution on the off path', () => {
-    const off = bloomSummary(build('off', 'direct'));
+    const off = bloomSummary(build('off'));
     const injected = { ...off, passes: ['bloom-falsified'] };
     expect(injected).not.toEqual({ passes: [], resources: [] });
     expect(off).toEqual({ passes: [], resources: [] });

package/src/__tests__/camera-target-consumption.unit.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { type CameraTargetCandidate, selectCameraTargetViews } from '../render-system-extract';
+import type { RenderTargetDescriptor } from '../targets/contracts';
+import { createRenderTargetOwner } from '../targets/owner';
+
+const descriptor: RenderTargetDescriptor = {
+  shape: '2d',
+  width: 16,
+  height: 16,
+  format: 'rgba8unorm',
+  mipLevels: 1,
+  sampleCount: 1,
+  sampled: true,
+  readback: false,
+};
+
+function targets() {
+  const owner = createRenderTargetOwner({ rendererId: Symbol('renderer'), initialGeneration: 1 });
+  const first = owner.create(descriptor);
+  const second = owner.create(descriptor);
+  if (!first.ok) throw first.error;
+  if (!second.ok) throw second.error;
+  return [first.value, second.value] as const;
+}
+
+describe('Camera target consumption', () => {
+  it('keeps display authority separate and applies stable auxiliary ordering and budget', () => {
+    const [first, second] = targets();
+    const cameras: CameraTargetCandidate[] = [
+      { worldId: 2, entityKey: 20, target: first, requestVersion: 1, update: 'once' },
+      { worldId: 1, entityKey: 30, target: second, requestVersion: 1, update: 'continuous' },
+      { worldId: 1, entityKey: 10, requestVersion: 0, update: 'continuous' },
+    ];
+    const selected = selectCameraTargetViews(cameras, { displayEntityKey: 10, budget: 1 });
+    expect(selected.display?.entityKey).toBe(10);
+    expect(selected.auxiliary.map((camera) => camera.entityKey)).toEqual([30]);
+    expect(selected.rejected).toHaveLength(1);
+    expect(selected.rejected[0]?.reason).toBe('budget');
+  });
+
+  it('rejects a target camera selected as display and duplicate target producers', () => {
+    const [first] = targets();
+    const cameras: CameraTargetCandidate[] = [
+      { worldId: 1, entityKey: 3, target: first, requestVersion: 1, update: 'once' },
+      { worldId: 1, entityKey: 4, target: first, requestVersion: 2, update: 'once' },
+    ];
+    const selected = selectCameraTargetViews(cameras, { displayEntityKey: 3, budget: 2 });
+    expect(selected.display).toBeUndefined();
+    expect(selected.rejected.map((entry) => entry.reason)).toEqual(
+      expect.arrayContaining(['display-target', 'duplicate-target']),
+    );
+  });
+});

package/src/__tests__/cluster-binner.unit.test.ts

@@ -0,0 +1,35 @@
+import { mat4, vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import { bin, createClusterBinScratch } from '../cluster-binner';
+
+describe('cluster binner structured boundaries', () => {
+  it('returns a complete structured overflow without truncating output', () => {
+    const grid = { x: 4, y: 3, z: 4 };
+    const view = mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]);
+    const projection = mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100);
+    const clusterGrid = new Uint32Array(grid.x * grid.y * grid.z * 2).fill(7);
+    const lightIndexList = new Uint32Array(1).fill(9);
+    const result = bin(
+      [{ position: vec3.create(0, 0, -4), range: 100 }],
+      view,
+      projection,
+      grid,
+      0.1,
+      100,
+      clusterGrid,
+      lightIndexList,
+      0,
+      createClusterBinScratch(),
+    );
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('index-overflow');
+    expect(result.error.expected).toContain('writeCount <= 0');
+    expect(result.error.hint).toContain('reduce lights');
+    expect(result.error.detail.actual).toBeGreaterThan(0);
+    expect(result.error.detail.capacity).toBe(0);
+    expect(Array.from(clusterGrid)).toEqual(new Array(clusterGrid.length).fill(0));
+    expect(Array.from(lightIndexList)).toEqual([9]);
+  });
+});

package/src/__tests__/cluster-grid-default-surface.unit.test.ts

@@ -6,15 +6,20 @@ const ownerSource = readFileSync(
   new URL('../pipeline/standard-profile.ts', import.meta.url),
   'utf8',
 );
+const layoutSource = readFileSync(
+  new URL('../pipeline/standard-lighting/layout.ts', import.meta.url),
+  'utf8',
+);
 const recordSource = readFileSync(new URL('../record/frame-lighting.ts', import.meta.url), 'utf8');
 
 describe('cluster grid default owner', () => {
   it('keeps all record-stage fallbacks on the pipeline owner', () => {
     expect(DEFAULT_CLUSTER_GRID).toEqual({ x: 16, y: 9, z: 24 });
     expect(
-      ownerSource.match(/export const DEFAULT_CLUSTER_GRID\s*=\s*\{ x: 16, y: 9, z: 24 \}/g),
+      layoutSource.match(/export const DEFAULT_CLUSTER_GRID\s*=\s*\{ x: 16, y: 9, z: 24 \}/g),
     ).toHaveLength(1);
-    expect(recordSource.match(/clusterGrid \?\? DEFAULT_CLUSTER_GRID/g)).toHaveLength(3);
+    expect(ownerSource).toMatch(/DEFAULT_CLUSTER_GRID/);
+    expect(recordSource.match(/clusterGrid \?\? DEFAULT_CLUSTER_GRID/g)).toHaveLength(1);
     expect(recordSource).not.toMatch(/clusterGrid \?\? \{\s*x: 16,\s*y: 9,\s*z: 24,\s*\}/);
   });
 });

package/src/__tests__/cube-camera-scheduler.unit.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { type CubeCaptureRequest, createCubeCaptureScheduler } from '../capture/scheduler';
+import type { RenderTarget } from '../targets/contracts';
+
+function request(target: RenderTarget, requestVersion = 1): CubeCaptureRequest {
+  return {
+    target,
+    position: [0, 0, 0],
+    near: 0.1,
+    far: 100,
+    updateIntent: 'on-demand',
+    requestVersion,
+    faceBudget: 2,
+  };
+}
+
+describe('CubeCamera capture scheduler', () => {
+  it('spends a bounded face budget and promotes only after all faces submit', () => {
+    const target = {} as RenderTarget;
+    const scheduler = createCubeCaptureScheduler({ maxFacesPerFrame: 2 });
+    expect(scheduler.request(request(target)).ok).toBe(true);
+
+    scheduler.beginFrame();
+    expect(scheduler.nextWork()).toHaveLength(2);
+    expect(scheduler.inspect(target).pendingFaces).toHaveLength(4);
+    expect(scheduler.completeSubmission(true).ok).toBe(true);
+    expect(scheduler.inspect(target).activeGeneration).toBe(0);
+
+    scheduler.beginFrame();
+    expect(scheduler.nextWork()).toHaveLength(2);
+    expect(scheduler.completeSubmission(true).ok).toBe(true);
+    expect(scheduler.inspect(target).pendingFaces).toHaveLength(2);
+    scheduler.beginFrame();
+    expect(scheduler.nextWork()).toHaveLength(2);
+    expect(scheduler.completeSubmission(true).ok).toBe(true);
+    expect(scheduler.inspect(target).pendingFaces).toEqual([]);
+    expect(scheduler.inspect(target).activeGeneration).toBe(1);
+  });
+
+  it('rejects nested capture and does not publish a partial or failed candidate', () => {
+    const target = {} as RenderTarget;
+    const scheduler = createCubeCaptureScheduler({ maxFacesPerFrame: 6 });
+    expect(scheduler.request(request(target)).ok).toBe(true);
+    scheduler.beginFrame();
+    expect(scheduler.request(request(target, 2)).ok).toBe(false);
+    expect(scheduler.nextWork()).toHaveLength(2);
+    expect(scheduler.completeSubmission(false).ok).toBe(false);
+    expect(scheduler.inspect(target).activeGeneration).toBe(0);
+    expect(scheduler.inspect(target).pendingFaces).toEqual([]);
+  });
+
+  it('waits for the FrameReceipt completion before publishing the six-face candidate', async () => {
+    const target = {} as RenderTarget;
+    const scheduler = createCubeCaptureScheduler({ maxFacesPerFrame: 6 });
+    expect(scheduler.request({ ...request(target), faceBudget: 6 }).ok).toBe(true);
+    scheduler.beginFrame();
+    expect(scheduler.nextWork()).toHaveLength(6);
+
+    let resolveCompletion: (() => void) | undefined;
+    const completion = new Promise<void>((resolve) => {
+      resolveCompletion = resolve;
+    });
+    expect(scheduler.completeSubmission(true, completion).ok).toBe(true);
+    expect(scheduler.inspect(target).activeGeneration).toBe(0);
+    resolveCompletion?.();
+    await completion;
+    await Promise.resolve();
+    expect(scheduler.inspect(target).activeGeneration).toBe(1);
+  });
+});

package/src/__tests__/cube-camera-single-submit.perf.test.ts

@@ -0,0 +1,75 @@
+import { World } from '@forgeax/engine-ecs';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { createRenderer as constructRenderer } from '../assembly/factory';
+import { createCubeCaptureScheduler } from '../capture/scheduler';
+import { Camera } from '../components/camera';
+import type { RenderTarget } from '../targets/contracts';
+
+function manifestUrl(): string {
+  return `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
+}
+
+describe('CubeCamera single-submit benchmark contract', () => {
+  it('measures actual Renderer receipts for the steady frame path', async () => {
+    const renderer = await constructRenderer(
+      { width: 1, height: 1, getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    expect((await renderer.initialization).ok).toBe(true);
+    const world = new World();
+    const spawned = world.spawn(
+      { component: Transform, data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+      { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+    );
+    expect(spawned.ok).toBe(true);
+    expect(world.update().ok).toBe(true);
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+
+    const initial = renderer.inspect().frame;
+    const receipts = [];
+    for (let index = 0; index < 6; index += 1) {
+      const frame = renderer.draw({
+        leases: [attached.value],
+        camera: { lease: attached.value },
+        environment: { lease: attached.value },
+      });
+      expect(frame.ok).toBe(true);
+      if (!frame.ok || frame.value === undefined) return;
+      receipts.push(frame.value);
+      await frame.value.completed;
+    }
+
+    const inspected = renderer.inspect();
+    expect(receipts).toHaveLength(6);
+    expect(inspected.frame.frameId - initial.frameId).toBe(6);
+    expect(inspected.perFramePassNames.length).toBeGreaterThan(0);
+    expect(inspected.state).toBe('alive');
+    await renderer.dispose();
+  });
+
+  it('retains neutral or previous active output after a failed submit', () => {
+    const target = {} as RenderTarget;
+    const scheduler = createCubeCaptureScheduler({ maxFacesPerFrame: 6 });
+    expect(
+      scheduler.request({
+        target,
+        position: [0, 0, 0],
+        near: 0.1,
+        far: 10,
+        updateIntent: 'continuous',
+        requestVersion: 1,
+        faceBudget: 6,
+      }).ok,
+    ).toBe(true);
+    scheduler.beginFrame();
+    expect(scheduler.nextWork()).toHaveLength(6);
+    expect(scheduler.completeSubmission(false).ok).toBe(false);
+    expect(scheduler.inspect(target).activeGeneration).toBe(0);
+    expect(scheduler.inspect(target).fallback).toBe('neutral');
+  });
+});

package/src/__tests__/cube-camera-view-matrices.unit.test.ts

@@ -0,0 +1,41 @@
+import { mat4, vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import { buildCubeCameraFaceViews } from '../capture/cube-views';
+import { CUBE_CAMERA_FACE_ORDER } from '../components/cube-camera';
+
+describe('CubeCamera canonical view matrices', () => {
+  it('builds six ordered views from one origin with shared near/far', () => {
+    const views = buildCubeCameraFaceViews({
+      position: [2, 3, 4],
+      near: 0.25,
+      far: 80,
+    });
+
+    expect(views.map((view) => view.face)).toEqual(CUBE_CAMERA_FACE_ORDER);
+    expect(views).toHaveLength(6);
+    expect(views.every((view) => view.near === 0.25 && view.far === 80)).toBe(true);
+    expect(
+      views.every((view) => view.view.length === 16 && view.viewProjection.length === 16),
+    ).toBe(true);
+    expect(new Set(views.map((view) => Array.from(view.view))).size).toBe(6);
+  });
+
+  it('keeps asymmetric world directions in the canonical cube face orientation', () => {
+    const views = buildCubeCameraFaceViews({ position: [0, 0, 0], near: 0.1, far: 10 });
+    const samples = [
+      { direction: [1, 0.25, -0.4], ndc: [-0.4, 0.25] },
+      { direction: [-1, 0.25, 0.4], ndc: [-0.4, 0.25] },
+      { direction: [0.35, 1, 0.25], ndc: [-0.35, -0.25] },
+      { direction: [0.35, -1, -0.25], ndc: [-0.35, -0.25] },
+      { direction: [0.35, 0.25, 1], ndc: [-0.35, 0.25] },
+      { direction: [-0.35, 0.25, -1], ndc: [-0.35, 0.25] },
+    ] as const;
+
+    for (const [index, sample] of samples.entries()) {
+      const ndc = vec3.create();
+      mat4.transformVec3(ndc, views[index]?.viewProjection ?? mat4.create(), sample.direction);
+      expect(ndc[0]).toBeCloseTo(sample.ndc[0], 5);
+      expect(ndc[1]).toBeCloseTo(sample.ndc[1], 5);
+    }
+  });
+});

package/src/__tests__/cube-camera-vocabulary.unit.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import {
+  CUBE_CAMERA_FACE_ORDER,
+  CUBE_CAMERA_UPDATE_CONTINUOUS,
+  CUBE_CAMERA_UPDATE_ON_DEMAND,
+  CUBE_CAMERA_UPDATE_ONCE,
+  CubeCamera,
+  cubeCameraUpdateIntentFromF32,
+} from '../components/cube-camera';
+import { RenderIntentInvalidError } from '../errors/render';
+
+describe('CubeCamera vocabulary', () => {
+  it('exposes the canonical faces and bounded capture facts', () => {
+    expect(CUBE_CAMERA_FACE_ORDER).toEqual(['+X', '-X', '+Y', '-Y', '+Z', '-Z']);
+    expect(CubeCamera.fields.target.type).toBe('shared<RenderTarget>');
+    expect(CubeCamera.fields.near.type).toBe('f32');
+    expect(CubeCamera.fields.far.type).toBe('f32');
+    expect(CubeCamera.fields.requestVersion.type).toBe('u32');
+    expect(CubeCamera.fields.faceBudget.type).toBe('u32');
+    expect(CubeCamera.fields.updateIntent.type).toBe('f32');
+  });
+
+  it('keeps update intent closed and decodable', () => {
+    expect(cubeCameraUpdateIntentFromF32(CUBE_CAMERA_UPDATE_ONCE)).toBe('once');
+    expect(cubeCameraUpdateIntentFromF32(CUBE_CAMERA_UPDATE_ON_DEMAND)).toBe('on-demand');
+    expect(cubeCameraUpdateIntentFromF32(CUBE_CAMERA_UPDATE_CONTINUOUS)).toBe('continuous');
+  });
+
+  it('reports invalid update intent through the structured render error contract', () => {
+    expect(() => cubeCameraUpdateIntentFromF32(99)).toThrowError(RenderIntentInvalidError);
+    try {
+      cubeCameraUpdateIntentFromF32(99);
+    } catch (error) {
+      expect(error).toBeInstanceOf(RenderIntentInvalidError);
+      if (!(error instanceof RenderIntentInvalidError)) return;
+      expect(error.code).toBe('render-intent-invalid');
+      expect(error.expected).toBe('CubeCamera.updateIntent is one of 0, 1, or 2');
+      expect(error.hint).toBe('set CubeCamera.updateIntent to 0, 1, or 2');
+      expect(error.detail).toEqual({
+        component: 'CubeCamera',
+        field: 'updateIntent',
+        value: 99,
+        allowed: [0, 1, 2],
+      });
+    }
+  });
+});

package/src/__tests__/cube-camera.integration.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { createCubeCaptureScheduler, selectCubeCaptureRenderables } from '../capture/scheduler';
+import type { RenderTarget } from '../targets/contracts';
+
+describe('CubeCamera graph contribution contract', () => {
+  it('keeps Standard geometry and environment while excluding debug, UI, and self', () => {
+    const target = {} as RenderTarget;
+    const included = selectCubeCaptureRenderables(
+      [
+        { kind: 'opaque' },
+        { kind: 'transparent' },
+        { kind: 'environment' },
+        { kind: 'debug' },
+        { kind: 'ui' },
+        { kind: 'opaque', target },
+      ],
+      target,
+    );
+    expect(included.map((entry) => entry.kind)).toEqual(['opaque', 'transparent', 'environment']);
+  });
+
+  it('does not promote a candidate until the graph submission completes all six faces', () => {
+    const target = {} as RenderTarget;
+    const scheduler = createCubeCaptureScheduler({ maxFacesPerFrame: 6 });
+    expect(
+      scheduler.request({
+        target,
+        position: [0, 0, 0],
+        near: 0.1,
+        far: 10,
+        updateIntent: 'once',
+        requestVersion: 1,
+        faceBudget: 6,
+      }).ok,
+    ).toBe(true);
+    scheduler.beginFrame();
+    expect(scheduler.nextWork()).toHaveLength(6);
+    expect(scheduler.completeSubmission(false).ok).toBe(false);
+    expect(scheduler.inspect(target).activeGeneration).toBe(0);
+    expect(scheduler.inspect(target).fallback).toBe('neutral');
+  });
+});

package/src/__tests__/device-feature-admission.unit.test.ts

@@ -0,0 +1,73 @@
+import type { RhiAdapter, RhiDevice } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import {
+  deriveDeviceFeatureAdmission,
+  isTimestampQueryAdmitted,
+} from '../assembly/device-feature-admission.js';
+
+function adapter(
+  features: string[],
+  limits?: Readonly<Record<string, number>>,
+): Pick<RhiAdapter, 'features'> & Partial<Pick<RhiAdapter, 'limits'>> {
+  return {
+    features: new Set(features) as RhiAdapter['features'],
+    ...(limits === undefined ? {} : { limits }),
+  };
+}
+
+function deviceCaps(
+  timestampQuery: boolean,
+  timestampPeriodNanoseconds: number | null,
+): Pick<RhiDevice['caps'], 'timestampQuery' | 'timestampPeriodNanoseconds'> {
+  return { timestampQuery, timestampPeriodNanoseconds };
+}
+
+describe('shared device feature admission', () => {
+  it('keeps timestamp-query out of the disabled and unsupported descriptors', () => {
+    const supported = adapter(['timestamp-query', 'texture-compression-bc']);
+    const disabled = deriveDeviceFeatureAdmission(supported);
+    const unsupported = deriveDeviceFeatureAdmission(adapter(['texture-compression-bc']), {
+      gpuPassTiming: {},
+    });
+
+    expect(disabled.requiredFeatures).toEqual(['texture-compression-bc']);
+    expect(unsupported.requiredFeatures).toEqual(['texture-compression-bc']);
+  });
+
+  it('adds only adapter-supported timestamp-query once for either timing producer', () => {
+    const result = deriveDeviceFeatureAdmission(adapter(['timestamp-query']), {
+      gpuPassTiming: {},
+    });
+
+    expect(result.requiredFeatures).toEqual(['timestamp-query']);
+  });
+
+  it('requests the transmission sampled-texture limit only when the adapter supports it', () => {
+    expect(
+      deriveDeviceFeatureAdmission(adapter([], { maxSampledTexturesPerShaderStage: 17 })),
+    ).toEqual({
+      requiredFeatures: [],
+      requiredLimits: { maxSampledTexturesPerShaderStage: 17 },
+    });
+    expect(
+      deriveDeviceFeatureAdmission(adapter([], { maxSampledTexturesPerShaderStage: 16 })),
+    ).toEqual({ requiredFeatures: [] });
+  });
+
+  it('requires both device capability and a finite positive period before admission', () => {
+    expect(isTimestampQueryAdmitted(deviceCaps(true, 1))).toBe(true);
+    expect(isTimestampQueryAdmitted(deviceCaps(false, 1))).toBe(false);
+    expect(isTimestampQueryAdmitted(deviceCaps(true, null))).toBe(false);
+    expect(isTimestampQueryAdmitted(deviceCaps(true, Number.NaN))).toBe(false);
+    expect(isTimestampQueryAdmitted(deviceCaps(true, 0))).toBe(false);
+  });
+
+  it('derives byte-identical initial and recovery request descriptors', () => {
+    const supported = adapter(['texture-compression-etc2', 'timestamp-query']);
+    const options = { gpuPassTiming: {} };
+
+    expect(deriveDeviceFeatureAdmission(supported, options)).toEqual(
+      deriveDeviceFeatureAdmission(supported, options),
+    );
+  });
+});

package/src/__tests__/direct-light-snapshot.unit.test.ts

@@ -48,14 +48,14 @@ describe('one direct-light snapshot proof', () => {
       'utf8',
     );
     const shader = await readFile(
-      new URL('../../../shader/src/hdrp-cluster-forward.wgsl', import.meta.url),
+      new URL('../../../shader/src/standard-cluster.wgsl', import.meta.url),
       'utf8',
     );
 
     expect(extract.match(/const spotLightQuery =/g)).toHaveLength(1);
     expect(extract).toContain('direction: dirN');
-    expect(lighting).toContain('packLightSlot(pl');
-    expect(lighting).toContain('packLightSlot(sl)');
+    expect(lighting).toContain('prepareStandardLighting');
+    expect(lighting).toContain('source');
     expect(shader).not.toContain('normalize(light.direction.xyz)');
   });
 });

package/src/__tests__/docs-gate-green.unit.test.ts

@@ -0,0 +1,38 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+function read(relativePath: string): string {
+  return readFileSync(new URL(relativePath, import.meta.url), 'utf8');
+}
+
+const renderReadme = read('../../README.md');
+const assetsReadme = read('../../../assets-runtime/README.md');
+const instancesSource = read('../components/instances.ts');
+
+describe('M4 material and Instances documentation contract', () => {
+  it('keeps resident observation and derived-bounds recovery discoverable', () => {
+    for (const token of [
+      'renderer.inspect().meshMaterialBindings[]',
+      '`ready`, `pending`, `failed`, or `last-known-good`',
+      'nearest structured preparation',
+      'does not keep a second readiness ledger',
+      '`Instances` remains author data',
+      'renderer derives a CPU union bound',
+      'conservative no-cull result',
+      'GPU path keeps the mesh-local AABB',
+    ]) {
+      expect(renderReadme).toContain(token);
+    }
+    for (const token of [
+      'producer lifecycle observations',
+      '`inspect -> rebuild/recook or refresh LKG -> loadByGuid`',
+      'parallel readiness ledger',
+    ]) {
+      expect(assetsReadme).toContain(token);
+    }
+  });
+
+  it('keeps bounds out of the public Instances author schema', () => {
+    expect(instancesSource).not.toMatch(/\bbounds\s*:/);
+  });
+});