@forgeax/engine-render 0.1.21 → 0.1.24

package/src/__tests__/ssr-composition.unit.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { composeSsrReflection } from '../ssr/composition';
+
+const baseSpecular = [0.2, 0.3, 0.4] as const;
+const screenSpecular = [0.8, 0.7, 0.9] as const;
+const fallbackSpecular = [0.1, 0.2, 0.3] as const;
+
+describe('SSR M0 reflection composition', () => {
+  it('keeps the base specular lobe when c=0', () => {
+    const composed = composeSsrReflection({
+      c: 0,
+      baseSpecular,
+      screenSpecular,
+      fallbackSpecular,
+    });
+    expect(composed).toMatchObject({ ok: true, value: baseSpecular });
+  });
+
+  it('replaces only the same-source lobe when c=1', () => {
+    const composed = composeSsrReflection({
+      c: 1,
+      baseSpecular,
+      screenSpecular,
+      fallbackSpecular,
+    });
+    expect(composed.ok).toBe(true);
+    if (composed.ok) {
+      expect(composed.value[0]).toBeCloseTo(0.9, 12);
+      expect(composed.value[1]).toBeCloseTo(0.8, 12);
+      expect(composed.value[2]).toBeCloseTo(1, 12);
+    }
+  });
+
+  it('rejects an unbounded confidence instead of clamping an invalid contract', () => {
+    const composed = composeSsrReflection({
+      c: 1.01,
+      baseSpecular,
+      screenSpecular,
+      fallbackSpecular,
+    });
+    expect(composed).toMatchObject({
+      ok: false,
+      error: { code: 'ssr-composition-input-invalid', detail: { field: 'c' } },
+    });
+  });
+});

package/src/__tests__/ssr-fallback-zero-work.bench.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+import {
+  admitSsrM0,
+  SSR_FORMAT_STAGES,
+  type SsrAdmissionIdentity,
+  type SsrFormatReceipt,
+  type SsrReflectionFallbackReceipt,
+} from '../ssr/admission';
+
+const identity: SsrAdmissionIdentity = {
+  sourceHead: 'head',
+  sourceTree: 'tree',
+  lockSha256: 'lock',
+  buildSha256: 'build',
+};
+
+const unavailable = () => admitSsrM0({ requested: true, identity });
+
+describe('SSR fallback zero-work budget', () => {
+  it('keeps unavailable and unrequested paths at exact zero work', () => {
+    for (const result of [admitSsrM0({ requested: false, identity }), unavailable()]) {
+      expect(result.status).toBe('fallback-only');
+      expect(result.work).toEqual({
+        attachmentCount: 0,
+        passCount: 0,
+        bindingCount: 0,
+        resourceCount: 0,
+        historyCount: 0,
+        temporalDemand: 0,
+      });
+      expect(result.budget).toEqual({
+        probeExecutions: 0,
+        resetCount: 0,
+        rebuildCount: 0,
+      });
+    }
+  });
+
+  it('keeps an unchanged admitted generation stable without reset or rebuild', () => {
+    const fallback = {
+      identity,
+      source: 'probe' as const,
+      sourceGeneration: 4,
+      projectionGeneration: 4,
+      deviceGeneration: 2,
+      state: 'active' as const,
+      candidateVisible: false as const,
+      coverage: 1,
+      brdfSignature: 'standard-pbr-ibl-v1',
+    } satisfies SsrReflectionFallbackReceipt;
+    const format = {
+      identity,
+      profile: 'r32float-mip-sampled-storage' as const,
+      verdict: 'admitted' as const,
+      evidence: 'real' as const,
+      stages: SSR_FORMAT_STAGES.map((stage) => ({
+        stage,
+        verdict: 'admitted' as const,
+        evidence: 'real' as const,
+      })),
+      deviceGeneration: 2,
+      sampleType: 'unfilterable-float' as const,
+      usages: ['texture-binding', 'storage-binding', 'copy-src'] as const,
+      readback: { byteLength: 4, values: [1] },
+      probeExecutions: 1,
+    } satisfies SsrFormatReceipt;
+    const temporal = { identity, successfulSubmit: true as const, generation: 4 };
+    const first = admitSsrM0({
+      requested: true,
+      identity,
+      reflectionFallback: fallback,
+      format,
+      temporal,
+    });
+    const stable = admitSsrM0({
+      requested: true,
+      identity,
+      previousGeneration: first.generation,
+      reflectionFallback: fallback,
+      format,
+      temporal,
+    });
+    expect(first.status).toBe('admitted');
+    expect(stable).toEqual(first);
+    expect(stable.budget).toEqual({ probeExecutions: 1, resetCount: 0, rebuildCount: 0 });
+  });
+});
+
+it('keeps unavailable admission detached and bounded', () => {
+  const result = unavailable();
+  if (result.status !== 'fallback-only' || result.work.temporalDemand !== 0) {
+    throw new Error('unavailable admission performed SSR work');
+  }
+});

