@forgeax/engine-render 0.1.24 → 0.1.25

package/src/__tests__/instances-world-ownership.integration.test.ts

@@ -0,0 +1,62 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { Camera } from '../components/camera';
+import { Instances } from '../components/instances';
+import { MeshFilter } from '../components/mesh-filter';
+import { MeshRenderer } from '../components/mesh-renderer';
+import { extractFrames } from '../render-system-extract';
+
+function matrices(count: number, x: number): Float32Array {
+  const out = new Float32Array(count * 16);
+  for (let i = 0; i < count; i++) {
+    out[i * 16] = out[i * 16 + 5] = out[i * 16 + 10] = out[i * 16 + 15] = 1;
+    out[i * 16 + 12] = x;
+  }
+  return out;
+}
+
+function scene(count: number, x: number) {
+  const world = new World();
+  registerPropagateTransforms(world);
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 5] } },
+      { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+    )
+    .unwrap();
+  const entity = world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: {} },
+      { component: Instances, data: { transforms: matrices(count, x) } },
+    )
+    .unwrap();
+  world.update(0).unwrap();
+  return { world, entity };
+}
+
+describe('World-owned instance authoring', () => {
+  it.each([1500, 10000, 20000])('extracts %s matrices without creating a Renderer', (count) => {
+    const { world } = scene(count, 0);
+    const snapshot = extractFrames([world], 0).renderables[0]?.instances;
+    expect(snapshot?.instanceCount).toBe(count);
+    expect(snapshot?.transforms).toEqual(matrices(count, 0));
+  });
+
+  it('keeps worlds isolated and lets independent consumers observe skipped updates', () => {
+    const a = scene(2, 0);
+    const b = scene(2, 1);
+    const before = extractFrames([a.world], 0).renderables[0]?.instances;
+    expect(extractFrames([b.world], 0).renderables[0]?.instances?.transforms[12]).toBe(1);
+    a.world.set(a.entity, Instances, { transforms: matrices(2, 0.5) }).unwrap();
+    extractFrames([a.world], 0);
+    a.world.set(a.entity, Instances, { transforms: matrices(2, -0.5) }).unwrap();
+    const late = extractFrames([a.world], 0).renderables[0]?.instances;
+    expect(late?.transforms[12]).toBe(-0.5);
+    expect(before?.transforms[12]).toBe(0);
+    expect(extractFrames([b.world], 0).renderables[0]?.instances?.transforms[12]).toBe(1);
+  });
+});

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

@@ -68,19 +68,11 @@ describe('vertex color does not change the material contract', () => {
     expect(material.passes?.[0]?.renderState).toMatchObject({ depthWriteEnabled: false });
   });
 
