@forgeax/engine-render 0.1.23 → 0.1.24

package/src/__tests__/renderer-recovery-lifecycle.unit.test.ts

@@ -0,0 +1,216 @@
+import { RhiNullCommandEncoder, RhiNullDevice, RhiNullQueue, rhi } from '@forgeax/engine-rhi-null';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  acquireDeviceGeneration,
+  probeCandidateGraphExecution,
+  runRecoveryStep,
+} from '../assembly/recovery/recovery-attempt';
+import {
+  createRecoveryContinuation,
+  createRecoveryDeadline,
+  createRendererLifecycle,
+  createSingleFlight,
+  RECOVERY_ADAPTER_DEADLINE_MS,
+  RECOVERY_DEVICE_DEADLINE_MS,
+  RECOVERY_PHASES,
+  RECOVERY_TOTAL_DEADLINE_MS,
+} from '../assembly/renderer-lifecycle';
+
+describe('renderer recovery lifecycle', () => {
+  it('exhausts the public lifecycle states and rejects illegal transitions', () => {
+    const lifecycle = createRendererLifecycle();
+
+    expect(lifecycle.state()).toBe('alive');
+    expect(lifecycle.transition('device-lost')).toBe(true);
+    expect(lifecycle.transition('recovering')).toBe(true);
+    expect(lifecycle.transition('alive')).toBe(true);
+    expect(lifecycle.transition('faulted')).toBe(false);
+    expect(lifecycle.transition('disposed')).toBe(true);
+    expect(lifecycle.transition('alive')).toBe(false);
+    expect(lifecycle.states()).toEqual([
+      'alive',
+      'device-lost',
+      'recovering',
+      'faulted',
+      'disposed',
+    ]);
+  });
+
+  it('shares one recovery promise and one candidate for concurrent callers', async () => {
+    let attempts = 0;
+    let release: (() => void) | undefined;
+    const flight = createSingleFlight(async () => {
+      attempts += 1;
+      await new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      return { candidate: attempts };
+    });
+
+    const first = flight.run();
+    const second = flight.run();
+    expect(first).toBe(second);
+    expect(flight.inFlight()).toBe(first);
+    expect(attempts).toBe(1);
+
+    release?.();
+    await expect(first).resolves.toEqual({ candidate: 1 });
+    expect(flight.inFlight()).toBeUndefined();
+  });
+
+  it('enforces the 20 second attempt and 10 second acquisition budgets', () => {
+    const deadline = createRecoveryDeadline(1000);
+
+    expect(deadline.totalDeadlineMs).toBe(RECOVERY_TOTAL_DEADLINE_MS);
+    expect(deadline.adapterDeadlineMs).toBe(RECOVERY_ADAPTER_DEADLINE_MS);
+    expect(deadline.deviceDeadlineMs).toBe(RECOVERY_DEVICE_DEADLINE_MS);
+    expect(deadline.isValid('acquire-adapter', 10_999)).toBe(true);
+    expect(deadline.isValid('acquire-adapter', 11_000)).toBe(false);
+    expect(deadline.isValid('acquire-device', 11_000)).toBe(false);
+    expect(deadline.isValid('compile-graph', 20_999)).toBe(true);
+    expect(deadline.isValid('compile-graph', 21_000)).toBe(false);
+    expect(RECOVERY_PHASES).toEqual([
+      'quiesce',
+      'acquire-adapter',
+      'acquire-device',
+      'rehydrate',
+      'compile-graph',
+      'publish',
+      'cleanup',
+    ]);
+  });
+
+  it('reports acquisition phases in their execution order', async () => {
+    const phases: string[] = [];
+    const result = await acquireDeviceGeneration(
+      { rhi },
+      {} as HTMLCanvasElement,
+      undefined,
+      undefined,
+      (phase) => phases.push(phase),
+    );
+
+    expect(result.ok).toBe(true);
+    expect(phases).toEqual(['acquire-adapter', 'acquire-device']);
+  });
+
+  it('treats the null graph probe as structural-only and rejects a non-null pixel mismatch', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const nullDevice = (await adapter.requestDevice()).unwrap();
+    const texture = nullDevice
+      .createTexture({
+        label: 'recovery-probe-test.texture',
+        size: { width: 1, height: 1, depthOrArrayLayers: 1 },
+        mipLevelCount: 1,
+        sampleCount: 1,
+        dimension: '2d',
+        format: 'rgba8unorm',
+        usage: 0x11,
+        viewFormats: undefined,
+        textureBindingViewDimension: undefined,
+      })
+      .unwrap();
+    const view = nullDevice.createTextureView(texture, { dimension: '2d' }).unwrap();
+    const nullProbe = await probeCandidateGraphExecution(nullDevice, {
+      texture,
+      view,
+      format: 'rgba8unorm',
+    });
+    expect(nullProbe.ok).toBe(true);
+
+    class PixellessNonNullDevice extends RhiNullDevice {
+      override get caps() {
+        return { ...super.caps, backendKind: 'webgpu' as const };
+      }
+    }
+    const nonNullDevice = new PixellessNonNullDevice(
+      new RhiNullQueue(),
+      (bookkeeper, device) => new RhiNullCommandEncoder(bookkeeper, device),
+    );
+    const nonNullTexture = nonNullDevice
+      .createTexture({
+        label: 'recovery-probe-test.non-null-texture',
+        size: { width: 1, height: 1, depthOrArrayLayers: 1 },
+        mipLevelCount: 1,
+        sampleCount: 1,
+        dimension: '2d',
+        format: 'rgba8unorm',
+        usage: 0x11,
+        viewFormats: undefined,
+        textureBindingViewDimension: undefined,
+      })
+      .unwrap();
+    const nonNullView = nonNullDevice
+      .createTextureView(nonNullTexture, { dimension: '2d' })
+      .unwrap();
+    const nonNullProbe = await probeCandidateGraphExecution(nonNullDevice, {
+      texture: nonNullTexture,
+      view: nonNullView,
+      format: 'rgba8unorm',
+    });
+    expect(nonNullProbe.ok).toBe(false);
+    if (!nonNullProbe.ok) expect(nonNullProbe.error.code).toBe('webgpu-runtime-error');
+  });
+
+  it('invalidates late continuation and cleans the candidate exactly once', () => {
+    let cleanupCount = 0;
+    const continuation = createRecoveryContinuation(createRecoveryDeadline(0), () => {
+      cleanupCount += 1;
+    });
+
+    expect(continuation.isValid('compile-graph', 19_999)).toBe(true);
+    continuation.abandon(20_000);
+    expect(continuation.isValid('compile-graph', 20_000)).toBe(false);
+    continuation.cleanupOnce();
+    continuation.cleanupOnce();
+    expect(cleanupCount).toBe(1);
+  });
+
+  it('invalidates an async step on timeout before a late completion can write', async () => {
+    let cleanupCount = 0;
+    let lateWrites = 0;
+    const startedAt = Date.now();
+    const deadline = {
+      startedAt,
+      totalDeadlineMs: 1,
+      adapterDeadlineMs: 1,
+      deviceDeadlineMs: 1,
+      deadlineAt: startedAt + 1,
+      beginDeviceAcquisition: (_now: number) => undefined,
+      isValid: (
+        _phase:
+          | 'quiesce'
+          | 'acquire-adapter'
+          | 'acquire-device'
+          | 'rehydrate'
+          | 'compile-graph'
+          | 'publish'
+          | 'cleanup',
+        now: number,
+      ) => now < startedAt + 1,
+      elapsed: (now: number) => Math.max(0, now - startedAt),
+    };
+    const continuation = createRecoveryContinuation(deadline, () => {
+      cleanupCount += 1;
+    });
+
+    const outcome = await runRecoveryStep(
+      async (attemptToken) => {
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        if (attemptToken?.isValid('compile-graph', Date.now())) lateWrites += 1;
+        return ok(undefined);
+      },
+      'compile-graph',
+      deadline,
+      Date.now,
+      continuation,
+    );
+
+    expect(outcome.kind).toBe('timeout');
+    if (outcome.kind === 'timeout') expect(outcome.timeout.cause.code).toBe('webgpu-runtime-error');
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(lateWrites).toBe(0);
+    expect(cleanupCount).toBe(1);
+  });
+});

