@forgeax/engine-render 0.1.23 → 0.1.25

package/src/__tests__/surface-standard-pipeline.dawn.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { projectStandardSurfacePasses } from '../assembly/material/surface-projection';
+import { layerPlanFor, passFor, SURFACE_CASES } from './surface-standard-pipeline.fixture';
+
+describe('Standard Surface render projection contract', () => {
+  it('keeps physical roots Forward-only while base roots remain Deferred', () => {
+    for (const surfaceCase of SURFACE_CASES) {
+      const passes = projectStandardSurfacePasses({
+        surfaceModule: surfaceCase.surfaceModule,
+        values: surfaceCase.material.values ?? {},
+        geometryVariant: 'skinned',
+        lightingLane: 'clustered',
+        alphaClip: true,
+        layerPlan: layerPlanFor(surfaceCase),
+      });
+      expect(passes.some((entry) => entry.name === passFor(surfaceCase))).toBe(true);
+      expect(passes[0]?.program.moduleSlots?.surface).toBe(surfaceCase.surfaceModule);
+    }
+  });
+});

package/src/__tests__/surface-standard-pipeline.fixture.ts

@@ -0,0 +1,132 @@
+import { AssetGuid, type PackageId } from '@forgeax/engine-pack/guid';
+import type { MaterialAsset } from '@forgeax/engine-types';
+import { deriveStandardLayerPlan } from '@forgeax/engine-types';
+
+type SurfacePack = {
+  packageId: PackageId;
+  build: () =>
+    | { readonly ok: true; readonly value: Readonly<Record<string, MaterialAsset>> }
+    | Promise<{ readonly ok: true; readonly value: Readonly<Record<string, MaterialAsset>> }>;
+};
+
+type ViteImportMeta = ImportMeta & {
+  glob<T>(
+    patterns: readonly string[],
+    options: { readonly eager: true; readonly import: 'default' },
+  ): Readonly<Record<string, T>>;
+};
+
+const packModules = Object.values(
+  (import.meta as ViteImportMeta).glob<SurfacePack>(
+    [
+      '../../../../templates/game-3d/assets/materials.pack.ts',
+      '../../../../apps/preview/assets/surface-standard-evidence.pack.ts',
+    ],
+    {
+      eager: true,
+      import: 'default',
+    },
+  ),
+);
+if (packModules.length !== 2)
+  throw new Error('surface-evidence-fixture: required pack module missing');
+
+const builtPacks = packModules.map((pack) => {
+  const built = pack.build();
+  if (built instanceof Promise || !built.ok) {
+    throw new Error('surface-evidence-fixture: materials pack did not produce outputs');
+  }
+  return { packageId: pack.packageId, values: built.value };
+});
+const materials = Object.assign({}, ...builtPacks.map((pack) => pack.values)) as Record<
+  string,
+  MaterialAsset | undefined
+>;
+
+function guidForSourceKey(sourceKey: string): AssetGuid {
+  const owner = builtPacks.find((pack) => Object.hasOwn(pack.values, sourceKey));
+  if (owner === undefined) {
+    throw new Error(`surface-evidence-fixture: source key '${sourceKey}' is not published`);
+  }
+  return AssetGuid.derive(owner.packageId, sourceKey);
+}
+
+const rustedIron = materials['material/rusted-iron'];
+
+const defaultBase = materials['material/ground'];
+const defaultPhysical = materials['material/painted'];
+const customPhysical = materials['material/rusted-iron-custom-physical'];
+if (
+  rustedIron === undefined ||
+  defaultBase === undefined ||
+  defaultPhysical === undefined ||
+  customPhysical === undefined
+)
+  throw new Error('surface-evidence-fixture: required material row missing');
+
+export const SURFACE_CLOSURE = 'forgeax_material::surface_v1';
+export const SURFACE_SOURCE_CLOSURE = [
+  'templates/game-3d/assets/materials.pack.ts',
+  'templates/game-3d/assets/shaders/rusted-iron.wgsl',
+] as const;
+export const SURFACE_SOURCE_PATH = 'templates/game-3d/assets/shaders/rusted-iron.wgsl';
+export const SURFACE_MATERIAL_SOURCE_KEY = 'material/rusted-iron';
+export const EVIDENCE_SOURCE_SHA =
+  (import.meta as ImportMeta & { env?: Record<string, string | undefined> }).env
+    ?.VITE_FORGEAX_EVIDENCE_SOURCE_SHA ?? 'unavailable';
+
+export const SURFACE_CASES = [
+  {
+    id: 'default-base',
+    material: defaultBase,
+    materialGuid: AssetGuid.format(guidForSourceKey('material/ground')),
+    surfaceModule: defaultBase.passes?.[0]?.program.moduleSlots?.surface ?? '',
+    physical: false,
+  },
+  {
+    id: 'custom-base',
+    material: rustedIron,
+    materialGuid: AssetGuid.format(guidForSourceKey('material/rusted-iron')),
+    surfaceModule: rustedIron.passes?.[0]?.program.moduleSlots?.surface ?? '',
+    physical: false,
+  },
+  {
+    id: 'default-physical',
+    material: defaultPhysical,
+    materialGuid: '019fb7ce-3200-7000-8000-000000000002',
+    surfaceModule: defaultPhysical.passes?.[0]?.program.moduleSlots?.surface ?? '',
+    physical: true,
+  },
+  {
+    id: 'custom-physical',
+    material: customPhysical,
+    materialGuid: '019fb7ce-3f00-7000-8000-000000000001',
+    surfaceModule: customPhysical.passes?.[0]?.program.moduleSlots?.surface ?? '',
+    physical: true,
+  },
+] as const;
+
+export function layerPlanFor(surfaceCase: (typeof SURFACE_CASES)[number]) {
+  return deriveStandardLayerPlan(
+    surfaceCase.physical ? (surfaceCase.material.parameters ?? []) : [],
+  );
+}
+
+export function baseColorFor(
+  surfaceCase: (typeof SURFACE_CASES)[number],
+): readonly [number, number, number] {
+  const values = surfaceCase.material.values ?? {};
+  const value = values.baseColor ?? values.ironColor;
+  if (!Array.isArray(value) || value.length < 3) {
+    throw new Error(`surface-evidence-fixture: missing base color for ${surfaceCase.id}`);
+  }
+  return [Number(value[0]), Number(value[1]), Number(value[2])];
+}
+
+export function passFor(surfaceCase: (typeof SURFACE_CASES)[number]): 'forward' | 'deferred' {
+  return layerPlanFor(surfaceCase).mode === 'physical' ? 'forward' : 'deferred';
+}
+
+export function publicationGenerationFor(_surfaceCase: (typeof SURFACE_CASES)[number]): number {
+  return 1;
+}