-  it.each([
-    [
-      'unlit',
-      Materials.unlit([1, 1, 1, 1], { renderState: { cullMode: 'none', frontFace: 'cw' } }),
-    ],
-    [
-      'standard',
-      Materials.standard({
-        baseColor: [1, 1, 1, 1],
-        renderState: { cullMode: 'none', frontFace: 'cw' },
-      }),
-    ],
-  ] as const)('projects the %s material raster orientation into its ShadowCaster pass', (_name, material) => {
+  it('projects the standard material raster orientation into its ShadowCaster pass', () => {
+    const material = Materials.standard({
+      baseColor: [1, 1, 1, 1],
+      renderState: { cullMode: 'none', frontFace: 'cw' },
+    });
     const shadowCaster = material.passes?.find((entry) => entry.name === 'shadow-caster');
     expect(shadowCaster?.renderState).toMatchObject({ cullMode: 'none', frontFace: 'cw' });
   });

package/src/__tests__/material-pass-policy.unit.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { Materials } from '../materials';
+
+const surface = {
+  surfaceModule: 'game_3d::rusted_iron_surface',
+  parameters: [
+    { name: 'ironColor', type: 'color' as const },
+    { name: 'alphaClipThreshold', type: 'f32' as const, optional: true },
+  ],
+  values: { ironColor: [0.4, 0.45, 0.47, 1], alphaClipThreshold: 0.5 },
+};
+
+describe('custom Standard Surface pass policy', () => {
+  it('keeps opaque and alpha-clip custom surfaces on Forward, Deferred, and ShadowCaster', () => {
+    const material = Materials.standard(surface as never);
+    expect(material.passes?.map((pass) => pass.name)).toEqual([
+      'forward',
+      'deferred',
+      'shadow-caster',
+    ]);
+  });
+
+  it('does not create Deferred for an explicitly blended custom surface', () => {
+    const material = Materials.standard({
+      ...surface,
+      renderState: { blend: { color: {}, alpha: {} } },
+    } as never);
+    expect(material.passes?.map((pass) => pass.name)).not.toContain('deferred');
+  });
+
+  it('does not create Deferred when the effective root declares a physical layer', () => {
+    const material = Materials.standard({
+      ...surface,
+      parameters: [
+        { name: 'clearcoat', type: 'f32' },
+        { name: 'clearcoatRoughness', type: 'f32' },
+      ],
+      values: { clearcoat: 0, clearcoatRoughness: 0.5 },
+    } as never);
+    expect(material.passes?.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+  });
+
+  it('keeps optional physical fields inactive until the root makes the fragment effective', () => {
+    const material = Materials.standard({
+      ...surface,
+      parameters: [
+        { name: 'clearcoat', type: 'f32', optional: true },
+        { name: 'clearcoatRoughness', type: 'f32', optional: true },
+      ],
+      values: { clearcoat: 0, clearcoatRoughness: 0.5 },
+    } as never);
+    expect(material.passes?.map((pass) => pass.name)).toEqual([
+      'forward',
+      'deferred',
+      'shadow-caster',
+    ]);
+  });
+
+  it('projects an explicitly declared default clearcoat root as Forward-only', () => {
+    const material = Materials.standard({
+      baseColor: [0.28, 0.035, 0.075, 1],
+      metallic: 0.12,
+      roughness: 0.18,
+      clearcoat: 0.82,
+      clearcoatRoughness: 0.08,
+    });
+    expect(material.passes?.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+  });
+});

package/src/__tests__/material-snapshot-mutation.integration.test.ts

@@ -3,7 +3,9 @@ import { World } from '@forgeax/engine-ecs';
 import { Transform } from '@forgeax/engine-scene';
 import type { ShaderRegistry } from '@forgeax/engine-shader';
 import type { MaterialAsset } from '@forgeax/engine-types';
+import { deriveStandardLayerPlan } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import { projectStandardSurfacePasses } from '../assembly/material/surface-projection';
 import { MeshFilter } from '../components/mesh-filter';
 import { MeshRenderer } from '../components/mesh-renderer';
 import { extractFrames, type MaterialSnapshotCachesByWorld } from '../render-system-extract';
@@ -50,4 +52,71 @@ describe('material snapshot mutation', () => {
     expect(second?.baseColor).toEqual(new Float32Array([0, 1, 0]));
     expect(second).not.toBe(first);
   });
+
+  it('keeps the pipeline identity stable for a value-only child update', () => {
+    const world = new World();
+    const assets = new AssetRegistry({
+      findMaterialArtifact: () => ({ ok: false, error: new Error('not registered') }),
+    } as unknown as ShaderRegistry);
+    const values: Record<string, unknown> = { baseColor: [1, 0, 0, 1] };
+    const material: MaterialAsset = {
+      kind: 'material',
+      passes: [
+        {
+          name: 'Forward',
+          program: { module: 'forgeax_material::standard' },
+          renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+        },
+      ],
+      values: values as NonNullable<MaterialAsset['values']>,
+    };
+    const materialHandle = world.allocSharedRef('MaterialAsset', material);
+    world.spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: { materials: [materialHandle] } },
+    );
+    const materialCaches: MaterialSnapshotCachesByWorld = new WeakMap();
+    const first = extractFrames([world], 0, assets, undefined, materialCaches).renderables[0];
+    values.baseColor = [0, 1, 0, 1];
+    const second = extractFrames([world], 0, assets, undefined, materialCaches).renderables[0];
+
+    expect(first?.gpuDrivenDraws?.[0]?.pipelineClass).toBe(
+      second?.gpuDrivenDraws?.[0]?.pipelineClass,
+    );
+    expect(first?.material?.materialShaderId).toBe(second?.material?.materialShaderId);
+  });
+
+  it('falsifies legacy surface, physical deferred, and forward fallback projections', () => {
+    const basePlan = deriveStandardLayerPlan([]);
+    const physicalPlan = deriveStandardLayerPlan([
+      { name: 'clearcoat', type: 'f32' },
+      { name: 'clearcoatRoughness', type: 'f32' },
+    ]);
+
+    const base = projectStandardSurfacePasses({
+      surfaceModule: 'game_3d::rusted_iron_surface',
+      values: {},
+      layerPlan: basePlan,
+      geometryVariant: 'rigid',
+      lightingLane: 'direct',
+    });
+    const physical = projectStandardSurfacePasses({
+      surfaceModule: 'game_3d::rusted_iron_surface',
+      values: {},
+      layerPlan: physicalPlan,
+      geometryVariant: 'rigid',
+      lightingLane: 'direct',
+    });
+    const legacy = base.map((entry) => ({
+      ...entry,
+      program: { ...entry.program, moduleSlots: { surface: 'legacy::surface_data' } },
+    }));
+    const physicalDeferred = physical.some((entry) => entry.name === 'deferred');
+    const forwardFallback = base.some((entry) => entry.name === 'forward');
+
+    expect(legacy[0]?.program.moduleSlots?.surface).not.toBe('game_3d::rusted_iron_surface');
+    expect(physicalDeferred).toBe(false);
+    expect(forwardFallback).toBe(true);
+  });
 });