package/src/__tests__/ssr-recovery-errors.unit.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { ssrAdmissionRecoveryAction } from '../errors/recover';
+import { createSsrAdmissionError, type SsrAdmissionErrorCode } from '../ssr/errors';
+
+const codes = [
+  'ssr-not-requested',
+  'ssr-reflection-fallback-unavailable',
+  'ssr-format-unavailable',
+  'ssr-temporal-unavailable',
+  'ssr-receipt-identity-mismatch',
+  'ssr-receipt-stale',
+] as const satisfies readonly SsrAdmissionErrorCode[];
+
+describe('SSR admission recovery contract', () => {
+  it('keeps every failure closed and maps only to owner actions', () => {
+    const errors = [
+      createSsrAdmissionError({ code: 'ssr-not-requested', owner: 'consumer', action: 'retry' }),
+      createSsrAdmissionError({
+        code: 'ssr-reflection-fallback-unavailable',
+        owner: 'producer',
+        action: 'use-LKG',
+      }),
+      createSsrAdmissionError({
+        code: 'ssr-format-unavailable',
+        owner: 'format',
+        action: 'retry',
+        stage: 'readback',
+      }),
+      createSsrAdmissionError({
+        code: 'ssr-temporal-unavailable',
+        owner: 'temporal',
+        action: 'rebuild',
+      }),
+      createSsrAdmissionError({
+        code: 'ssr-receipt-identity-mismatch',
+        owner: 'format',
+        action: 'rebuild',
+        identityField: 'buildSha256',
+      }),
+      createSsrAdmissionError({
+        code: 'ssr-receipt-stale',
+        owner: 'consumer',
+        action: 'retry',
+        generation: 7,
+      }),
+    ];
+    expect(errors.map((error) => error.code)).toEqual(codes);
+    expect(errors.map(ssrAdmissionRecoveryAction)).toEqual([
+      'retry',
+      'use-LKG',
+      'retry',
+      'rebuild',
+      'rebuild',
+      'retry',
+    ]);
+    expect(errors.every((error) => !('handle' in error))).toBe(true);
+  });
+});

package/src/__tests__/standard-cluster-variant-resolution.unit.test.ts

@@ -71,6 +71,24 @@ describe('Standard clustered variant resolution', () => {
     );
   });
 
