@forgeax/engine-render 0.1.21 → 0.1.24

package/src/__tests__/material-contract-inventory.unit.test.ts

@@ -36,15 +36,30 @@ describe('vertex color does not change the material contract', () => {
 
   it('keeps the standard authoring parameters derived from the shared schema', () => {
     const material = Materials.standard({ baseColor: [1, 1, 1, 1] });
-    expect(material.parameters?.map((parameter) => parameter.name)).toEqual(
-      DEFAULT_STANDARD_PBR_PARAM_SCHEMA.map((entry) => entry.name),
-    );
-    expect(material.values).toMatchObject({
-      transmission: 0,
-      ior: 1.5,
-      thickness: 0,
-      attenuationColor: [1, 1, 1],
-    });
+    expect(material.parameters?.map((parameter) => parameter.name)).toEqual([
+      'baseColor',
+      'metallic',
+      'roughness',
+      'metallicChannel',
+      'roughnessChannel',
+      'aoChannel',
+      'extraChannel',
+      'emissive',
+      'emissiveIntensity',
+      'occlusionStrength',
+      'alphaCutoff',
+      'specular',
+      'specularColor',
+      'normalScale',
+      'ior',
+      'baseColorTexture',
+      'metallicRoughnessTexture',
+      'normalTexture',
+      'emissiveTexture',
+      'occlusionTexture',
+    ]);
+    expect(material.values).not.toHaveProperty('transmission');
+    expect(material.values).toHaveProperty('ior', 1.5);
   });
 
   it('routes active transmission to Forward and ShadowCaster only', () => {
@@ -53,6 +68,23 @@ describe('vertex color does not change the material contract', () => {
     expect(material.passes?.[0]?.renderState).toMatchObject({ depthWriteEnabled: false });
   });
 
+  it.each([
+    [
+      'unlit',
+      Materials.unlit([1, 1, 1, 1], { renderState: { cullMode: 'none', frontFace: 'cw' } }),
+    ],
+    [
+      'standard',
+      Materials.standard({
+        baseColor: [1, 1, 1, 1],
+        renderState: { cullMode: 'none', frontFace: 'cw' },
+      }),
+    ],
+  ] as const)('projects the %s material raster orientation into its ShadowCaster pass', (_name, material) => {
+    const shadowCaster = material.passes?.find((entry) => entry.name === 'shadow-caster');
+    expect(shadowCaster?.renderState).toMatchObject({ cullMode: 'none', frontFace: 'cw' });
+  });
+
   it.each([
     ['transmission', { transmission: -0.1 }],
     ['ior', { ior: 0 }],

package/src/__tests__/material-cooked-projection.unit.test.ts

@@ -1,8 +1,10 @@
 import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '@forgeax/engine-shader';
+import type { MaterialParameter, MaterialPass } from '@forgeax/engine-types';
 import { derive } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import { projectStandardLayerPlan } from '../assembly/material/standard-layer-projection.js';
 
-describe('standard material cooked projection', () => {
+describe('cooked material render projection', () => {
   it('uses one schema for reflection, uniform layout, and resource bindings', () => {
     const derived = derive(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);
     const names = derived.numericMembers.map((member) => member.name);
@@ -19,4 +21,20 @@ describe('standard material cooked projection', () => {
       ]),
     );
   });
+
+  it('projects the prepared contract without reading authored values', () => {
+    const parameters: readonly MaterialParameter[] = [
+      { name: 'baseColor', type: 'color' },
+      { name: 'metallic', type: 'f32' },
+      { name: 'roughness', type: 'f32' },
+    ];
+    const passes: readonly MaterialPass[] = [
+      { name: 'forward', program: { module: 'forgeax_material::standard' } },
+      { name: 'deferred', program: { module: 'forgeax_material::standard' } },
+      { name: 'shadow-caster', program: { module: 'forgeax_material::standard' } },
+    ];
+    const plan = projectStandardLayerPlan(parameters, passes);
+    expect(plan.mode).toBe('base-only');
+    expect(plan.passFamily).toEqual(['forward', 'deferred', 'shadow']);
+  });
 });

package/src/__tests__/material-static-dynamic-route.unit.test.ts

@@ -1,4 +1,5 @@
 import type { CookedMaterialRecord } from '@forgeax/engine-pack';
+import { deriveStandardLayerPlan } from '@forgeax/engine-types';
 import { describe, expect, it, vi } from 'vitest';
 import { assembleMaterialProjection } from '../assembly/material/assembly.js';
 import {
@@ -59,6 +60,34 @@ const record: CookedMaterialRecord = {
 };
 
 describe('cooked material static and dynamic routing', () => {
+  it('rejects a stale Standard layer plan before render projection', () => {
+    const standardPass = { name: 'forward', program: { module: 'forgeax::default-standard-pbr' } };
+    const standardResolved = { ...record.resolved, passes: [standardPass] };
+    const expected = deriveStandardLayerPlan(
+      standardResolved.parameters,
+      standardResolved.passes,
+    ).identity;
+    const standardRecord = {
+      ...record,
+      resolved: standardResolved,
+      receipt: {
+        ...record.receipt,
+        derivedInterface: { layoutIdentity: 'sha256:layout', layerPlanIdentity: expected },
+      },
+    } as CookedMaterialRecord;
+
+    expect(assembleMaterialProjection(standardRecord).layerPlan.identity).toBe(expected);
+    expect(() =>
+      assembleMaterialProjection({
+        ...standardRecord,
+        receipt: {
+          ...standardRecord.receipt,
+          derivedInterface: { layoutIdentity: 'sha256:layout', layerPlanIdentity: 'stale' },
+        },
+      }),
+    ).toThrow('Standard material layer-plan identity mismatch');
+  });
+
   it('updates runtime values without requesting a compile or changing the artifact key', () => {
     const projection = assembleMaterialProjection(record);
     const updated = updateMaterialRuntimeValues(projection, {

package/src/__tests__/material-stride-surface.unit.test.ts

@@ -4,7 +4,7 @@ import { MATERIAL_PER_ENTITY_STRIDE } from '../render-system';
 
 const ownerSource = readFileSync(new URL('../record/render-context.ts', import.meta.url), 'utf8');
 const rendererFactorySource = readFileSync(
-  new URL('../assembly/factory.ts', import.meta.url),
+  new URL('../assembly/webgpu-ready.ts', import.meta.url),
   'utf8',
 );
 const recordSources = [
@@ -16,8 +16,12 @@ const recordSources = [
 
 describe('material dynamic-offset stride surface', () => {
   it('keeps one internal owner and routes every record path through it', () => {
-    expect(MATERIAL_PER_ENTITY_STRIDE).toBe(512);
-    expect(ownerSource.match(/export const MATERIAL_PER_ENTITY_STRIDE\s*=\s*512/g)).toHaveLength(1);
+    expect(MATERIAL_PER_ENTITY_STRIDE).toBe(768);
+    expect(
+      ownerSource.match(
+        /export const MATERIAL_PER_ENTITY_STRIDE\s*=\s*Math\.ceil\(STANDARD_PBR_UBO_SIZE \/ 256\) \* 256/g,
+      ),
+    ).toHaveLength(1);
 
     for (const source of recordSources) {
       expect(source).toContain('MATERIAL_PER_ENTITY_STRIDE');

package/src/__tests__/materials-standard-contract.unit.test.ts

@@ -0,0 +1,104 @@
+import type { Buffer, Sampler, TextureView } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import { assembleMaterialWithSkylightEntries } from '../ibl/skylight-bind-group.js';
+import { Materials } from '../materials.js';
+
+describe('Materials.standard clearcoat public contract', () => {
+  it('declares clearcoat only when the physical root is authored', () => {
+    const base = Materials.standard({ baseColor: [1, 1, 1, 1] });
+    const zero = Materials.standard({ baseColor: [1, 1, 1, 1], clearcoat: 0 });
+    expect(base.parameters?.map((parameter) => parameter.name)).not.toContain('clearcoat');
+    expect(zero.parameters?.map((parameter) => parameter.name)).toContain('clearcoat');
+    expect(zero.passes?.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+  });
+
+  it('uses the R, G, and RG channel matrix without a guessed UV set', () => {
+    const options = {
+      baseColor: [1, 1, 1, 1] as const,
+      clearcoat: 0.5,
+      clearcoatRoughness: 0.25,
+      clearcoatTexture: 1,
+      clearcoatRoughnessTexture: 2,
+      clearcoatNormalTexture: 3,
+      clearcoatNormalScale: 0.75,
+    } as Parameters<typeof Materials.standard>[0] & Record<string, unknown>;
+    const material = Materials.standard(options);
+    expect(material.values).toMatchObject(options);
+    expect(material.values).not.toHaveProperty('clearcoatTexCoord');
+  });
+
+  it('keeps scalar clearcoat identity without charging unauthored map slots', () => {
+    const scalar = Materials.standard({
+      baseColor: [1, 1, 1, 1],
+      clearcoat: 0,
+      clearcoatRoughness: 0.5,
+      clearcoatNormalScale: 1,
+    });
+    const names = scalar.parameters?.map((parameter) => parameter.name) ?? [];
+    expect(names).toEqual(expect.arrayContaining(['clearcoat', 'clearcoatRoughness']));
+    expect(names).not.toEqual(
+      expect.arrayContaining([
+        'clearcoatTexture',
+        'clearcoatRoughnessTexture',
+        'clearcoatNormalTexture',
+      ]),
+    );
+  });
+
+  it('declares each clearcoat map slot only when its root value is authored', () => {
+    const material = Materials.standard({
+      baseColor: [1, 1, 1, 1],
+      clearcoat: 1,
+      clearcoatTexture: 1,
+      clearcoatNormalTexture: 2,
+    });
+    const names = material.parameters?.map((parameter) => parameter.name) ?? [];
+    expect(names).toEqual(expect.arrayContaining(['clearcoatTexture', 'clearcoatNormalTexture']));
+    expect(names).not.toContain('clearcoatRoughnessTexture');
+  });
+
+  it('keeps physical scalar fields before texture coordinate records', () => {
+    const material = Materials.standard({
+      baseColor: [1, 1, 1, 1],
+      clearcoat: 0.5,
+      clearcoatRoughness: 0.25,
+      clearcoatTexture: 1,
+    });
+    const names = material.parameters?.map((parameter) => parameter.name) ?? [];
+    expect(names.indexOf('clearcoat')).toBeLessThan(names.indexOf('baseColorTexture'));
+    expect(names.indexOf('clearcoatRoughness')).toBeLessThan(names.indexOf('baseColorTexture'));
+  });
+
+  it('keeps authored clearcoat map pairs contiguous after the material ABI', () => {
+    const sampler = {} as Sampler;
+    const view = {} as TextureView;
+    const entries = Array.from({ length: 17 }, (_, binding) => ({
+      binding,
+      resource:
+        binding === 0
+          ? { kind: 'buffer' as const, value: { buffer: {} as Buffer } }
+          : binding % 2 === 1
+            ? { kind: 'sampler' as const, value: sampler }
+            : { kind: 'textureView' as const, value: view },
+    }));
+    const merged = assembleMaterialWithSkylightEntries(
+      entries,
+      {
+        irradianceView: view,
+        irradianceSampler: sampler,
+        prefilterView: view,
+        prefilterSampler: sampler,
+        brdfLutView: view,
+        brdfLutSampler: sampler,
+        intensityBuffer: {} as Buffer,
+      },
+      undefined,
+      [
+        { slot: 0, sampler, view },
+        { slot: 1, sampler, view },
+        { slot: 2, sampler, view },
+      ],
+    );
+    expect(merged.slice(-6).map((entry) => entry.binding)).toEqual([26, 27, 28, 29, 30, 31]);
+  });
+});

package/src/__tests__/mesh-buffer-usage-surface.unit.test.ts

@@ -14,7 +14,7 @@ import {
 const ownerSource = readFileSync(new URL('../gpu-usage.ts', import.meta.url), 'utf8');
 const meshSsboSource = readFileSync(new URL('../record/mesh-ssbo.ts', import.meta.url), 'utf8');
 const rendererFactorySource = readFileSync(
-  new URL('../assembly/factory.ts', import.meta.url),
+  new URL('../assembly/webgpu-ready.ts', import.meta.url),
   'utf8',
 );
 const consumerSources = [

package/src/__tests__/occlusion-confidence.unit.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from 'vitest';
+import { createVisibilityBudget } from '../scene/visibility/budget';
+import {
+  applyConfidenceEvent,
+  createConfidenceState,
+  OcclusionConfidenceScheduler,
+  shouldIssueRetest,
+} from '../scene/visibility/occlusion-confidence';
+
+describe('occlusion confidence FSM', () => {
+  it('shows positive results immediately and suppresses only after two zeros', () => {
+    const initial = createConfidenceState();
+    const positive = applyConfidenceEvent(initial, {
+      type: 'result',
+      samples: 4,
+      submissionGeneration: 1,
+    });
+    expect(positive.status).toBe('visible');
+    const firstZero = applyConfidenceEvent(positive, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 2,
+    });
+    expect(firstZero.status).toBe('visible');
+    const secondZero = applyConfidenceEvent(firstZero, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 3,
+    });
+    expect(secondZero.status).toBe('hidden');
+  });
+
+  it('retests within six successful submits and expires to visible by eight', () => {
+    const budget = createVisibilityBudget();
+    let state = applyConfidenceEvent(createConfidenceState(), {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 1,
+    });
+    state = applyConfidenceEvent(state, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 2,
+    });
+    expect(state.status).toBe('hidden');
+    for (let generation = 3; generation <= 2 + budget.retestSubmits; generation += 1) {
+      state = applyConfidenceEvent(
+        state,
+        { type: 'submit', submissionGeneration: generation },
+        budget,
+      );
+    }
+    expect(shouldIssueRetest(state, budget)).toBe(true);
+    expect(state.status).toBe('hidden');
+    for (
+      let generation = 3 + budget.retestSubmits;
+      generation <= 2 + budget.expirySubmits;
+      generation += 1
+    ) {
+      state = applyConfidenceEvent(
+        state,
+        { type: 'submit', submissionGeneration: generation },
+        budget,
+      );
+    }
+    expect(state.status).toBe('visible');
+    expect(shouldIssueRetest(state, budget)).toBe(false);
+  });
+
+  it('keeps failures and invalidations visible and clears only the facet state', () => {
+    const hidden = applyConfidenceEvent(
+      applyConfidenceEvent(createConfidenceState(), {
+        type: 'result',
+        samples: 0,
+        submissionGeneration: 1,
+      }),
+      { type: 'result', samples: 0, submissionGeneration: 2 },
+    );
+    const failed = applyConfidenceEvent(hidden, {
+      type: 'failure',
+      submissionGeneration: 3,
+    });
+    expect(failed).toMatchObject({ status: 'visible', queryable: true });
+    const invalidated = applyConfidenceEvent(hidden, { type: 'invalidate', reason: 'teleport' });
+    expect(invalidated).toMatchObject({ status: 'visible', zeroStreak: 0, queryable: true });
+  });
+
+  it('does not query transparent or detached facets', () => {
+    expect(
+      applyConfidenceEvent(createConfidenceState(), { type: 'invalidate', reason: 'transparent' }),
+    ).toMatchObject({ queryable: false, status: 'visible' });
+    expect(
+      applyConfidenceEvent(createConfidenceState(), { type: 'invalidate', reason: 'detach' }),
+    ).toMatchObject({ queryable: false, status: 'visible' });
+  });
+
+  it('consumes overdue wake/expiry buckets without scanning unrelated generations', () => {
+    const budget = createVisibilityBudget();
+    const scheduler = new OcclusionConfidenceScheduler(budget);
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 1 });
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 2 });
+    scheduler.apply('other', { type: 'result', samples: 0, submissionGeneration: 99 });
+    scheduler.apply('other', { type: 'result', samples: 0, submissionGeneration: 100 });
+
+    scheduler.advanceSuccessfulSubmits(100);
+    expect(scheduler.get('hidden')).toMatchObject({ status: 'visible', dirty: true });
+    expect(scheduler.get('other')).toMatchObject({ status: 'hidden', successfulSubmits: 0 });
+  });
+
+  it('reschedules an excluded due wake without retaining its old expiry bucket', () => {
+    const budget = createVisibilityBudget();
+    const scheduler = new OcclusionConfidenceScheduler(budget);
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 1 });
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 2 });
+
+    scheduler.advanceSuccessfulSubmits(2 + budget.retestSubmits, new Set(['hidden']));
+    scheduler.advanceSuccessfulSubmits(2 + budget.retestSubmits + 2);
+    expect(scheduler.get('hidden')).toMatchObject({ status: 'hidden', successfulSubmits: 0 });
+
+    scheduler.advanceSuccessfulSubmits(2 + budget.retestSubmits + budget.expirySubmits);
+    expect(scheduler.get('hidden')).toMatchObject({ status: 'visible', dirty: true });
+  });
+
+  it('keeps a same-generation excluded reschedule reachable after an empty bucket', () => {
+    const budget = createVisibilityBudget();
+    const scheduler = new OcclusionConfidenceScheduler(budget);
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 1 });
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 2 });
+    for (let generation = 3; generation <= 2 + budget.retestSubmits; generation += 1) {
+      scheduler.apply('hidden', { type: 'submit', submissionGeneration: generation });
+    }
+
+    const retestGeneration = 2 + budget.retestSubmits;
+    scheduler.advanceSuccessfulSubmits(retestGeneration, new Set(['hidden']));
+    // Repeating the same generation used to leave the newly-created bucket
+    // only in the map: unschedule removed its key but the heap membership bit
+    // prevented addDue from pushing a reachable heap entry.
+    scheduler.advanceSuccessfulSubmits(retestGeneration, new Set(['hidden']));
+    // The requeued wake at generation 8 must remain reachable. Consuming it
+    // here recreates the expiry at generation 10; without the heap repair the
+    // old expiry was removed and this later recovery never happens.
+    scheduler.advanceSuccessfulSubmits(retestGeneration);
+    scheduler.advanceSuccessfulSubmits(
+      retestGeneration + budget.expirySubmits - budget.retestSubmits,
+    );
+    expect(scheduler.get('hidden')).toMatchObject({ status: 'visible', dirty: true });
+  });
+
+  it('advances a due hidden row queried in the same generation exactly once', () => {
+    const budget = createVisibilityBudget();
+    const scheduler = new OcclusionConfidenceScheduler(budget);
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 1 });
+    scheduler.apply('hidden', { type: 'result', samples: 0, submissionGeneration: 2 });
+    const dueGeneration = 2 + budget.retestSubmits;
+
+    scheduler.advanceSuccessfulSubmits(dueGeneration);
+    expect(scheduler.get('hidden')).toMatchObject({
+      status: 'hidden',
+      successfulSubmits: budget.retestSubmits,
+    });
+    scheduler.apply('hidden', { type: 'submit', submissionGeneration: dueGeneration });
+    scheduler.advanceSuccessfulSubmits(dueGeneration);
+    expect(scheduler.get('hidden')).toMatchObject({
+      status: 'hidden',
+      successfulSubmits: budget.retestSubmits + 1,
+    });
+  });
+});

package/src/__tests__/occlusion-invalidation.integration.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import {
+  applyConfidenceEvent,
+  createConfidenceState,
+  type InvalidationReason,
+} from '../scene/visibility/occlusion-confidence';
+
+describe('occlusion confidence invalidation matrix', () => {
+  it.each([
+    'cut',
+    'teleport',
+    'resize',
+    'projection',
+    'primitive',
+    'bounds',
+    'topology',
+    'world-reorder',
+    'detach',
+    'failed-submit',
+    'device-loss',
+  ] satisfies readonly InvalidationReason[])('invalidates %s without suppressing the facet', (reason) => {
+    const state = applyConfidenceEvent(
+      applyConfidenceEvent(createConfidenceState(), {
+        type: 'result',
+        samples: 0,
+        submissionGeneration: 1,
+      }),
+      { type: 'result', samples: 0, submissionGeneration: 2 },
+    );
+    const next = applyConfidenceEvent(state, { type: 'invalidate', reason });
+    expect(next).toMatchObject({
+      status: 'visible',
+      zeroStreak: 0,
+      queryable: reason !== 'detach',
+    });
+  });
+});

package/src/__tests__/occlusion-pass-routing.unit.test.ts

@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const typedPrimitivesSource = readFileSync(
+  new URL('../typed-render-graph-primitives.ts', import.meta.url),
+  'utf8',
+);
+
+describe('typed scene occlusion pass routing', () => {
+  it('only forwards a projection to the pass that owns its query set', () => {
+    expect(typedPrimitivesSource).toContain('const activeOcclusion = options.occlusion;');
+    expect(typedPrimitivesSource).not.toContain(
+      '...(internal.occlusion === undefined ? {} : { occlusion: internal.occlusion })',
+    );
+  });
+});

package/src/__tests__/occlusion-pass.dawn.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { buildOcclusionPassPlan } from '../scene/visibility/occlusion-pass';
+
+describe('occlusion pass Dawn contract', () => {
+  it('keeps resolve, copy, and async map in one shared submission plan', () => {
+    const plan = buildOcclusionPassPlan({
+      opaquePass: 'opaque',
+      depthResource: 'depth',
+      colorResource: 'color',
+      bounds: { min: [-1, -1, -1], max: [1, 1, 1] },
+      queryIndex: 0,
+    });
+    expect(plan).toMatchObject({
+      resolve: { queryIndex: 0 },
+      copy: { asynchronous: true },
+      submitCount: 1,
+      mapSameFrame: false,
+    });
+  });
+});

package/src/__tests__/occlusion-pass.integration.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { buildOcclusionPassPlan } from '../scene/visibility/occlusion-pass';
+
+const bounds = { min: [-1, -1, -1] as const, max: [1, 1, 1] as const };
+
+describe('typed occlusion bounds pass', () => {
+  it('is ordered after opaque and only reads depth through a conservative proxy', () => {
+    expect(
+      buildOcclusionPassPlan({
+        opaquePass: 'opaque-main',
+        depthResource: 'depth-main',
+        colorResource: 'color-main',
+        bounds,
+        queryIndex: 3,
+      }),
+    ).toMatchObject({
+      after: 'opaque-main',
+      queryIndex: 3,
+      depth: { resource: 'depth-main', usage: 'depth-read-only' },
+      writesColor: false,
+      writesDepth: false,
+      submitCount: 1,
+    });
+  });
+
+  it.each([
+    { transparent: true },
+    { deformed: true },
+    { bounds: undefined },
+  ])('keeps non-queryable candidates visible: %o', (input) => {
+    expect(
+      buildOcclusionPassPlan({
+        opaquePass: 'opaque-main',
+        depthResource: 'depth-main',
+        colorResource: 'color-main',
+        bounds: input.bounds === undefined ? undefined : bounds,
+        queryIndex: 0,
+        ...(input.transparent === undefined ? {} : { transparent: input.transparent }),
+        ...(input.deformed === undefined ? {} : { deformed: input.deformed }),
+      }),
+    ).toBeUndefined();
+  });
+});

package/src/__tests__/occlusion-pass.rhi-null.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { buildOcclusionPassPlan } from '../scene/visibility/occlusion-pass';
+
+describe('occlusion pass RhiNull structural contract', () => {
+  it('does not create color/depth writes and keeps query index separate from identity', () => {
+    const plan = buildOcclusionPassPlan({
+      opaquePass: 'opaque',
+      depthResource: 'depth',
+      colorResource: 'color',
+      bounds: { min: [-2, -2, -2], max: [2, 2, 2] },
+      queryIndex: 17,
+      identity: { primitiveSlot: 4, slotGeneration: 9 },
+    });
+    expect(plan).toMatchObject({
+      queryIndex: 17,
+      identity: { primitiveSlot: 4, slotGeneration: 9 },
+      writesColor: false,
+      writesDepth: false,
+    });
+    expect(plan?.depth.usage).toBe('depth-read-only');
+  });
+});

package/src/__tests__/occlusion-query-pool.rhi-null.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { OcclusionQueryPool } from '../scene/visibility/occlusion-query-pool';
+
+describe('occlusion query RhiNull structure', () => {
+  it('disposes pages and reuses them without exposing query identity', () => {
+    const pool = new OcclusionQueryPool();
+    expect(pool.inspect().disposed).toBe(false);
+    pool.dispose();
+    expect(pool.inspect()).toMatchObject({ disposed: true, inFlight: 0, availablePages: 0 });
+    expect(
+      pool.reserve({
+        viewKey: 'view',
+        attachmentId: 'attachment',
+        deviceGeneration: 1,
+        worldGeneration: 1,
+        primitiveSlot: 0,
+        slotGeneration: 1,
+      }),
+    ).toBeUndefined();
+  });
+});