@forgeax/engine-render 0.1.24 → 0.1.26

package/src/__tests__/instances-store.unit.test.ts

@@ -0,0 +1,46 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { InstanceProjectionStore } from '../instances';
+
+function matrices(x: number): Float32Array {
+  return new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, 0, 0, 1]);
+}
+
+describe('renderer instance projection', () => {
+  it('derives independent complete snapshots for consumers that skip different updates', () => {
+    const world = new World();
+    const first = new InstanceProjectionStore();
+    const late = new InstanceProjectionStore();
+    const before = first.project(world, 1, matrices(0));
+    late.project(world, 1, matrices(0));
+    first.project(world, 1, matrices(1));
+    first.project(world, 1, matrices(2));
+    const latest = late.project(world, 1, matrices(2));
+    expect(before.transforms[12]).toBe(0);
+    expect(latest.transforms[12]).toBe(2);
+    const stable = late.project(world, 1, matrices(2));
+    expect(stable.transforms).toBe(latest.transforms);
+    expect(stable.revision).toBe(latest.revision);
+  });
+
+  it('does not alias identical entity numbers across World identities', () => {
+    const projection = new InstanceProjectionStore();
+    const a = projection.project(new World(), 1, matrices(10));
+    const b = projection.project(new World(), 1, matrices(99));
+    expect(a.collectionId).not.toBe(b.collectionId);
+    expect(a.transforms[12]).toBe(10);
+    expect(b.transforms[12]).toBe(99);
+  });
+
+  it('rebuilds from unchanged source after dropping renderer resources', () => {
+    const world = new World();
+    const transforms = matrices(4);
+    const projection = new InstanceProjectionStore();
+    projection.project(world, 1, transforms);
+    projection.dispose();
+    expect(projection.project(world, 1, transforms).transforms).toEqual(transforms);
+    expect(new InstanceProjectionStore().project(world, 1, transforms).transforms).toEqual(
+      transforms,
+    );
+  });
+});

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