package/src/__tests__/material-surface-authoring.test-d.ts

@@ -0,0 +1,62 @@
+import type { MaterialAsset } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+import {
+  type CustomStandardSurfaceOptions,
+  type DefaultStandardOptions,
+  Materials,
+  type StandardOptions,
+} from '../materials';
+
+const parameters = [{ name: 'ironColor', type: 'color' as const }];
+const values = { ironColor: [0.4, 0.45, 0.47, 1] as const };
+
+describe('Standard Surface authoring union', () => {
+  it('exposes one callable Parameters union for default and custom options', () => {
+    const defaultOptions = { baseColor: [1, 1, 1, 1] as const } satisfies DefaultStandardOptions;
+    const customOptions = {
+      surfaceModule: 'game_3d::rusted_iron_surface',
+      parameters,
+      values,
+    } satisfies CustomStandardSurfaceOptions;
+    expectTypeOf<Parameters<typeof Materials.standard>[0]>().toEqualTypeOf<StandardOptions>();
+
+    function acceptStandard<T extends StandardOptions>(options: T): T {
+      return options;
+    }
+
+    acceptStandard(defaultOptions);
+    acceptStandard(customOptions);
+  });
+
+  it('accepts a custom Surface without convenience fields', () => {
+    const options = {
+      surfaceModule: 'game_3d::rusted_iron_surface',
+      parameters,
+      values,
+      castShadow: true,
+    } satisfies CustomStandardSurfaceOptions;
+    const material = Materials.standard(options);
+    expectTypeOf(material.passes?.[0]?.program.moduleSlots?.surface).toBeString;
+  });
+
+  it('keeps default and custom options mutually exclusive', () => {
+    expectTypeOf<DefaultStandardOptions>().toHaveProperty('baseColor');
+    Materials.standard({
+      surfaceModule: 'game_3d::rusted_iron_surface',
+      parameters,
+      values,
+      // @ts-expect-error Custom Surface options cannot add Standard convenience fields.
+      baseColor: [1, 1, 1, 1],
+    });
+  });
+
+  it('keeps custom Surface parameters sparse and root-owned', () => {
+    const custom = Materials.standard({
+      surfaceModule: 'game_3d::rusted_iron_surface',
+      parameters,
+      values,
+    });
+    expectTypeOf(custom.parameters).toEqualTypeOf<MaterialAsset['parameters']>();
+    expectTypeOf(custom.values).toEqualTypeOf<MaterialAsset['values']>();
+  });
+});

package/src/__tests__/materials-transmission-validation.unit.test.ts

@@ -33,4 +33,28 @@ describe('Materials.standard transmission validation', () => {
       }),
     ).toThrow(MaterialTransmissionContractError);
   });
+
+  it('preserves the typed physical contract error for incomplete custom layers', () => {
+    const options = {
+      surfaceModule: 'game_3d::custom_surface',
+      parameters: [{ name: 'clearcoat', type: 'f32' as const }],
+      values: { clearcoat: 0.5 },
+    };
+
+    expect(() => Materials.standard(options as never)).toThrow(Error);
+    try {
+      Materials.standard(options as never);
+    } catch (error) {
+      expect(error).toMatchObject({
+        code: 'material-physical-contract-invalid',
+        detail: {
+          code: 'material-physical-contract-invalid',
+          material: 'Standard',
+          layer: 'clearcoat',
+          missing: ['clearcoatRoughness'],
+          reason: 'incomplete-layer',
+        },
+      });
+    }
+  });
 });

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

@@ -47,10 +47,6 @@ const featureBufferSources = [
     source: readFileSync(new URL('../record/main-pass-sprite-draws.ts', import.meta.url), 'utf8'),
     names: ['GPU_BUFFER_USAGE_STORAGE', 'GPU_BUFFER_USAGE_UNIFORM', 'GPU_BUFFER_USAGE_COPY_DST'],
   },