package/src/__tests__/surface-variant-provenance.integration.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import {
+  projectStandardSurfacePasses,
+  type StandardSurfaceProjectionOptions,
+} from '../assembly/material/surface-projection';
+
+type FullCustomFixture = StandardSurfaceProjectionOptions & {
+  readonly surfaceKind: 'full-custom';
+  readonly declaredPasses: readonly ('forward' | 'deferred' | 'shadow-caster')[];
+};
+
+describe('full-custom Surface provenance', () => {
+  it('does not synthesize an undeclared Deferred pass or fallback identity', () => {
+    const options: FullCustomFixture = {
+      surfaceModule: 'game_3d::full_custom_surface',
+      values: { tint: [1, 0.1, 0.05, 1] },
+      surfaceKind: 'full-custom',
+      declaredPasses: ['forward', 'shadow-caster'],
+    };
+
+    const passes = projectStandardSurfacePasses(options);
+
+    expect(passes.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+    expect(passes.map((pass) => pass.program.module)).toEqual([
+      'forgeax_material::standard',
+      'forgeax_material::standard',
+    ]);
+    for (const pass of passes) {
+      expect(pass.program.moduleSlots?.surface).toBe(options.surfaceModule);
+      expect((pass.renderState?.tags as Record<string, string>).SurfaceKind).toBe('full-custom');
+    }
+  });
+});

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-budget-recovery.integration.test.ts

@@ -651,5 +651,5 @@ describe('volumetric fog budget and recovery contract', () => {
       activeLedger: steadyLedger,
     });
     await renderer.dispose();
-  });
+  }, 30_000);
 });

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