@forgeax/engine-render 0.1.24 → 0.1.26

package/src/__tests__/skin-motion-regression.unit.test.ts

@@ -45,6 +45,39 @@ describe('custom skinned mesh motion consumer contract', () => {
     expect(writes[1]?.data[12]).toBe(0.5);
   });
 
+  it('keeps stable uniform palette slices isolated across frame-pool resets', () => {
+    const device = {
+      limits: { maxUniformBufferBindingSize: 65536 },
+      createBuffer: () => ok({} as Buffer),
+      destroyBuffer: () => undefined,
+      queue: { writeBuffer: () => ok(undefined) },
+    } as unknown as RhiDevice;
+    const allocator = createSkinPaletteAllocator(device, 65536, false);
+    const first = allocator.allocateSliceFor('world:1', 1);
+    allocator.resetForFrame();
+    const second = allocator.allocateSliceFor('world:2', 1);
+
+    expect(second.buffer).not.toBe(first.buffer);
+  });
+
+  it('does not reuse a split storage range beyond its binding window', () => {
+    let bufferId = 0;
+    const device = {
+      limits: { maxStorageBufferBindingSize: 65536 },
+      createBuffer: () => ok({ id: bufferId++ } as unknown as Buffer),
+      queue: { writeBuffer: () => ok(undefined) },
+    } as unknown as RhiDevice;
+    const allocator = createSkinPaletteAllocator(device, 65536, true);
+
+    const full = allocator.allocateSliceFor('world:full', 255);
+    allocator.releaseSliceFor('world:full');
+    const firstSmall = allocator.allocateSliceFor('world:first', 1);
+    const secondSmall = allocator.allocateSliceFor('world:second', 1);
+
+    expect(firstSmall.buffer).toBe(full.buffer);
+    expect(secondSmall.buffer).not.toBe(full.buffer);
+  });
+
   it('prepares both URP and HDRP pbr-skin consumers with the skin-cluster contract', () => {
     const variants = selectSkinPrewarmVariants(
       {

package/src/__tests__/skinned-shadow-caster.test.ts

@@ -9,6 +9,7 @@ import {
   SHADOW_CASTER_SHADER_ID,
   shadowCasterVariantSet,
 } from '../pbr-pipeline.js';
+import { shadowShaderMap } from '../record/shadow-pass.js';
 
 describe('skinned shadow caster', () => {
   it('derives closed capability variants without changing the shader identity', () => {
@@ -52,8 +53,7 @@ describe('skinned shadow caster', () => {
     expect(shader).toContain('let skinMatrix = palette[');
     expect(record).toContain('entry.source.skin.byteOffset');
     expect(record).toContain("'shadow-pbr-skin-mesh'");
-    expect(builder).toContain("ctx.layoutKind === 'pbr-skin'");
-    expect(builder).toContain('? [...ctx.vertexBuffers]');
+    expect(builder).toContain('buffers: [...ctx.vertexBuffers]');
   });
 
   it('keeps mixed static and skinned shadow draws on matching variants and bindings', () => {
@@ -129,4 +129,32 @@ describe('skinned shadow caster', () => {
     );
     expect(recordSource).toContain('binding: 12');
   });
+
+  it('keeps each submesh material associated with its selected shadow program and entries', () => {
+    const context = {
+      dispatch: [
+        {
+          renderableIndex: 4,
+          materialHandle: 42,
+          materialShaderId: 'forgeax::default-standard-pbr',
+          tags: { LightMode: 'ShadowCaster' },
+        },
+        {
+          renderableIndex: 4,
+          materialHandle: 43,
+          materialShaderId: 'custom::cutout',
+          vertexEntry: 'vs_displaced',
+          fragmentEntry: 'fs_cutout',
+          tags: { LightMode: 'ShadowCaster' },
+        },
+      ],
+    } as never;
+    const bindings = shadowShaderMap(context);
+    expect(bindings.get(4)?.get(42)?.materialShaderId).toBe(SHADOW_CASTER_SHADER_ID);
+    expect(bindings.get(4)?.get(43)).toMatchObject({
+      materialShaderId: 'custom::cutout',
+      vertexEntry: 'vs_displaced',
+      fragmentEntry: 'fs_cutout',
+    });
+  });
 });

package/src/__tests__/surface-adjacent-regressions.integration.test.ts

@@ -0,0 +1,60 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import {
+  projectStandardSurfacePasses,
+  type StandardSurfaceProjectionOptions,
+} from '../assembly/material/surface-projection';
+import { GPU_DRIVEN_RIGID_UNLIT_WGSL } from '../gpu-driven/production-raster';
+
+function shaderSource(name: string): string {
+  return readFileSync(
+    fileURLToPath(new URL(`../../../shader/src/${name}`, import.meta.url)),
+    'utf8',
+  );
+}
+
+const standard: StandardSurfaceProjectionOptions = {
+  surfaceModule: 'game_3d::rusted_iron_surface',
+  values: {},
+  geometryVariant: 'rigid',
+  lightingLane: 'direct',
+  alphaClip: true,
+};
+
+describe('Surface adjacent regressions', () => {
+  it('retains the default Standard pass family and provenance', () => {
+    const passes = projectStandardSurfacePasses(standard);
+    expect(passes.map((pass) => pass.name)).toEqual(['forward', 'deferred', 'shadow-caster']);
+    expect(
+      passes.every((pass) => pass.program.moduleSlots?.surface === standard.surfaceModule),
+    ).toBe(true);
+    expect(
+      passes.every(
+        (pass) =>
+          (pass.renderState?.tags as Readonly<Record<string, string>> | undefined)?.SurfaceKind ===
+          'standard',
+      ),
+    ).toBe(true);
+  });
+
+  it('keeps explicit full-custom pass ownership closed', () => {
+    const passes = projectStandardSurfacePasses({
+      ...standard,
+      surfaceKind: 'full-custom',
+      declaredPasses: ['forward'],
+    });
+    expect(passes.map((pass) => pass.name)).toEqual(['forward']);
+    expect(
+      (passes[0]?.renderState?.tags as Readonly<Record<string, string>> | undefined)?.SurfaceKind,
+    ).toBe('full-custom');
+  });
+
+  it('keeps skinning and GPU-driven siblings on their own shader owners', () => {
+    const skinned = shaderSource('default-standard-pbr-skin.wgsl');
+    expect(skinned).toContain('skinIndex');
+    expect(skinned).toContain('skinWeight');
+    expect(GPU_DRIVEN_RIGID_UNLIT_WGSL).toContain('@builtin(instance_index)');
+    expect(GPU_DRIVEN_RIGID_UNLIT_WGSL).not.toContain('surface_v1');
+  });
+});

package/src/__tests__/surface-standard-pipeline.browser.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('projects every published cell to its declared pass and Surface module', () => {
+    for (const surfaceCase of SURFACE_CASES) {
+      const passes = projectStandardSurfacePasses({
+        surfaceModule: surfaceCase.surfaceModule,
+        values: surfaceCase.material.values ?? {},
+        geometryVariant: 'rigid',
+        lightingLane: 'direct',
+        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.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::default-shadow-caster',
+    ]);
+    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__/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/assembly/factory.ts

@@ -64,11 +64,11 @@ export {
   exposeRenderer,
   isSharedMaterialUserRegionCompatible,
   normalizeMaterialShaderVariantSet,
-  projectMaterialPipeline,
+  resolveMaterialShaderBackendArtifactKey,
   resolveMaterialShaderBindingContract,
+  resolveMaterialShaderUvSetCount,
   resolveMaterialShaderVariantSet,
   resolveMaterialShaderVertexInputContract,
-  routeMaterialPipeline,
   selectHdrpPbrPrewarmVariants,
   selectNoColorPbrVariant,
   selectPipelineLayoutForVariant,
@@ -76,7 +76,6 @@ export {
   selectSkinPrewarmVariants,
   selectStandardPbrTransmissionPrewarmVariants,
   shouldDeferMissingPreparedMaterialShader,
-  updateMaterialRuntimeValues,
 } from './webgpu-renderer';
 
 const GPU_ENVIRONMENT_ERROR_CODES = new Set([

package/src/assembly/material/__tests__/standard-layer-plan-projection.integration.test.ts

@@ -0,0 +1,18 @@
+import { deriveStandardLayerPlan } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { projectStandardSurfacePasses } from '../surface-projection.js';
+
+describe('StandardLayerPlan pass projection', () => {
+  it('keeps a physical Standard material on Forward and shadow passes', () => {
+    const plan = deriveStandardLayerPlan([
+      { name: 'clearcoat', type: 'f32' },
+      { name: 'clearcoatRoughness', type: 'f32' },
+    ]);
+    const passes = projectStandardSurfacePasses({
+      surfaceModule: 'game::surface',
+      values: {},
+      layerPlan: plan,
+    });
+    expect(passes.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+  });
+});

package/src/assembly/material/__tests__/surface-pass-projection.integration.test.ts

@@ -0,0 +1,62 @@
+import { deriveStandardLayerPlan } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  projectStandardSurfacePasses,
+  type StandardSurfaceProjectionOptions,
+} from '../surface-projection';
+
+type SurfaceFixture = StandardSurfaceProjectionOptions & {
+  readonly geometryVariant: 'rigid' | 'skinned' | 'instanced';
+  readonly lightingLane: 'direct' | 'clustered';
+  readonly alphaClip: boolean;
+};
+
+const fixture = (geometryVariant: SurfaceFixture['geometryVariant']): SurfaceFixture => ({
+  surfaceModule: 'game_3d::rusted_iron_surface',
+  values: { ironColor: [0.42, 0.47, 0.5, 1] },
+  geometryVariant,
+  lightingLane: geometryVariant === 'instanced' ? 'clustered' : 'direct',
+  alphaClip: geometryVariant === 'skinned',
+});
+
+function tagsFor(pass: ReturnType<typeof projectStandardSurfacePasses>[number]) {
+  return pass.renderState?.tags as Record<string, string>;
+}
+
+describe('Standard Surface pass projection', () => {
+  it.each([
+    'rigid',
+    'skinned',
+    'instanced',
+  ] as const)('projects one %s Surface closure into every Standard pass', (geometryVariant) => {
+    const options = fixture(geometryVariant);
+    const passes = projectStandardSurfacePasses(options);
+
+    expect(passes.map((pass) => pass.name)).toEqual(['forward', 'deferred', 'shadow-caster']);
+    for (const pass of passes) {
+      expect(pass.program.moduleSlots?.surface).toBe(options.surfaceModule);
+      expect(tagsFor(pass)).toMatchObject({
+        SurfaceModule: options.surfaceModule,
+        GeometryVariant: geometryVariant,
+        LightingLane: options.lightingLane,
+        AlphaClip: options.alphaClip ? 'enabled' : 'disabled',
+      });
+    }
+  });
+
+  it('keeps base Standard on Deferred while physical Standard stays Forward-only', () => {
+    const base = projectStandardSurfacePasses({
+      ...fixture('rigid'),
+      layerPlan: deriveStandardLayerPlan([]),
+    });
+    const physical = projectStandardSurfacePasses({
+      ...fixture('rigid'),
+      layerPlan: deriveStandardLayerPlan([
+        { name: 'clearcoat', type: 'f32' },
+        { name: 'clearcoatRoughness', type: 'f32' },
+      ]),
+    });
+    expect(base.map((pass) => pass.name)).toEqual(['forward', 'deferred', 'shadow-caster']);
+    expect(physical.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+  });
+});

package/src/assembly/material/assembly.ts

@@ -1,46 +1,19 @@
+import {
+  type MaterialRenderProjection as AssetMaterialRenderProjection,
+  projectMaterialRecord,
+} from '@forgeax/engine-assets-runtime';
 import {
   type CookedMaterialRecord,
   materialLayerPlanIdentity,
 } from '@forgeax/engine-pack/material-cook';
-import type { MaterialValue, StandardLayerPlan } from '@forgeax/engine-types';
+import type { StandardLayerPlan } from '@forgeax/engine-types';
 import { projectStandardLayerPlan } from './standard-layer-projection.js';
 
-export interface MaterialRenderPassProjection {
-  readonly name: string;
-  readonly module: string;
-  readonly vertexEntry?: string;
-  readonly fragmentEntry?: string;
-  readonly moduleSlots?: Readonly<Record<string, string>>;
-  readonly renderState?: Readonly<Record<string, unknown>>;
-  readonly artifactHash: string;
-}
-
-export interface MaterialRenderProjection {
-  readonly materialGuid: string;
-  readonly specializationKey: string;
-  readonly artifactHash: string;
-  readonly passes: readonly MaterialRenderPassProjection[];
-  readonly runtimeValues: Readonly<Record<string, MaterialValue | null>>;
-  readonly staticSelection: readonly string[];
+export type { MaterialRenderPassProjection } from '@forgeax/engine-assets-runtime';
+export interface MaterialRenderProjection extends AssetMaterialRenderProjection {
   readonly layerPlan: StandardLayerPlan;
 }
 
-function projectPass(
-  record: CookedMaterialRecord,
-  pass: CookedMaterialRecord['resolved']['passes'][number],
-): MaterialRenderPassProjection {
-  const program = pass.program;
-  return {
-    name: pass.name,
-    module: program.module,
-    ...(program.vertexEntry === undefined ? {} : { vertexEntry: program.vertexEntry }),
-    ...(program.fragmentEntry === undefined ? {} : { fragmentEntry: program.fragmentEntry }),
-    ...(program.moduleSlots === undefined ? {} : { moduleSlots: program.moduleSlots }),
-    ...(pass.renderState === undefined ? {} : { renderState: pass.renderState }),
-    artifactHash: record.artifact.digest,
-  };
-}
-
 export function assembleMaterialProjection(record: CookedMaterialRecord): MaterialRenderProjection {
   const layerPlan = projectStandardLayerPlan(record.resolved.parameters, record.resolved.passes);
   const expectedLayerPlanIdentity = materialLayerPlanIdentity(record);
@@ -53,12 +26,7 @@ export function assembleMaterialProjection(record: CookedMaterialRecord): Materi
     );
   }
   return {
-    materialGuid: record.guid,
-    specializationKey: record.specializationKey ?? record.receipt.identity.programIdentity,
-    artifactHash: record.artifact.digest,
-    passes: record.resolved.passes.map((pass) => projectPass(record, pass)),
-    runtimeValues: record.resolved.values,
-    staticSelection: [],
+    ...projectMaterialRecord(record),
     layerPlan,
   };
 }

package/src/assembly/material/standard-layer-projection.ts

@@ -1,3 +1,4 @@
+import { isStandardRootModule } from '@forgeax/engine-pack';
 import type { MaterialParameter, MaterialPass, StandardLayerPlan } from '@forgeax/engine-types';
 import { deriveStandardLayerPlan } from '@forgeax/engine-types';
 
@@ -12,5 +13,6 @@ export function projectStandardLayerPlan(
   parameters: readonly MaterialParameter[],
   passes: readonly MaterialPass[],
 ): StandardLayerPlan {
-  return deriveStandardLayerPlan(parameters, passes);
+  const standard = passes.some((pass) => isStandardRootModule(pass.program.module));
+  return deriveStandardLayerPlan(standard ? parameters : [], standard ? passes : undefined);
 }

package/src/assembly/material/surface-projection.ts

@@ -0,0 +1,91 @@
+import { DEFAULT_STANDARD_SURFACE_MODULE } from '@forgeax/engine-shader';
+import type {
+  MaterialPass,
+  MaterialRenderState,
+  MaterialValue,
+  StandardLayerPlan,
+} from '@forgeax/engine-types';
+
+export const STANDARD_MATERIAL_MODULE = 'forgeax_material::standard';
+export { DEFAULT_STANDARD_SURFACE_MODULE };
+
+export type StandardSurfacePassName = 'forward' | 'deferred' | 'shadow-caster';
+export type StandardSurfaceGeometryVariant = 'rigid' | 'skinned' | 'instanced';
+export type StandardSurfaceLightingLane = 'direct' | 'clustered';
+export type StandardSurfaceKind = 'standard' | 'full-custom';
+
+export interface StandardSurfaceProjectionOptions {
+  readonly surfaceModule: string;
+  readonly values: Readonly<Record<string, MaterialValue | null>>;
+  readonly renderState?: MaterialRenderState;
+  readonly castShadow?: boolean;
+  readonly queue?: number;
+  readonly geometryVariant?: StandardSurfaceGeometryVariant;
+  readonly lightingLane?: StandardSurfaceLightingLane;
+  readonly alphaClip?: boolean;
+  readonly surfaceKind?: StandardSurfaceKind;
+  readonly declaredPasses?: readonly StandardSurfacePassName[];
+  readonly layerPlan?: StandardLayerPlan;
+}
+
+function pass(
+  name: StandardSurfacePassName,
+  options: StandardSurfaceProjectionOptions,
+  fragmentEntry: string,
+): MaterialPass {
+  const authoredState = options.renderState ?? {};
+  const authoredRecord = authoredState as Readonly<Record<string, unknown>>;
+  const tags = (authoredRecord.tags ?? {}) as Readonly<Record<string, string>>;
+  const lightMode =
+    name === 'shadow-caster' ? 'ShadowCaster' : name === 'forward' ? 'Forward' : 'Deferred';
+  return {
+    name,
+    program: {
+      module:
+        name === 'shadow-caster' ? 'forgeax::default-shadow-caster' : STANDARD_MATERIAL_MODULE,
+      fragmentEntry,
+      moduleSlots: { surface: options.surfaceModule },
+    },
+    renderState: {
+      ...authoredState,
+      tags:
+        options.surfaceModule === DEFAULT_STANDARD_SURFACE_MODULE
+          ? { LightMode: lightMode, ...tags }
+          : {
+              ...tags,
+              LightMode: lightMode,
+              SurfaceModule: options.surfaceModule,
+              SurfaceKind: options.surfaceKind ?? 'standard',
+              GeometryVariant: options.geometryVariant ?? 'rigid',
+              LightingLane: options.lightingLane ?? 'direct',
+              AlphaClip: options.alphaClip === true ? 'enabled' : 'disabled',
+            },
+      ...(options.queue === undefined ? {} : { queue: options.queue }),
+    },
+  };
+}
+
+/** Project one custom or default Surface into the existing Standard pass family. */
+export function projectStandardSurfacePasses(
+  options: StandardSurfaceProjectionOptions,
+): [MaterialPass, ...MaterialPass[]] {
+  const authoredPasses = options.declaredPasses;
+  const passNames: StandardSurfacePassName[] =
+    options.surfaceKind === 'full-custom' && authoredPasses !== undefined
+      ? [...authoredPasses]
+      : (['forward'] as StandardSurfacePassName[]);
+  if (authoredPasses === undefined || options.surfaceKind !== 'full-custom') {
+    const blended = options.renderState?.blend !== undefined;
+    if (!blended && options.layerPlan?.mode !== 'physical') passNames.push('deferred');
+    if (options.castShadow !== false) passNames.push('shadow-caster');
+  }
+  const entries = passNames.map((name) =>
+    pass(
+      name,
+      options,
+      name === 'forward' ? 'fs_main' : name === 'deferred' ? 'fs_gbuffer' : 'fs_shadow',
+    ),
+  );
+  const passes = entries as [MaterialPass, ...MaterialPass[]];
+  return passes;
+}