@forgeax/engine-render 0.1.23 → 0.1.25

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

@@ -36,15 +36,30 @@ describe('vertex color does not change the material contract', () => {
 
   it('keeps the standard authoring parameters derived from the shared schema', () => {
     const material = Materials.standard({ baseColor: [1, 1, 1, 1] });
-    expect(material.parameters?.map((parameter) => parameter.name)).toEqual(
-      DEFAULT_STANDARD_PBR_PARAM_SCHEMA.map((entry) => entry.name),
-    );
-    expect(material.values).toMatchObject({
-      transmission: 0,
-      ior: 1.5,
-      thickness: 0,
-      attenuationColor: [1, 1, 1],
-    });
+    expect(material.parameters?.map((parameter) => parameter.name)).toEqual([
+      'baseColor',
+      'metallic',
+      'roughness',
+      'metallicChannel',
+      'roughnessChannel',
+      'aoChannel',
+      'extraChannel',
+      'emissive',
+      'emissiveIntensity',
+      'occlusionStrength',
+      'alphaCutoff',
+      'specular',
+      'specularColor',
+      'normalScale',
+      'ior',
+      'baseColorTexture',
+      'metallicRoughnessTexture',
+      'normalTexture',
+      'emissiveTexture',
+      'occlusionTexture',
+    ]);
+    expect(material.values).not.toHaveProperty('transmission');
+    expect(material.values).toHaveProperty('ior', 1.5);
   });
 
   it('routes active transmission to Forward and ShadowCaster only', () => {
@@ -53,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-cooked-projection.unit.test.ts

@@ -1,8 +1,10 @@
 import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '@forgeax/engine-shader';
+import type { MaterialParameter, MaterialPass } from '@forgeax/engine-types';
 import { derive } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import { projectStandardLayerPlan } from '../assembly/material/standard-layer-projection.js';
 
-describe('standard material cooked projection', () => {
+describe('cooked material render projection', () => {
   it('uses one schema for reflection, uniform layout, and resource bindings', () => {
     const derived = derive(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);
     const names = derived.numericMembers.map((member) => member.name);
@@ -19,4 +21,20 @@ describe('standard material cooked projection', () => {
       ]),
     );
   });
+
+  it('projects the prepared contract without reading authored values', () => {
+    const parameters: readonly MaterialParameter[] = [
+      { name: 'baseColor', type: 'color' },
+      { name: 'metallic', type: 'f32' },
+      { name: 'roughness', type: 'f32' },
+    ];
+    const passes: readonly MaterialPass[] = [
+      { name: 'forward', program: { module: 'forgeax_material::standard' } },
+      { name: 'deferred', program: { module: 'forgeax_material::standard' } },
+      { name: 'shadow-caster', program: { module: 'forgeax_material::standard' } },
+    ];
+    const plan = projectStandardLayerPlan(parameters, passes);
+    expect(plan.mode).toBe('base-only');
+    expect(plan.passFamily).toEqual(['forward', 'deferred', 'shadow']);
+  });
 });

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-static-dynamic-route.unit.test.ts

@@ -1,4 +1,5 @@
 import type { CookedMaterialRecord } from '@forgeax/engine-pack';
+import { deriveStandardLayerPlan } from '@forgeax/engine-types';
 import { describe, expect, it, vi } from 'vitest';
 import { assembleMaterialProjection } from '../assembly/material/assembly.js';
 import {
@@ -59,6 +60,34 @@ const record: CookedMaterialRecord = {
 };
 
 describe('cooked material static and dynamic routing', () => {
+  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] };
+    const expected = deriveStandardLayerPlan(
+      standardResolved.parameters,
+      standardResolved.passes,
+    ).identity;
+    const standardRecord = {
+      ...record,
+      resolved: standardResolved,
+      receipt: {
+        ...record.receipt,
+        derivedInterface: { layoutIdentity: 'sha256:layout', layerPlanIdentity: expected },
+      },
+    } as CookedMaterialRecord;
+
+    expect(assembleMaterialProjection(standardRecord).layerPlan.identity).toBe(expected);
+    expect(() =>
+      assembleMaterialProjection({
+        ...standardRecord,
+        receipt: {
+          ...standardRecord.receipt,
+          derivedInterface: { layoutIdentity: 'sha256:layout', layerPlanIdentity: 'stale' },
+        },
+      }),
+    ).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, {

package/src/__tests__/material-stride-surface.unit.test.ts

@@ -4,7 +4,7 @@ import { MATERIAL_PER_ENTITY_STRIDE } from '../render-system';
 
 const ownerSource = readFileSync(new URL('../record/render-context.ts', import.meta.url), 'utf8');
 const rendererFactorySource = readFileSync(
-  new URL('../assembly/factory.ts', import.meta.url),
+  new URL('../assembly/webgpu-ready.ts', import.meta.url),
   'utf8',
 );
 const recordSources = [
@@ -16,8 +16,12 @@ const recordSources = [
 
 describe('material dynamic-offset stride surface', () => {
   it('keeps one internal owner and routes every record path through it', () => {
-    expect(MATERIAL_PER_ENTITY_STRIDE).toBe(512);
-    expect(ownerSource.match(/export const MATERIAL_PER_ENTITY_STRIDE\s*=\s*512/g)).toHaveLength(1);
+    expect(MATERIAL_PER_ENTITY_STRIDE).toBe(768);
+    expect(
+      ownerSource.match(
+        /export const MATERIAL_PER_ENTITY_STRIDE\s*=\s*Math\.ceil\(STANDARD_PBR_UBO_SIZE \/ 256\) \* 256/g,
+      ),
+    ).toHaveLength(1);
 
     for (const source of recordSources) {
       expect(source).toContain('MATERIAL_PER_ENTITY_STRIDE');

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-standard-contract.unit.test.ts

@@ -0,0 +1,104 @@
+import type { Buffer, Sampler, TextureView } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import { assembleMaterialWithSkylightEntries } from '../ibl/skylight-bind-group.js';
+import { Materials } from '../materials.js';
+
+describe('Materials.standard clearcoat public contract', () => {
+  it('declares clearcoat only when the physical root is authored', () => {
+    const base = Materials.standard({ baseColor: [1, 1, 1, 1] });
+    const zero = Materials.standard({ baseColor: [1, 1, 1, 1], clearcoat: 0 });
+    expect(base.parameters?.map((parameter) => parameter.name)).not.toContain('clearcoat');
+    expect(zero.parameters?.map((parameter) => parameter.name)).toContain('clearcoat');
+    expect(zero.passes?.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+  });
+
+  it('uses the R, G, and RG channel matrix without a guessed UV set', () => {
+    const options = {
+      baseColor: [1, 1, 1, 1] as const,
+      clearcoat: 0.5,
+      clearcoatRoughness: 0.25,
+      clearcoatTexture: 1,
+      clearcoatRoughnessTexture: 2,
+      clearcoatNormalTexture: 3,
+      clearcoatNormalScale: 0.75,
+    } as Parameters<typeof Materials.standard>[0] & Record<string, unknown>;
+    const material = Materials.standard(options);
+    expect(material.values).toMatchObject(options);
+    expect(material.values).not.toHaveProperty('clearcoatTexCoord');
+  });
+
+  it('keeps scalar clearcoat identity without charging unauthored map slots', () => {
+    const scalar = Materials.standard({
+      baseColor: [1, 1, 1, 1],
+      clearcoat: 0,
+      clearcoatRoughness: 0.5,
+      clearcoatNormalScale: 1,
+    });
+    const names = scalar.parameters?.map((parameter) => parameter.name) ?? [];
+    expect(names).toEqual(expect.arrayContaining(['clearcoat', 'clearcoatRoughness']));
+    expect(names).not.toEqual(
+      expect.arrayContaining([
+        'clearcoatTexture',
+        'clearcoatRoughnessTexture',
+        'clearcoatNormalTexture',
+      ]),
+    );
+  });
+
+  it('declares each clearcoat map slot only when its root value is authored', () => {
+    const material = Materials.standard({
+      baseColor: [1, 1, 1, 1],
+      clearcoat: 1,
+      clearcoatTexture: 1,
+      clearcoatNormalTexture: 2,
+    });
+    const names = material.parameters?.map((parameter) => parameter.name) ?? [];
+    expect(names).toEqual(expect.arrayContaining(['clearcoatTexture', 'clearcoatNormalTexture']));
+    expect(names).not.toContain('clearcoatRoughnessTexture');
+  });
+
+  it('keeps physical scalar fields before texture coordinate records', () => {
+    const material = Materials.standard({
+      baseColor: [1, 1, 1, 1],
+      clearcoat: 0.5,
+      clearcoatRoughness: 0.25,
+      clearcoatTexture: 1,
+    });
+    const names = material.parameters?.map((parameter) => parameter.name) ?? [];
+    expect(names.indexOf('clearcoat')).toBeLessThan(names.indexOf('baseColorTexture'));
+    expect(names.indexOf('clearcoatRoughness')).toBeLessThan(names.indexOf('baseColorTexture'));
+  });
+
+  it('keeps authored clearcoat map pairs contiguous after the material ABI', () => {
+    const sampler = {} as Sampler;
+    const view = {} as TextureView;
+    const entries = Array.from({ length: 17 }, (_, binding) => ({
+      binding,
+      resource:
+        binding === 0
+          ? { kind: 'buffer' as const, value: { buffer: {} as Buffer } }
+          : binding % 2 === 1
+            ? { kind: 'sampler' as const, value: sampler }
+            : { kind: 'textureView' as const, value: view },
+    }));
+    const merged = assembleMaterialWithSkylightEntries(
+      entries,
+      {
+        irradianceView: view,
+        irradianceSampler: sampler,
+        prefilterView: view,
+        prefilterSampler: sampler,
+        brdfLutView: view,
+        brdfLutSampler: sampler,
+        intensityBuffer: {} as Buffer,
+      },
+      undefined,
+      [
+        { slot: 0, sampler, view },
+        { slot: 1, sampler, view },
+        { slot: 2, sampler, view },
+      ],
+    );
+    expect(merged.slice(-6).map((entry) => entry.binding)).toEqual([26, 27, 28, 29, 30, 31]);
+  });
+});

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

@@ -14,7 +14,7 @@ import {
 const ownerSource = readFileSync(new URL('../gpu-usage.ts', import.meta.url), 'utf8');
 const meshSsboSource = readFileSync(new URL('../record/mesh-ssbo.ts', import.meta.url), 'utf8');
 const rendererFactorySource = readFileSync(
-  new URL('../assembly/factory.ts', import.meta.url),
+  new URL('../assembly/webgpu-ready.ts', import.meta.url),
   'utf8',
 );
 const consumerSources = [
@@ -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__/physical-clearcoat.integration.test.ts

@@ -0,0 +1,89 @@
+import { STANDARD_PIPELINE_PARAM_SCHEMA } from '@forgeax/engine-shader';
+import { describe, expect, it } from 'vitest';
+import { Materials } from '../materials.js';
+import {
+  buildBindGroupLayoutDescriptor,
+  materialBindGroupLayoutIdentity,
+} from '../pbr-pipeline.js';
+
+describe('Standard clearcoat root contract', () => {
+  it('keeps a declared factor-zero clearcoat physical and forward-only', () => {
+    const material = Materials.standard({ baseColor: [1, 1, 1, 1], clearcoat: 0 });
+    expect(material.passes?.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+    expect(material.parameters?.map((parameter) => parameter.name)).toContain('clearcoat');
+    expect(material.values).toMatchObject({ clearcoat: 0 });
+  });
+
+  it('retains a single root identity when coat maps are present', () => {
+    const options = {
+      baseColor: [1, 1, 1, 1] as const,
+      clearcoat: 0.8,
+      clearcoatRoughness: 0.2,
+      clearcoatTexture: 11,
+      clearcoatRoughnessTexture: 12,
+      clearcoatNormalTexture: 13,
+      clearcoatNormalScale: 0.5,
+    } as Parameters<typeof Materials.standard>[0] & Record<string, unknown>;
+    const material = Materials.standard(options);
+    expect(material.values).toMatchObject({
+      clearcoat: 0.8,
+      clearcoatRoughness: 0.2,
+      clearcoatTexture: 11,
+      clearcoatRoughnessTexture: 12,
+      clearcoatNormalTexture: 13,
+      clearcoatNormalScale: 0.5,
+    });
+  });
+
+  it('keys equivalent schema instances by the same merged layout identity', () => {
+    const withTexture = (name: string) => [
+      ...STANDARD_PIPELINE_PARAM_SCHEMA,
+      { name, type: 'texture2d' as const },
+    ];
+    const rigidR = withTexture('clearcoatTexture');
+    const rigidRClone = [...rigidR];
+    const rigidG = withTexture('clearcoatRoughnessTexture');
+    const rigidRg = [...rigidR, { name: 'clearcoatNormalTexture', type: 'texture2d' as const }];
+
+    expect(materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidR)).toBe(
+      materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidRClone),
+    );
+    expect(materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidR)).not.toBe(
+      materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidG),
+    );
+    expect(materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidR)).not.toBe(
+      materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidRg),
+    );
+  });
+
+  it('keeps the built-in Standard IBL ABI stable when physical maps are appended', () => {
+    const schema = [
+      ...STANDARD_PIPELINE_PARAM_SCHEMA,
+      { name: 'clearcoatTexture', type: 'texture2d' as const },
+      { name: 'clearcoatNormalTexture', type: 'texture2d' as const },
+    ];
+    const descriptor = buildBindGroupLayoutDescriptor(
+      {
+        shader: { id: 'forgeax::default-standard-pbr', passKind: 'forward', variantSet: undefined },
+        attachments: { colorFormats: [], depthFormat: undefined, sampleCount: 1 },
+        geometry: { topology: 'triangle-list', vertexLayout: {} },
+        renderState: undefined,
+      },
+      { kind: 'pbr-material-merged', materialParamSchema: schema },
+    );
+
+    // The canonical seven texture pairs occupy bindings 1..14. IBL remains
+    // at 15..21 and transmission at 22..23; authored physical maps append at
+    // 24..27. Compacting the authored root here shifts WGSL IBL bindings and
+    // causes Dawn to reject the pipeline before any pixels are submitted.
+    expect(descriptor.entries).toHaveLength(28);
+    expect(descriptor.entries.slice(0, 15).map((entry) => entry.binding)).toEqual(
+      Array.from({ length: 15 }, (_, binding) => binding),
+    );
+    expect(descriptor.entries[15]?.texture).toMatchObject({ viewDimension: 'cube' });
+    expect(descriptor.entries[17]?.texture).toMatchObject({ viewDimension: 'cube' });
+    expect(descriptor.entries[22]?.sampler).toMatchObject({ type: 'filtering' });
+    expect(descriptor.entries[23]?.texture).toMatchObject({ viewDimension: '2d' });
+    expect(descriptor.entries.slice(24).map((entry) => entry.binding)).toEqual([24, 25, 26, 27]);
+  });
+});

package/src/__tests__/prepared-gpu-driven-pbr.integration.test.ts

@@ -8,7 +8,7 @@ const textureNames = [
   'baseColorTexture',
   'metallicRoughnessTexture',
   'normalTexture',
-  'specularTintTexture',
+  'specularColorTexture',
   'emissiveTexture',
   'occlusionTexture',
   'transmissionTexture',

package/src/__tests__/prepared-graphics-pipeline-warmup.unit.test.ts

@@ -15,7 +15,7 @@ describe('prepared graphics material pipeline warmup', () => {
   });
 
   it('keeps view-only material bindings on the canonical view group with depth', () => {
-    const declaration = ownerSource.indexOf('const preparedViewOnlyPipelines');
+    const declaration = ownerSource.indexOf('preparedViewOnlyPipelines: new WeakSet()');
     const classification = ownerSource.indexOf('preparedViewOnlyPipelines.add', declaration);
     const bindingResolution = ownerSource.indexOf(
       'preparedViewOnlyPipelines.has(pipeline as object)',

package/src/__tests__/recover-error-policy-owner.unit.test.ts

@@ -14,14 +14,14 @@ const evidence = [
   {
     code: 'recover-not-needed',
     expected:
-      'renderer is healthy; call health() first to confirm degraded state before calling recover()',
-    hint: 'call health() first to confirm degraded state before calling recover()',
+      'renderer is healthy; use state() or inspect() to confirm degraded state before calling recover()',
+    hint: 'use state() or inspect().state to confirm degraded state before calling recover()',
     message: 'recover-not-needed: renderer is not in a degraded state',
   },
   {
     code: 'recover-not-implemented',
     expected: 'recovery is not yet implemented; self-heal lands in S5',
-    hint: 'self-heal recovery lands in S5; health().reason still reflects the degraded state',
+    hint: 'self-heal recovery lands in S5; inspect().state still reflects the lifecycle state',
     message: 'recover-not-implemented: self-heal recovery is not yet implemented',
   },
   {
@@ -47,6 +47,9 @@ describe('RecoverError policy ownership', () => {
 
     expect(source).toContain('export type RecoverErrorCode = keyof typeof RECOVER_ERROR_POLICY;');
     expect(source).not.toMatch(/export type RecoverErrorCode = 'recover-/);
+    expect(source).not.toContain('health()');
+    expect(source).toContain('state()');
+    expect(source).toContain('inspect()');
   });
 
   it('preserves the exact four-code vocabulary and order', () => {