+  it('expands the clustered base before requesting the object-level probe ABI', () => {
+    const noLocalForward = { kind: 'no-local-lights' as const };
+    const clusteredForward = { kind: 'clustered' as const };
+
+    expect(standardTopologyVariantSet(noLocalForward, true, false, true)).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+PROBE_BLEND_AVAILABLE=true',
+    );
+    expect(standardTopologyVariantSet(clusteredForward, true, false, true)).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+PROBE_BLEND_AVAILABLE=true',
+    );
+    expect(standardTopologyVariantSet(clusteredForward, true, true, true)).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+PROBE_BLEND_AVAILABLE=true',
+    );
+    expect(standardTopologyVariantSet(clusteredForward, false, false, true)).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=false',
+    );
+  });
+
   it('fails closed when a clustered frame is missing its unified group', () => {
     expect(standardTopologyBindGroupReady({ kind: 'no-local-lights' }, null)).toBe(true);
     expect(standardTopologyBindGroupReady({ kind: 'clustered' }, {})).toBe(true);
@@ -169,6 +187,55 @@ describe('Standard clustered variant resolution', () => {
     ).toBe(noColorVariants[1]);
   });
 
+  it('keeps fallback PBR layout selection aligned with the requested probe ABI', () => {
+    const noProbeUrp = {
+      defines: {
+        CLUSTER_FORWARD_AVAILABLE: false,
+        PROBE_BLEND_AVAILABLE: false,
+        STORAGE_BUFFER_AVAILABLE: true,
+        VERTEX_COLOR_AVAILABLE: false,
+      },
+      composedWgsl: 'no-probe-urp',
+    };
+    const probeUrp = {
+      defines: {
+        CLUSTER_FORWARD_AVAILABLE: false,
+        PROBE_BLEND_AVAILABLE: true,
+        STORAGE_BUFFER_AVAILABLE: true,
+        VERTEX_COLOR_AVAILABLE: false,
+      },
+      composedWgsl: 'probe-urp',
+    };
+    const noProbeHdrp = {
+      defines: {
+        CLUSTER_FORWARD_AVAILABLE: true,
+        PROBE_BLEND_AVAILABLE: false,
+        STORAGE_BUFFER_AVAILABLE: true,
+        VERTEX_COLOR_AVAILABLE: false,
+      },
+      composedWgsl: 'no-probe-hdrp',
+    };
+    const probeHdrp = {
+      defines: {
+        CLUSTER_FORWARD_AVAILABLE: true,
+        PROBE_BLEND_AVAILABLE: true,
+        STORAGE_BUFFER_AVAILABLE: true,
+        VERTEX_COLOR_AVAILABLE: false,
+      },
+      composedWgsl: 'probe-hdrp',
+    };
+    const manifest = { variants: [probeUrp, noProbeUrp, probeHdrp, noProbeHdrp] } as never;
+
+    expect(selectNoColorPbrVariant(manifest, true, undefined)).toBe(noProbeUrp);
+    expect(
+      selectNoColorPbrVariant(
+        manifest,
+        true,
+        'CLUSTER_FORWARD_AVAILABLE=true+PROBE_BLEND_AVAILABLE=true',
+      ),
+    ).toBe(probeHdrp);
+  });
+
   it('rebuilds membership in write after a device and layout generation change', async () => {
     const adapter = new RhiNullAdapter();
     const deviceAResult = await adapter.requestDevice();

package/src/__tests__/standard-clustered-pipeline.unit.test.ts

@@ -14,6 +14,7 @@ const forwardSource = readFileSync(
   new URL('../pipeline/standard-forward-lane.ts', import.meta.url),
   'utf8',
 );
+const recordSource = readFileSync(new URL('../record/frame.ts', import.meta.url), 'utf8');
 
 describe('Standard clustered post color-domain order', () => {
   it('keeps transparent and bloom work in linear HDR before tone output', () => {
@@ -49,4 +50,10 @@ describe('Standard clustered post color-domain order', () => {
     expect(clusteredSource).toContain('shadows.value.spot,');
     expect(clusterGraphSource).toContain("'hdrp-light-index-list'");
   });
+
+  it('routes clustered direct-light recording through the Spot modifier uploader', () => {
+    expect(recordSource).toContain(
+      'writeSpotModifierTextures(internals, pipelineState, lights.spot);',
+    );
+  });
 });

package/src/__tests__/standard-layer-projection.unit.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { Materials } from '../materials.js';
+
+describe('Standard pass projection', () => {
+  it('keeps default and custom base surfaces on the base pass family', () => {
+    const material = Materials.standard({ baseColor: [1, 1, 1, 1] });
+    expect(material.passes?.map((pass) => pass.name)).toEqual([
+      'forward',
+      'deferred',
+      'shadow-caster',
+    ]);
+  });
+
+  it('uses the same physical forward-only projection for a zero-factor declaration', () => {
+    const material = Materials.standard({
+      baseColor: [1, 1, 1, 1],
+      clearcoat: 0,
+      clearcoatRoughness: 0,
+    });
+    expect(material.passes?.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+    expect(material.parameters?.some((parameter) => parameter.name === 'clearcoat')).toBe(true);
+  });
+});

package/src/__tests__/standard-lighting-inspection.integration.test.ts

@@ -54,7 +54,7 @@ describe('Standard lighting inspection provenance', () => {
       occupied: selected.value.occupiedClusterCount,
       clusterGridBytes: preparedFrame.layout.clusterGridU32Length * 4,
       lightIndexListBytes: preparedFrame.membershipEntryCount * 4,
-      lightDataBytes: 33 * 64,
+      lightDataBytes: 33 * 80,
       lightBoundsBytes: preparedFrame.lightBounds.byteLength,
       grid: preparedFrame.layout.grid,
     });

package/src/__tests__/standard-lighting-write.unit.test.ts

@@ -9,9 +9,16 @@ import {
 } from '../hdrp-buffers';
 import { prepareStandardLighting } from '../pipeline/standard-lighting/prepare';
 import { selectStandardClusterTransport } from '../pipeline/standard-lighting/transport';
-import { writeHdrpClusterAndSsaoBuffers } from '../record/frame-lighting';
+import {
+  writeHdrpClusterAndSsaoBuffers,
+  writeSpotModifierTextures,
+} from '../record/frame-lighting';
 import type { RenderFrameState } from '../record/frame-snapshot';
-import type { RenderSystemInternals, RenderSystemRuntime } from '../record/render-context';
+import type {
+  PipelineState,
+  RenderSystemInternals,
+  RenderSystemRuntime,
+} from '../record/render-context';
 import type { CameraSnapshot } from '../render-contract';
 
 function camera(): CameraSnapshot {
@@ -81,6 +88,63 @@ function internalsWithFirstWriteFailure() {
 }
 
 describe('Standard Cluster upload ownership', () => {
+  it('uploads authored Spot modifiers and caches the content identity', () => {
+    const cookieTexture = { label: 'fallback-cookie-array' };
+    const cookieMatrixBuffer = { label: 'fallback-cookie-matrices' };
+    const textureWrites: unknown[] = [];
+    const bufferWrites: unknown[] = [];
+    const cookieData = new Uint8Array(256 * 256 * 4);
+    cookieData[0] = 0x12;
+    const cookieMatrix = new Float32Array(16);
+    cookieMatrix[0] = 0.7;
+    cookieMatrix[5] = 1;
+    cookieMatrix[10] = 1;
+    cookieMatrix[15] = 1;
+    const internals = {
+      device: {
+        queue: {
+          writeTexture(destination: unknown, data: Uint8Array) {
+            textureWrites.push({ destination, data });
+            return rhiOk(undefined);
+          },
+          writeBuffer(destination: unknown, offset: number, data: Float32Array) {
+            bufferWrites.push({ destination, offset, data });
+            return rhiOk(undefined);
+          },
+        },
+      },
+    } as unknown as RenderSystemInternals;
+    const pipelineState = {
+      iesProfileTexture: undefined,
+      cookieTexture,
+      cookieMatrixBuffer,
+      spotModifierUploadState: undefined,
+    } as unknown as PipelineState;
+    const spot = {
+      kind: 'spot' as const,
+      cookieSlice: 0,
+      cookieData,
+      cookieMatrix,
+    } as never;
+
+    writeSpotModifierTextures(internals, pipelineState, [spot]);
+    writeSpotModifierTextures(internals, pipelineState, [spot]);
+
+    expect(textureWrites).toHaveLength(1);
+    expect(bufferWrites).toHaveLength(1);
+    expect(textureWrites[0]).toMatchObject({
+      destination: { origin: { x: 0, y: 0, z: 0 } },
+      data: cookieData,
+    });
+    expect(bufferWrites[0]).toMatchObject({
+      destination: cookieMatrixBuffer,
+      offset: 0,
+      data: cookieMatrix,
+    });
+    expect(pipelineState.spotModifierUploadState?.cookie.has(0)).toBe(true);
+    expect(pipelineState.spotModifierUploadState?.cookieMatrix.has(0)).toBe(true);
+  });
+
   it('returns device-operation-failed instead of publishing after a required upload fails', () => {
     const source = {
       kind: 'point' as const,

package/src/__tests__/temporal-fallback-generation.integration.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { resolveReflectionFallbackTemporalReset } from '../temporal/frame-coordinator';
+
+describe('fallback generation temporal boundary', () => {
+  it('resets only when a committed semantic generation changes', () => {
+    expect(resolveReflectionFallbackTemporalReset(4, 4)).toEqual({ reset: false });
+    expect(resolveReflectionFallbackTemporalReset(4, 5)).toEqual({
+      reset: true,
+      reason: 'reflection-fallback-generation',
+    });
+  });
+
+  it('does not create a temporal demand for an unavailable projection', () => {
+    expect(resolveReflectionFallbackTemporalReset(undefined, 4)).toEqual({ reset: false });
+  });
+});

package/src/__tests__/temporal-view.unit.test.ts

@@ -132,7 +132,7 @@ describe('TemporalView v1', () => {
     } as unknown as ExtractedLights;
     const buffer = {} as Parameters<typeof writeViewUbo>[1];
     const first = createTemporalView({ antialias: 'taa', width: 4, height: 4, frameIndex: 0 });
-    writeViewUbo(queue, buffer, camera, light, lights, [], undefined, first);
+    writeViewUbo(queue, buffer, camera, light, lights, [], first);
     expect(Array.from(uploads[0]?.slice(212, 228) ?? [])).toEqual(new Array(16).fill(0));
 
     const previous = Float32Array.from({ length: 16 }, (_value, index) => index + 1);
@@ -143,10 +143,10 @@ describe('TemporalView v1', () => {
       frameIndex: 1,
       previousUnjitteredViewProjection: previous,
     });
-    writeViewUbo(queue, buffer, camera, light, lights, [], undefined, second);
+    writeViewUbo(queue, buffer, camera, light, lights, [], second);
     expect(Array.from(uploads[1]?.slice(212, 228) ?? [])).toEqual(Array.from(previous));
 
-    writeViewUbo(queue, buffer, camera, light, lights, [], undefined, second);
+    writeViewUbo(queue, buffer, camera, light, lights, [], second);
     expect(Array.from(uploads[2]?.slice(212, 228) ?? [])).toEqual(Array.from(previous));
   });
 });

package/src/__tests__/transmission-prewarm.unit.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import {
   type MaterialShaderManifestEntry,
   selectHdrpPbrPrewarmVariants,
+  selectProbePrewarmVariants,
   selectStandardPbrTransmissionPrewarmVariants,
 } from '../assembly/factory.js';
 
@@ -9,10 +10,10 @@ const falseKey =
   'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=false';
 const trueKey =
   'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false';
-const hdrpFalseKey =
-  'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=false';
-const hdrpTrueKey =
-  'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false';
+const probeFalseKey =
+  'CLUSTER_FORWARD_AVAILABLE=false+PROBE_BLEND_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=false';
+const probeTrueKey =
+  'CLUSTER_FORWARD_AVAILABLE=false+PROBE_BLEND_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false';
 
 function standardEntry(
   variants: readonly MaterialShaderManifestEntry['variants'][number][],
@@ -26,6 +27,23 @@ function standardEntry(
   };
 }
 
+function variant(cluster: boolean, storage: boolean, projector?: boolean) {
+  const defines = {
+    CLUSTER_FORWARD_AVAILABLE: cluster,
+    STORAGE_BUFFER_AVAILABLE: storage,
+    VERTEX_COLOR_AVAILABLE: false,
+    ...(projector === undefined ? {} : { PROJECTOR_AVAILABLE: projector }),
+  };
+  return {
+    definesKey: Object.entries(defines)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([name, value]) => `${name}=${value}`)
+      .join('+'),
+    defines,
+    composedWgsl: JSON.stringify(defines),
+  };
+}
+
 function transmissionVariant(definesKey: string, transmission: boolean) {
   return {
     definesKey,
@@ -39,55 +57,116 @@ function transmissionVariant(definesKey: string, transmission: boolean) {
   };
 }
 
-function hdrpVariant(definesKey: string, transmission: boolean) {
+function probeTransmissionVariant(definesKey: string, transmission: boolean) {
+  const base = transmissionVariant(definesKey, transmission);
   return {
-    definesKey,
-    defines: {
-      CLUSTER_FORWARD_AVAILABLE: true,
-      STORAGE_BUFFER_AVAILABLE: true,
-      TRANSMISSION_AVAILABLE: transmission,
-      VERTEX_COLOR_AVAILABLE: false,
-    },
-    composedWgsl: `hdrp-${transmission}`,
+    ...base,
+    defines: { ...base.defines, PROBE_BLEND_AVAILABLE: true },
   };
 }
 
 describe('Standard transmission exact-key prewarm selection', () => {
-  it('returns both declared variants through exact manifest lookup', () => {
+  it('returns both declared transmission variants', () => {
     const entry = standardEntry([
       transmissionVariant(falseKey, false),
       transmissionVariant(trueKey, true),
     ]);
-    const selected = selectStandardPbrTransmissionPrewarmVariants(entry, true);
-    expect(selected.map((variant) => variant.definesKey)).toEqual([falseKey, trueKey]);
+    expect(
+      selectStandardPbrTransmissionPrewarmVariants(entry, true).map((item) => item.definesKey),
+    ).toEqual([falseKey, trueKey]);
   });
 
-  it('fails when the manifest does not declare an exact transmission key', () => {
+  it('rejects a missing exact transmission variant', () => {
     const entry = standardEntry([transmissionVariant(falseKey, false)]);
     expect(() => selectStandardPbrTransmissionPrewarmVariants(entry, true)).toThrow(
       'TRANSMISSION_AVAILABLE=true',
     );
   });
-
-  it('fails when the Standard material shader manifest row is missing', () => {
-    expect(() => selectStandardPbrTransmissionPrewarmVariants(undefined, true)).toThrow(
-      'manifest row is missing',
-    );
-  });
 });
 
-describe('HDRP PBR prewarm capability selection', () => {
-  const entry = standardEntry([hdrpVariant(hdrpFalseKey, false), hdrpVariant(hdrpTrueKey, true)]);
+describe('HDRP PBR capability prewarm selection', () => {
+  it('selects only the matching static capability/geometry state', () => {
+    const entry = standardEntry([
+      variant(true, true),
+      variant(true, false),
+      variant(false, true),
+      variant(false, false),
+    ]);
+    expect(selectHdrpPbrPrewarmVariants(entry, true).map((item) => item.definesKey)).toEqual([
+      variant(true, true).definesKey,
+    ]);
+    // Cluster-forward requires the storage-backed group(2) ABI. A device
+    // without storage support must stay on the URP route and prewarm nothing.
+    expect(selectHdrpPbrPrewarmVariants(entry, false)).toEqual([]);
+  });
 
-  it('does not compile the transmission variant below the sampled-texture limit', () => {
+  it('respects an explicitly declared projector capability', () => {
+    const entry = standardEntry([
+      variant(true, true, true),
+      variant(true, true, false),
+      variant(true, true),
+    ]);
     expect(
-      selectHdrpPbrPrewarmVariants(entry, true, false).map((variant) => variant.definesKey),
-    ).toEqual([hdrpFalseKey]);
+      selectHdrpPbrPrewarmVariants(entry, true, undefined, true).map((item) => item.definesKey),
+    ).toEqual([variant(true, true, true).definesKey, variant(true, true).definesKey]);
   });
+});
 
-  it('retains both HDRP variants when transmission is supported', () => {
-    expect(
-      selectHdrpPbrPrewarmVariants(entry, true, true).map((variant) => variant.definesKey),
-    ).toEqual([hdrpFalseKey, hdrpTrueKey]);
+describe('probe material module prewarm capability selection', () => {
+  it('keeps probe variants out of the fallback tier and matches device-owned axes', () => {
+    const entry = standardEntry([
+      probeTransmissionVariant(probeFalseKey, false),
+      probeTransmissionVariant(probeTrueKey, true),
+    ]);
+    expect(selectProbePrewarmVariants(entry, false)).toEqual([]);
+    expect(selectProbePrewarmVariants(entry, true).map((variant) => variant.definesKey)).toEqual([
+      probeFalseKey,
+      probeTrueKey,
+    ]);
+  });
+
+  it('filters backend and sampled-texture axes but retains geometry/topology choices', () => {
+    const goodKey =
+      'CLUSTER_FORWARD_AVAILABLE=true+EXTENDED_LIGHTING_AVAILABLE=false+PROBE_BLEND_AVAILABLE=true+PROJECTOR_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=true';
+    const wrongExtendedKey = goodKey.replace(
+      'EXTENDED_LIGHTING_AVAILABLE=false',
+      'EXTENDED_LIGHTING_AVAILABLE=true',
+    );
+    const wrongProjectorKey = goodKey.replace(
+      'PROJECTOR_AVAILABLE=false',
+      'PROJECTOR_AVAILABLE=true',
+    );
+    const wrongTransmissionKey = goodKey.replace(
+      'TRANSMISSION_AVAILABLE=false',
+      'TRANSMISSION_AVAILABLE=true',
+    );
+    const variant = (definesKey: string, defines: Record<string, boolean>) => ({
+      definesKey,
+      defines,
+      composedWgsl: definesKey,
+    });
+    const baseDefines = {
+      CLUSTER_FORWARD_AVAILABLE: true,
+      EXTENDED_LIGHTING_AVAILABLE: false,
+      PROBE_BLEND_AVAILABLE: true,
+      PROJECTOR_AVAILABLE: false,
+      STORAGE_BUFFER_AVAILABLE: true,
+      TRANSMISSION_AVAILABLE: false,
+      VERTEX_COLOR_AVAILABLE: true,
+    };
+    const selected = selectProbePrewarmVariants(
+      standardEntry([
+        variant(goodKey, baseDefines),
+        variant(wrongExtendedKey, { ...baseDefines, EXTENDED_LIGHTING_AVAILABLE: true }),
+        variant(wrongProjectorKey, { ...baseDefines, PROJECTOR_AVAILABLE: true }),
+        variant(wrongTransmissionKey, { ...baseDefines, TRANSMISSION_AVAILABLE: true }),
+      ]),
+      true,
+      false,
+      false,
+      true,
+      false,
+    );
+    expect(selected.map((candidate) => candidate.definesKey)).toEqual([goodKey]);
   });
 });