package/src/__tests__/renderer-target-history-recovery.integration.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+import { TaaHistoryStore } from '../temporal/taa-history-store';
+
+type RecoveryReceipt = {
+  readonly deviceGeneration: number;
+  readonly completed: boolean;
+};
+
+type RecoverableHistory = TaaHistoryStore & {
+  recoverForGeneration(deviceGeneration: number): void;
+};
+
+function recover(store: TaaHistoryStore, deviceGeneration: number): void {
+  (store as RecoverableHistory).recoverForGeneration(deviceGeneration);
+}
+
+function commit(store: TaaHistoryStore, receipt: RecoveryReceipt): void {
+  const attempt = store.begin('device-generation');
+  attempt.commit(receipt as never);
+}
+
+describe('M4 / m4_t2 — target history recovery keeps logical token', () => {
+  it('publishes uninitialized replacement storage with neutral fallback', () => {
+    const store = new TaaHistoryStore();
+    const token = (
+      store.inspect() as typeof store.inspect extends () => infer T ? T : never & { token: string }
+    ).token;
+
+    recover(store, 8);
+
+    expect(store.inspect()).toMatchObject({
+      token,
+      deviceGeneration: 8,
+      content: 'uninitialized',
+      fallback: 'neutral-texture',
+      valid: false,
+      requestVersion: 0,
+    });
+  });
+
+  it('raises history only for a matching completed receipt', () => {
+    const store = new TaaHistoryStore();
+    recover(store, 8);
+    const before = store.inspect();
+
+    commit(store, { deviceGeneration: 7, completed: true });
+    expect(store.inspect()).toMatchObject({
+      token: before.token,
+      deviceGeneration: 8,
+      content: 'uninitialized',
+      valid: false,
+      requestVersion: 0,
+    });
+
+    commit(store, { deviceGeneration: 8, completed: false });
+    expect(store.inspect().valid).toBe(false);
+
+    commit(store, { deviceGeneration: 8, completed: true });
+    expect(store.inspect()).toMatchObject({
+      token: before.token,
+      deviceGeneration: 8,
+      content: 'active',
+      valid: true,
+      requestVersion: 1,
+    });
+  });
+
+  it('does not invent once or on-demand requests during replacement', () => {
+    const store = new TaaHistoryStore();
+    recover(store, 9);
+    const inspection = store.inspect() as typeof store.inspect extends () => infer T
+      ? T
+      : never & {
+          requestVersion: number;
+        };
+
+    expect(inspection.requestVersion).toBe(0);
+    expect(inspection.content).toBe('uninitialized');
+  });
+});