-  {
-    source: readFileSync(new URL('../record/shadow-pass.ts', import.meta.url), 'utf8'),
-    names: ['GPU_BUFFER_USAGE_STORAGE', 'GPU_BUFFER_USAGE_UNIFORM', 'GPU_BUFFER_USAGE_COPY_DST'],
-  },
   {
     source: readFileSync(new URL('../systems/skin-palette-allocator.ts', import.meta.url), 'utf8'),
     names: ['GPU_BUFFER_USAGE_STORAGE', 'GPU_BUFFER_USAGE_UNIFORM', 'GPU_BUFFER_USAGE_COPY_DST'],

package/src/__tests__/renderer-factory-material-contract.unit.test.ts

@@ -8,7 +8,9 @@ import {
   allowsUnlitPreparedFallback,
   isSharedMaterialUserRegionCompatible,
   normalizeMaterialShaderVariantSet,
+  resolveMaterialShaderBackendArtifactKey,
   resolveMaterialShaderBindingContract,
+  resolveMaterialShaderUvSetCount,
   resolveMaterialShaderVariantSet,
   resolveMaterialShaderVertexInputContract,
   selectNoColorPbrVariant,
@@ -390,6 +392,31 @@ describe('material shader variant identity', () => {
     ).toBe('STORAGE_BUFFER_AVAILABLE=true');
     expect(normalizeMaterialShaderVariantSet('CUSTOM=true', undefined)).toBe('CUSTOM=true');
   });
+
+  it('projects a published Surface artifact to its WebGL2 capability alias', () => {
+    const base = 'surface-specialization';
+    const webgl2 = 'forgeax::surface-variant::surface-specialization::webgl2::uniform-fallback';
+    const artifact = {
+      metadata: {
+        variants: [
+          {
+            backend: 'webgpu',
+            capability: 'storage-buffer',
+            specializationKey: base,
+          },
+          {
+            backend: 'webgl2',
+            capability: 'uniform-fallback',
+            specializationKey: webgl2,
+          },
+        ],
+      },
+    };
+
+    expect(resolveMaterialShaderBackendArtifactKey(base, 'wgpu-webgl2', artifact)).toBe(webgl2);
+    expect(resolveMaterialShaderBackendArtifactKey(base, 'webgpu', artifact)).toBe(base);
+    expect(resolveMaterialShaderBackendArtifactKey(base, 'wgpu-webgl2', undefined)).toBe(base);
+  });
 });
 
 describe('temporal material PSO creation contract', () => {
@@ -754,6 +781,21 @@ describe('material shader vertex input contract', () => {
     expect(resolveMaterialShaderVertexInputContract(source)).toBe('none');
   });
 
+  it('derives authored Standard UV aliases from the vertex input struct', () => {
+    const source = `
+      struct VsIn {
+        @location(0) position: vec3<f32>,
+        @location(2) uv: vec2<f32>,
+        @location(6) uv1_: vec2<f32>,
+        @location(12) uv7_: vec2<f32>,
+      }
+      struct VsOut { @builtin(position) position: vec4<f32> }
+      @vertex fn vs_main(input: VsIn) -> VsOut { var out: VsOut; return out }
+    `;
+
+    expect(resolveMaterialShaderUvSetCount(source)).toBe(8);
+  });
+
   it('keeps an explicit prepared vertex layout on a missing shader', () => {
     expect(allowsUnlitPreparedFallback(null, undefined)).toBe(true);
     expect(allowsUnlitPreparedFallback(null, 'position-size-color-instance', 'forward')).toBe(true);

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 the dispatch material handle, snapshot, and frame slot together', () => {
+    const paramSnapshot = { alphaClipThreshold: 0.4 };
+    const context = {
+      dispatch: [
+        {
+          renderableIndex: 4,
+          materialHandle: 42,
+          materialShaderId: 'forgeax::default-standard-pbr',
+          paramSnapshot,
+          tags: { LightMode: 'ShadowCaster' },
+        },
+      ],
+      validatedOrdered: [{ renderableIndex: 4 }],
+      materialSlotIndices: [[3, 7]],
+      materialSlots: Array.from({ length: 8 }, (_, slot) => ({
+        materialHandle: slot === 7 ? 42 : 11,
+      })),
+    } as never;
+
+    const bindings = shadowShaderMap(context);
+    expect(bindings.get(4)?.get(42)).toMatchObject({
+      materialHandle: 42,
+      materialShaderId: SHADOW_CASTER_SHADER_ID,
+      materialSlot: 7,
+      paramSnapshot,
+    });
+  });
 });

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);
+    }
+  });
+});