@@ -2,10 +2,12 @@ import {
   createBuiltinMaterialAsset,
   DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
   DEFAULT_UNLIT_PARAM_SCHEMA,
+  STANDARD_PIPELINE_PARAM_SCHEMA,
 } from '@forgeax/engine-shader';
 import { resolveMaterialAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { Materials } from '../materials.js';
+import { materialParametersToParamSchema } from '../render-system-extract.js';
 
 describe('vertex color does not change the material contract', () => {
   it('keeps colored and plain materials on the same schema and resource identity', () => {
@@ -62,25 +64,58 @@ describe('vertex color does not change the material contract', () => {
     expect(material.values).toHaveProperty('ior', 1.5);
   });
 
+  it('routes canonical Standard roots through the complete runtime UBO schema', () => {
+    const material = Materials.standard({ baseColor: [1, 1, 1, 1] });
+    const authoredSchema = materialParametersToParamSchema(material.parameters ?? []);
+    const canonicalSchema = materialParametersToParamSchema(
+      material.parameters ?? [],
+      'forgeax::default-standard-pbr',
+    );
+
+    expect(authoredSchema.map((entry) => entry.name)).toEqual(
+      material.parameters?.map((parameter) => parameter.name),
+    );
+    expect(canonicalSchema).toBe(STANDARD_PIPELINE_PARAM_SCHEMA);
+    expect(authoredSchema).not.toBe(STANDARD_PIPELINE_PARAM_SCHEMA);
+  });
+
+  it('publishes the complete Standard contract when authoring a custom Surface', () => {
+    const custom = Materials.standard({
+      surfaceModule: 'project::paint',
+      parameters: [{ name: 'paintStrength', type: 'f32', default: 0.75 }],
+      values: { paintStrength: 0.5 },
+    });
+    const names = custom.parameters?.map((parameter) => parameter.name) ?? [];
+    expect(names).toEqual(
+      expect.arrayContaining([
+        'baseColor',
+        'metallic',
+        'roughness',
+        'baseColorTexture',
+        'paintStrength',
+      ]),
+    );
+    expect(new Set(names).size).toBe(names.length);
+    expect(custom.parameters?.find((parameter) => parameter.name === 'paintStrength')).toEqual({
+      name: 'paintStrength',
+      type: 'f32',
+      default: 0.75,
+    });
+    expect(custom.values).toEqual({ paintStrength: 0.5 });
+    expect(names).not.toContain('clearcoat');
+  });
+
   it('routes active transmission to Forward and ShadowCaster only', () => {
     const material = Materials.standard({ baseColor: [1, 1, 1, 1], transmission: 0.5 });
     expect(material.passes?.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
     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-static-dynamic-route.unit.test.ts → material-layer-projection.unit.test.ts}

@@ -1,14 +1,10 @@
 import type { CookedMaterialRecord } from '@forgeax/engine-pack';
 import { deriveStandardLayerPlan } from '@forgeax/engine-types';
-import { describe, expect, it, vi } from 'vitest';
+import { describe, expect, it } from 'vitest';
 import { assembleMaterialProjection } from '../assembly/material/assembly.js';
-import {
-  routeMaterialPipeline,
-  updateMaterialRuntimeValues,
-} from '../assembly/material/pipeline-projection.js';
 
 const record: CookedMaterialRecord = {
-  schemaVersion: 'material-cook/3',
+  schemaVersion: 'material-cook/4',
   guid: 'material-route',
   specializationKey: 'route-key',
   authored: {
@@ -24,14 +20,34 @@ const record: CookedMaterialRecord = {
     values: { baseColor: [1, 1, 1, 1], useNormalMap: false },
   },
   refs: { parent: [], textures: [], samplers: [], modules: ['project::standard'] },
-  artifact: {
-    mediaType: 'text/wgsl',
-    path: 'material-route.wgsl',
-    digest: 'sha256:route',
-    bytes: new Uint8Array([4]),
-  },
+  programs: [
+    {
+      specializationKey: 'route-program',
+      artifact: {
+        mediaType: 'text/wgsl',
+        path: 'material-route.wgsl',
+        digest: 'sha256:route',
+        bytes: new Uint8Array([4]),
+      },
+      selections: [
+        {
+          pass: 'forward',
+          context: {
+            backend: 'webgpu',
+            capability: 'storage-buffer',
+            pipeline: 'forward',
+            geometry: 'mesh',
+            pass: 'forward',
+            profile: 'forgeax-material-wgsl-v1',
+            toolchain: 'naga-oil',
+            instrumentation: 'none',
+          },
+        },
+      ],
+    },
+  ],
   receipt: {
-    schemaVersion: 'material-cook/3',
+    schemaVersion: 'material-cook/4',
     sourceClosure: ['project::standard'],
     profile: 'forgeax-material-wgsl-v1',
     compilerVersion: 'compiler/1',
@@ -59,7 +75,7 @@ const record: CookedMaterialRecord = {
   },
 };
 
-describe('cooked material static and dynamic routing', () => {
+describe('cooked material layer projection', () => {
   it('rejects a stale Standard layer plan before render projection', () => {
     const standardPass = { name: 'forward', program: { module: 'forgeax::default-standard-pbr' } };
     const standardResolved = { ...record.resolved, passes: [standardPass] };
@@ -87,37 +103,4 @@ describe('cooked material static and dynamic routing', () => {
       }),
     ).toThrow('Standard material layer-plan identity mismatch');
   });
-
-  it('updates runtime values without requesting a compile or changing the artifact key', () => {
-    const projection = assembleMaterialProjection(record);
-    const updated = updateMaterialRuntimeValues(projection, {
-      baseColor: [0.25, 0.5, 0.75, 1],
-    });
-
-    expect(updated.runtimeValues.baseColor).toEqual([0.25, 0.5, 0.75, 1]);
-    expect(updated.specializationKey).toBe(projection.specializationKey);
-  });
-
-  it('selects a cooked static specialization and returns a structured miss', () => {
-    const projection = assembleMaterialProjection(record);
-    const lookup = vi.fn((key: string) =>
-      key === 'route-key' ? { key, bytes: new Uint8Array([4]), digest: 'sha256:route' } : undefined,
-    );
-
-    const ready = routeMaterialPipeline({ projection, lookupArtifact: lookup });
-    expect(ready).toMatchObject({ kind: 'ready', specializationKey: 'route-key' });
-    expect(lookup).toHaveBeenCalledWith('route-key');
-
-    const missing = routeMaterialPipeline({
-      projection: { ...projection, specializationKey: 'uncooked-static-selection' },
-      lookupArtifact: lookup,
-    });
-    expect(missing).toMatchObject({
-      kind: 'error',
-      error: {
-        code: 'material-specialization-not-cooked',
-        detail: { specializationKey: 'uncooked-static-selection' },
-      },
-    });
-  });
 });

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-program-dispatch.unit.test.ts

@@ -0,0 +1,48 @@
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import type { MaterialPass } from '@forgeax/engine-types';
+import { expect, it } from 'vitest';
+import { appendMaterialDispatchEntries, type DispatchEntry } from '../render-system-extract.js';
+
+it('dispatches each Pass with its published program, including an Engine-authored shadow', () => {
+  const passes: MaterialPass[] = [
+    {
+      name: 'Forward',
+      program: { module: 'game::toon', vertexEntry: 'vs_main', fragmentEntry: 'fs_toon' },
+    },
+    {
+      name: 'ShadowCaster',
+      program: { module: 'forgeax::default-shadow-caster', vertexEntry: 'vs_shadow' },
+      renderState: { tags: { LightMode: 'ShadowCaster' } },
+    },
+  ];
+  const dispatch: DispatchEntry[] = [];
+  appendMaterialDispatchEntries(dispatch, passes, 1 as EntityHandle, 7, 0, 0, { amount: 0 }, 0, {
+    Forward: 'cooked-toon',
+    ShadowCaster: 'cooked-shadow',
+  });
+  expect(
+    dispatch.map((entry) => [entry.materialShaderId, entry.vertexEntry, entry.fragmentEntry]),
+  ).toEqual([
+    ['cooked-toon', 'vs_main', 'fs_toon'],
+    ['cooked-shadow', 'vs_shadow', undefined],
+  ]);
+  expect(
+    dispatch.every((entry) => entry.materialHandle === 7 && entry.paramSnapshot?.amount === 0),
+  ).toBe(true);
+});
+
+it('refuses an incomplete published Pass map instead of using an authored shader', () => {
+  expect(() =>
+    appendMaterialDispatchEntries(
+      [],
+      [{ name: 'ShadowCaster', program: { module: 'forgeax::default-shadow-caster' } }],
+      1 as EntityHandle,
+      7,
+      0,
+      0,
+      {},
+      0,
+      { Forward: 'cooked-toon' },
+    ),
+  ).toThrow('Missing published material program');
+});

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', () => {
@@ -601,10 +628,10 @@ describe('material shader binding contract', () => {
       'utf8',
     );
     const projectionSource = readFileSync(
-      resolve(import.meta.dirname, '../assembly/material/pipeline-projection.ts'),
+      resolve(import.meta.dirname, '../assembly/material/assembly.ts'),
       'utf8',
     );
-    expect(projectionSource).toContain('routeMaterialPipeline');
+    expect(projectionSource).toContain('projectMaterialRecord');
     expect(recordSource).not.toMatch(/internals\.assets\.get<MaterialAsset>/);
     expect(recordSource).not.toMatch(/firstMaterial as \{/);
     expect(recordSource).not.toContain('baseColorHandle');
@@ -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);