package/src/__tests__/shader-manifest-fixture.ts

@@ -58,22 +58,19 @@ const standardPbrVariants = (() => {
   const variants = [];
   for (const cluster of [false, true]) {
     for (const storage of [false, true]) {
-      for (const transmission of [false, true]) {
-        for (const vertexColor of [false, true]) {
-          const defines = {
-            CLUSTER_FORWARD_AVAILABLE: cluster,
-            STORAGE_BUFFER_AVAILABLE: storage,
-            TRANSMISSION_AVAILABLE: transmission,
-            VERTEX_COLOR_AVAILABLE: vertexColor,
-          };
-          const sortedDefines = Object.entries(defines).sort(([left], [right]) =>
-            left < right ? -1 : left > right ? 1 : 0,
-          );
-          const definesKey = sortedDefines.every(([, value]) => value)
-            ? ''
-            : sortedDefines.map(([key, value]) => `${key}=${value}`).join('+');
-          variants.push({ definesKey, defines, composedWgsl: pbrWgsl });
-        }
+      for (const vertexColor of [false, true]) {
+        const defines = {
+          CLUSTER_FORWARD_AVAILABLE: cluster,
+          STORAGE_BUFFER_AVAILABLE: storage,
+          VERTEX_COLOR_AVAILABLE: vertexColor,
+        };
+        const sortedDefines = Object.entries(defines).sort(([left], [right]) =>
+          left < right ? -1 : left > right ? 1 : 0,
+        );
+        const definesKey = sortedDefines.every(([, value]) => value)
+          ? ''
+          : sortedDefines.map(([key, value]) => `${key}=${value}`).join('+');
+        variants.push({ definesKey, defines, composedWgsl: pbrWgsl });
       }
     }
   }

package/src/__tests__/shader-stage-surface.unit.test.ts

@@ -20,7 +20,7 @@ const fragmentConsumerSources = [
   pbrPipelineSource,
   iblPipelineCacheSource,
   readFileSync(new URL('../ibl/skylight-bind-group.ts', import.meta.url), 'utf8'),
-  readFileSync(new URL('../assembly/factory.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../assembly/webgpu-renderer.ts', import.meta.url), 'utf8'),
 ];
 
 describe('shader stage owner', () => {

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__/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,6 @@ 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 =
@@ -30,29 +27,33 @@ function standardEntry(
   };
 }
 
-function transmissionVariant(definesKey: string, transmission: boolean) {
+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,
-    defines: {
-      CLUSTER_FORWARD_AVAILABLE: false,
-      STORAGE_BUFFER_AVAILABLE: true,
-      TRANSMISSION_AVAILABLE: transmission,
-      VERTEX_COLOR_AVAILABLE: false,
-    },
-    composedWgsl: `standard-${transmission}`,
+    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 hdrpVariant(definesKey: string, transmission: boolean) {
+function transmissionVariant(definesKey: string, transmission: boolean) {
   return {
     definesKey,
     defines: {
-      CLUSTER_FORWARD_AVAILABLE: true,
+      CLUSTER_FORWARD_AVAILABLE: false,
       STORAGE_BUFFER_AVAILABLE: true,
       TRANSMISSION_AVAILABLE: transmission,
       VERTEX_COLOR_AVAILABLE: false,
     },
-    composedWgsl: `hdrp-${transmission}`,
+    composedWgsl: `standard-${transmission}`,
   };
 }
 
@@ -60,103 +61,112 @@ function probeTransmissionVariant(definesKey: string, transmission: boolean) {
   const base = transmissionVariant(definesKey, transmission);
   return {
     ...base,
-    definesKey,
     defines: { ...base.defines, PROBE_BLEND_AVAILABLE: true },
   };
 }
 
-function capabilityTransmissionVariant(
-  definesKey: string,
-  transmission: boolean,
-  extendedLighting: boolean,
-) {
-  const base = transmissionVariant(definesKey, transmission);
-  return {
-    ...base,
-    definesKey,
-    defines: {
-      ...base.defines,
-      EXTENDED_LIGHTING_AVAILABLE: extendedLighting,
-      PROJECTOR_AVAILABLE: true,
-    },
-    composedWgsl: `standard-${extendedLighting ? 'extended' : 'fallback'}-${transmission}`,
-  };
-}
-
 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',
-    );
-  });
-
-  it('keeps object-level probe variants out of the boot prewarm selection', () => {
+describe('HDRP PBR capability prewarm selection', () => {
+  it('selects only the matching static capability/geometry state', () => {
     const entry = standardEntry([
-      probeTransmissionVariant(probeFalseKey, false),
-      transmissionVariant(falseKey, false),
-      probeTransmissionVariant(probeTrueKey, true),
-      transmissionVariant(trueKey, true),
+      variant(true, true),
+      variant(true, false),
+      variant(false, true),
+      variant(false, false),
     ]);
-    expect(
-      selectStandardPbrTransmissionPrewarmVariants(entry, true).map(
-        (variant) => variant.definesKey,
-      ),
-    ).toEqual([falseKey, trueKey]);
+    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('selects the prewarm pair for the admitted extended-lighting capability', () => {
-    const fallbackFalseKey = `${falseKey}+EXTENDED_LIGHTING_AVAILABLE=false+PROJECTOR_AVAILABLE=true`;
-    const fallbackTrueKey = `${trueKey}+EXTENDED_LIGHTING_AVAILABLE=false+PROJECTOR_AVAILABLE=true`;
-    const extendedFalseKey = `${falseKey}+EXTENDED_LIGHTING_AVAILABLE=true+PROJECTOR_AVAILABLE=true`;
-    const extendedTrueKey = `${trueKey}+EXTENDED_LIGHTING_AVAILABLE=true+PROJECTOR_AVAILABLE=true`;
+  it('respects an explicitly declared projector capability', () => {
     const entry = standardEntry([
-      capabilityTransmissionVariant(fallbackFalseKey, false, false),
-      capabilityTransmissionVariant(fallbackTrueKey, true, false),
-      capabilityTransmissionVariant(extendedFalseKey, false, true),
-      capabilityTransmissionVariant(extendedTrueKey, true, true),
+      variant(true, true, true),
+      variant(true, true, false),
+      variant(true, true),
     ]);
-
     expect(
-      selectStandardPbrTransmissionPrewarmVariants(entry, true, true, true, false).map(
-        (variant) => variant.definesKey,
-      ),
-    ).toEqual([fallbackFalseKey, fallbackTrueKey]);
-    expect(
-      selectStandardPbrTransmissionPrewarmVariants(entry, true, true, true, true).map(
-        (variant) => variant.definesKey,
-      ),
-    ).toEqual([extendedFalseKey, extendedTrueKey]);
+      selectHdrpPbrPrewarmVariants(entry, true, undefined, true).map((item) => item.definesKey),
+    ).toEqual([variant(true, true, true).definesKey, variant(true, true).definesKey]);
   });
 });
 
-describe('HDRP PBR prewarm capability selection', () => {
-  const entry = standardEntry([hdrpVariant(hdrpFalseKey, false), hdrpVariant(hdrpTrueKey, true)]);
-
-  it('does not compile the transmission variant below the sampled-texture limit', () => {
-    expect(
-      selectHdrpPbrPrewarmVariants(entry, true, false).map((variant) => variant.definesKey),
-    ).toEqual([hdrpFalseKey]);
+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('retains both HDRP variants when transmission is supported', () => {
-    expect(
-      selectHdrpPbrPrewarmVariants(entry, true, true).map((variant) => variant.definesKey),
-    ).toEqual([hdrpFalseKey, hdrpTrueKey]);
+  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]);
   });
 });

package/src/__tests__/volumetric-fog-topology.unit.test.ts

@@ -219,7 +219,9 @@ describe('volumetric fog RenderGraph topology', () => {
       fileURLToPath(new URL('../render-system.ts', import.meta.url)),
       'utf8',
     );
-    const recoverStart = renderSystemSource.indexOf('resetForRecover(): void {');
+    const recoverStart = renderSystemSource.indexOf(
+      'resetForRecover(retiringPipelineState?: PipelineState, replacementDevice?: RhiDevice): void {',
+    );
     expect(recoverStart).toBeGreaterThanOrEqual(0);
     const recoverEnd = renderSystemSource.indexOf(
       'restorePostProcessResources(): void',

package/src/assembly/bundler-contract.ts

@@ -0,0 +1,9 @@
+import type { ImportTransport } from '@forgeax/engine-types';
+
+/** Build-tool inputs forwarded from the host into renderer assembly. */
+export interface BundlerOptions {
+  readonly importTransport?: ImportTransport | undefined;
+  readonly shaderManifestUrl?: string | undefined;
+  /** Exact checkout revision emitted by the build-tool adapter. */
+  readonly build?: string | undefined;
+}

package/src/assembly/device-feature-admission.ts

@@ -14,6 +14,14 @@ const COMPRESSION_FEATURES: GPUFeatureName[] = [
 // request that larger limit when the adapter can provide it; adapter limits are
 // not automatically inherited by requestDevice().
 export const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 17;
+/**
+ * The complete Standard physical root can declare all optional texture slots.
+ * Its material group therefore needs one more sampled-texture entry than the
+ * extended-lighting topology alone. Request this ceiling when the adapter can
+ * provide it; lower-capability devices remain fail-closed at material
+ * pipeline admission instead of receiving an invalid WebGPU layout.
+ */
+export const STANDARD_PHYSICAL_REQUIRED_SAMPLED_TEXTURES = 21;
 
 export interface DeviceFeatureAdmissionOptions {
   readonly gpuPassTiming?: object | undefined;
@@ -41,11 +49,13 @@ export function deriveDeviceFeatureAdmission(
   }
   const adapterSampledTextureLimit = adapter.limits?.maxSampledTexturesPerShaderStage ?? 0;
   const requiredSampledTextureLimit =
-    adapterSampledTextureLimit >= EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES
-      ? EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES
-      : adapterSampledTextureLimit >= STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES
-        ? STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES
-        : undefined;
+    adapterSampledTextureLimit >= STANDARD_PHYSICAL_REQUIRED_SAMPLED_TEXTURES
+      ? STANDARD_PHYSICAL_REQUIRED_SAMPLED_TEXTURES
+      : adapterSampledTextureLimit >= EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES
+        ? EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES
+        : adapterSampledTextureLimit >= STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES
+          ? STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES
+          : undefined;
   return {
     requiredFeatures,
     ...(requiredSampledTextureLimit === undefined