@forgeax/engine-gltf 0.1.23 → 0.1.24

package/src/__tests__/physical-material-import.integration.test.ts

@@ -0,0 +1,239 @@
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import {
+  ImporterRegistry,
+  type ImportRunnerFs,
+  type RunImportMeta,
+  runImport,
+} from '@forgeax/engine-import';
+import type { TextureAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { gltfImporter } from '../gltf-importer.js';
+
+const SOURCE = 'physical-material.gltf';
+const TINY_PNG_BASE64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGP4//8/AAX+Av4N70a4AAAAAElFTkSuQmCC';
+
+const MATERIAL_GUID = '019f0000-0000-7000-8000-000000000100';
+const TEXTURE_GUIDS = [
+  '019f0000-0000-7000-8000-000000000101',
+  '019f0000-0000-7000-8000-000000000102',
+  '019f0000-0000-7000-8000-000000000103',
+  '019f0000-0000-7000-8000-000000000104',
+  '019f0000-0000-7000-8000-000000000105',
+] as const;
+const SAMPLER_GUIDS = [
+  '019f0000-0000-7000-8000-000000000106',
+  '019f0000-0000-7000-8000-000000000107',
+  '019f0000-0000-7000-8000-000000000108',
+  '019f0000-0000-7000-8000-000000000109',
+  '019f0000-0000-7000-8000-00000000010a',
+] as const;
+
+function dataUri(): string {
+  return `data:image/png;base64,${TINY_PNG_BASE64}`;
+}
+
+function sourceBytes(): Uint8Array {
+  const textures = TEXTURE_GUIDS.map((_guid, index) => ({ source: index, sampler: index }));
+  return new TextEncoder().encode(
+    JSON.stringify({
+      asset: { version: '2.0' },
+      extensionsUsed: [
+        'KHR_materials_clearcoat',
+        'KHR_materials_anisotropy',
+        'KHR_materials_sheen',
+        'KHR_materials_iridescence',
+        'KHR_materials_specular',
+      ],
+      materials: [
+        {
+          name: 'PhysicalSurface',
+          pbrMetallicRoughness: {
+            baseColorFactor: [0.8, 0.7, 0.6, 1],
+            metallicFactor: 0.1,
+            roughnessFactor: 0.35,
+          },
+          extensions: {
+            KHR_materials_clearcoat: {
+              clearcoatFactor: 0.75,
+              clearcoatRoughnessFactor: 0.2,
+              clearcoatNormalTexture: { index: 0 },
+            },
+            KHR_materials_anisotropy: {
+              anisotropyStrength: 0.5,
+              anisotropyRotation: 0.25,
+              anisotropyTexture: { index: 1 },
+            },
+            KHR_materials_sheen: {
+              sheenColorFactor: [0.2, 0.1, 0.05],
+              sheenRoughnessFactor: 0.3,
+              sheenColorTexture: { index: 2 },
+            },
+            KHR_materials_iridescence: {
+              iridescenceFactor: 0.6,
+              iridescenceIor: 1.4,
+              iridescenceThicknessMinimum: 120,
+              iridescenceThicknessMaximum: 380,
+              iridescenceTexture: { index: 3 },
+            },
+            KHR_materials_specular: {
+              specularFactor: 0.8,
+              specularColorFactor: [0.9, 0.85, 0.75],
+              specularColorTexture: { index: 4 },
+            },
+          },
+        },
+      ],
+      textures,
+      samplers: [{}, {}, {}, {}, {}],
+      images: TEXTURE_GUIDS.map(() => ({ uri: dataUri(), mimeType: 'image/png' })),
+      scenes: [],
+      nodes: [],
+      meshes: [],
+    }),
+  );
+}
+
+function meta(): RunImportMeta {
+  return {
+    importer: 'gltf',
+    source: SOURCE,
+    subAssets: [
+      {
+        guid: MATERIAL_GUID,
+        sourceIndex: 0,
+        sourceKey: 'material/physical-surface',
+        kind: 'material',
+      },
+      ...TEXTURE_GUIDS.map((guid, sourceIndex) => ({
+        guid,
+        sourceIndex,
+        sourceKey: `texture/${sourceIndex}`,
+        kind: 'texture' as const,
+      })),
+      ...SAMPLER_GUIDS.map((guid, sourceIndex) => ({
+        guid,
+        sourceIndex,
+        sourceKey: `sampler/${sourceIndex}`,
+        kind: 'sampler' as const,
+      })),
+    ],
+  };
+}
+
+function decodeBase64(value: string): Uint8Array {
+  const binary = atob(value);
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+
+function fs(): ImportRunnerFs {
+  return {
+    readSource: async (sourcePath) =>
+      sourcePath === SOURCE
+        ? { ok: true, value: sourceBytes() }
+        : { ok: false, error: new Error(`unexpected source path ${sourcePath}`) },
+    decodeImage: async (_bytes, _mimeType, settings) => {
+      const colorSpace = settings.colorSpace === 'srgb' ? 'srgb' : 'linear';
+      const texture: TextureAsset = {
+        kind: 'texture',
+        shape: { viewDimension: '2d', extent: { width: 1, height: 1 } },
+        format: colorSpace === 'srgb' ? 'rgba8unorm-srgb' : 'rgba8unorm',
+        data: new Uint8Array([128, 96, 64, 255]),
+        colorSpace,
+        mips: { kind: 'generate' },
+      };
+      return {
+        ok: true,
+        value: {
+          texture,
+          bytes: decodeBase64(TINY_PNG_BASE64),
+          mediaType: 'image/png',
+          assetCodec: { name: 'rgba8', version: '1' },
+        },
+      };
+    },
+  };
+}
+
+describe('glTF physical material importer route', () => {
+  it('carries all five KHR layers from importer through pack and runtime material parsing', async () => {
+    const importers = new ImporterRegistry();
+    importers.register(gltfImporter);
+
+    const result = await runImport(meta(), importers, fs());
+    expect(result.ok).toBe(true);
+    if (!result.ok || 'skipped' in result.value)
+      throw new Error('physical import did not publish a pack');
+
+    expect(result.value.pack.assets).toHaveLength(11);
+    expect(result.value.cookProducts).toHaveLength(11);
+    expect(result.value.cookProducts.every((product) => product.receipt !== undefined)).toBe(true);
+
+    const material = result.value.pack.assets.find((asset) => asset.guid === MATERIAL_GUID);
+    if (material === undefined) throw new Error('physical material pack row missing');
+    expect(material.refs).toEqual([
+      TEXTURE_GUIDS[0],
+      SAMPLER_GUIDS[0],
+      TEXTURE_GUIDS[1],
+      SAMPLER_GUIDS[1],
+      TEXTURE_GUIDS[2],
+      SAMPLER_GUIDS[2],
+      TEXTURE_GUIDS[3],
+      SAMPLER_GUIDS[3],
+      TEXTURE_GUIDS[4],
+      SAMPLER_GUIDS[4],
+    ]);
+
+    const payload = material.payload;
+    const parameterNames = new Set(
+      (payload.parameters as readonly { name: string }[]).map((parameter) => parameter.name),
+    );
+    for (const name of [
+      'clearcoat',
+      'anisotropyStrength',
+      'sheenColor',
+      'iridescence',
+      'specular',
+      'clearcoatNormalTexture',
+      'anisotropyTexture',
+      'sheenColorTexture',
+      'iridescenceTexture',
+      'specularColorTexture',
+    ]) {
+      expect(parameterNames.has(name)).toBe(true);
+    }
+
+    const runtime = new AssetRegistry({
+      findMaterialArtifact: () => ({ ok: false, error: new Error('shader registry not wired') }),
+    } as never);
+    const parsed = runtime.parseAndReturnAsset({
+      kind: material.kind,
+      payload,
+      refs: [...material.refs],
+    });
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    expect(parsed.value.asset.kind).toBe('material');
+    const values = (parsed.value.asset as { values?: Record<string, unknown> }).values ?? {};
+    expect(values.clearcoatNormalTexture).toMatchObject({
+      texture: TEXTURE_GUIDS[0],
+      sampler: SAMPLER_GUIDS[0],
+    });
+    expect(values.anisotropyTexture).toMatchObject({
+      texture: TEXTURE_GUIDS[1],
+      sampler: SAMPLER_GUIDS[1],
+    });
+    expect(values.sheenColorTexture).toMatchObject({
+      texture: TEXTURE_GUIDS[2],
+      sampler: SAMPLER_GUIDS[2],
+    });
+    expect(values.iridescenceTexture).toMatchObject({
+      texture: TEXTURE_GUIDS[3],
+      sampler: SAMPLER_GUIDS[3],
+    });
+    expect(values.specularColorTexture).toMatchObject({
+      texture: TEXTURE_GUIDS[4],
+      sampler: SAMPLER_GUIDS[4],
+    });
+  });
+});

package/src/bridge.ts

@@ -19,7 +19,7 @@
 // (B3) child world pos accumulates parent transform
 // (B6) camera detection via GltfNodeIr.camera field (not legacy nodes[1] heuristic)
 
-import { packInterleavedVertexAttributes } from '@forgeax/engine-geometry';
+import { computeTangentVec4, packInterleavedVertexAttributes } from '@forgeax/engine-geometry';
 import type { Mat4 } from '@forgeax/engine-math';
 import { box3, mat4, quat, vec3 } from '@forgeax/engine-math';
 import { AssetGuid as AssetGuidCodec } from '@forgeax/engine-pack/guid';
@@ -40,6 +40,13 @@ import type {
   Submesh,
   VertexAttributeMap,
 } from '@forgeax/engine-types';
+import {
+  STANDARD_LAYER_PARAMETER_GROUPS,
+  STANDARD_MATERIAL_PARAM_SCHEMA,
+  STANDARD_PHYSICAL_PARAMETER_NAMES,
+  STANDARD_TRANSMISSION_PARAMETER_NAMES,
+  standardMaterialParameters,
+} from '@forgeax/engine-types';
 import { createMaterialError, err, type GltfError, gltfErr, ok } from './errors.js';
 import type {
   GltfDoc,
@@ -216,6 +223,21 @@ export function meshIrToMeshAsset(
     const materialSlot = slotFor(mesh.materialIndex);
     const primVertexCount = mesh.positions.length / 3;
     const primIndexCount = mesh.indices === undefined ? 0 : mesh.indices.length;
+    // A tangent admission check may already have computed a valid frame for a
+    // physical glTF material. Persist that producer result into the canonical
+    // MeshAsset instead of silently replacing it with the historical identity
+    // tangent. Non-physical meshes keep the identity fallback when the source
+    // lacks the inputs required by the tangent producer.
+    let generatedTangents: Float32Array | undefined;
+    if (mesh.tangents === undefined && mesh.normals !== undefined && mesh.texcoord0 !== undefined) {
+      const generated = computeTangentVec4(
+        mesh.positions,
+        mesh.normals,
+        mesh.texcoord0,
+        mesh.indices,
+      );
+      if (generated.ok) generatedTangents = generated.value;
+    }
     if (mesh.colors0 !== undefined && mesh.colors0.length !== primVertexCount * 4) {
       return err(
         gltfErr('gltf-mesh-bridge-invalid', {
@@ -247,12 +269,13 @@ export function meshIrToMeshAsset(
         uvsCat[(vertexCursor + i) * 2 + 0] = mesh.texcoord0[t + 0] as number;
         uvsCat[(vertexCursor + i) * 2 + 1] = mesh.texcoord0[t + 1] as number;
       }
-      if (mesh.tangents !== undefined) {
+      const sourceTangents = mesh.tangents ?? generatedTangents;
+      if (sourceTangents !== undefined) {
         const g = i * 4;
-        tangentsCat[(vertexCursor + i) * 4 + 0] = mesh.tangents[g + 0] as number;
-        tangentsCat[(vertexCursor + i) * 4 + 1] = mesh.tangents[g + 1] as number;
-        tangentsCat[(vertexCursor + i) * 4 + 2] = mesh.tangents[g + 2] as number;
-        tangentsCat[(vertexCursor + i) * 4 + 3] = mesh.tangents[g + 3] as number;
+        tangentsCat[(vertexCursor + i) * 4 + 0] = sourceTangents[g + 0] as number;
+        tangentsCat[(vertexCursor + i) * 4 + 1] = sourceTangents[g + 1] as number;
+        tangentsCat[(vertexCursor + i) * 4 + 2] = sourceTangents[g + 2] as number;
+        tangentsCat[(vertexCursor + i) * 4 + 3] = sourceTangents[g + 3] as number;
       } else {
         tangentsCat[(vertexCursor + i) * 4 + 0] = 1;
         tangentsCat[(vertexCursor + i) * 4 + 3] = 1;
@@ -778,7 +801,17 @@ type MaterialTextureSlot =
   | 'occlusionTexture'
   | 'emissiveTexture'
   | 'transmissionTexture'
-  | 'thicknessTexture';
+  | 'thicknessTexture'
+  | 'clearcoatTexture'
+  | 'clearcoatRoughnessTexture'
+  | 'clearcoatNormalTexture'
+  | 'anisotropyTexture'
+  | 'sheenColorTexture'
+  | 'sheenRoughnessTexture'
+  | 'iridescenceTexture'
+  | 'iridescenceThicknessTexture'
+  | 'specularTexture'
+  | 'specularColorTexture';
 
 function textureValue(
   info: GltfTextureInfoIr | number | undefined,
@@ -811,6 +844,12 @@ function textureValue(
       return { ...value, normalScale: normal.scale };
     }
   }
+  if (slot === 'clearcoatNormalTexture') {
+    const normal = info as GltfMaterialIr['clearcoatNormalTexture'];
+    if (typeof normal === 'object' && normal?.scale !== undefined) {
+      return { ...value, normalScale: normal.scale };
+    }
+  }
   if (slot === 'occlusionTexture') {
     const occlusion = info as GltfMaterialIr['occlusionTexture'];
     if (typeof occlusion === 'object' && occlusion?.strength !== undefined) {
@@ -820,6 +859,102 @@ function textureValue(
   return value;
 }
 
+/**
+ * Select the exact Standard root contract emitted by the glTF producer.
+ * Numeric/base fields come from the shared schema; physical texture slots are
+ * admitted only when the source actually declares them.  A parent root is
+ * retained for the legacy base-only path, while an extended glTF material
+ * becomes its own root so its extension declarations own cook/ABI identity.
+ */
+function standardRootParameterNames(mat: GltfMaterialIr): {
+  readonly names: ReadonlySet<string>;
+  readonly extended: boolean;
+} {
+  const names = new Set(
+    STANDARD_MATERIAL_PARAM_SCHEMA.filter(
+      (entry) =>
+        !STANDARD_PHYSICAL_PARAMETER_NAMES.has(entry.name) &&
+        !STANDARD_TRANSMISSION_PARAMETER_NAMES.has(entry.name),
+    ).map((entry) => entry.name),
+  );
+  // IOR is consumed for the base dielectric F0 fallback even when the
+  // transmission/volume extension is absent.
+  names.add('ior');
+
+  const addLayer = (layer: keyof typeof STANDARD_LAYER_PARAMETER_GROUPS): void => {
+    for (const name of STANDARD_LAYER_PARAMETER_GROUPS[layer]) names.add(name);
+  };
+  const addTexture = (name: string, info: GltfTextureInfoIr | number | undefined): void => {
+    if (info !== undefined) names.add(name);
+  };
+
+  const clearcoat =
+    mat.clearcoatFactor !== undefined ||
+    mat.clearcoatRoughnessFactor !== undefined ||
+    mat.clearcoatNormalTexture !== undefined ||
+    mat.clearcoatTexture !== undefined ||
+    mat.clearcoatRoughnessTexture !== undefined;
+  const anisotropy =
+    mat.anisotropyStrength !== undefined ||
+    mat.anisotropyRotation !== undefined ||
+    mat.anisotropyTexture !== undefined;
+  const sheen =
+    mat.sheenColorFactor !== undefined ||
+    mat.sheenRoughnessFactor !== undefined ||
+    mat.sheenColorTexture !== undefined ||
+    mat.sheenRoughnessTexture !== undefined;
+  const iridescence =
+    mat.iridescenceFactor !== undefined ||
+    mat.iridescenceIor !== undefined ||
+    mat.iridescenceThicknessMinimum !== undefined ||
+    mat.iridescenceThicknessMaximum !== undefined ||
+    mat.iridescenceTexture !== undefined ||
+    mat.iridescenceThicknessTexture !== undefined;
+  if (clearcoat) addLayer('clearcoat');
+  if (anisotropy) addLayer('anisotropy');
+  if (sheen) addLayer('sheen');
+  if (iridescence) addLayer('iridescence');
+  if (clearcoat && mat.clearcoatNormalTexture !== undefined) names.add('clearcoatNormalScale');
+
+  addTexture('clearcoatTexture', mat.clearcoatTexture);
+  addTexture('clearcoatRoughnessTexture', mat.clearcoatRoughnessTexture);
+  addTexture('clearcoatNormalTexture', mat.clearcoatNormalTexture);
+  addTexture('anisotropyTexture', mat.anisotropyTexture);
+  addTexture('sheenColorTexture', mat.sheenColorTexture);
+  addTexture('sheenRoughnessTexture', mat.sheenRoughnessTexture);
+  addTexture('iridescenceTexture', mat.iridescenceTexture);
+  addTexture('iridescenceThicknessTexture', mat.iridescenceThicknessTexture);
+  addTexture('specularTexture', mat.specularTexture);
+  addTexture('specularColorTexture', mat.specularColorTexture);
+
+  const transmission =
+    mat.transmissionFactor !== undefined ||
+    mat.transmissionTexture !== undefined ||
+    mat.ior !== undefined ||
+    mat.thicknessFactor !== undefined ||
+    mat.thicknessTexture !== undefined ||
+    mat.attenuationColor !== undefined ||
+    mat.attenuationDistance !== undefined;
+  if (transmission) {
+    // Transmission/volume keeps its existing paired backdrop ABI.  The
+    // producer may leave either value at its neutral fallback, but the pair
+    // remains part of the pre-existing transmission root contract.
+    for (const name of STANDARD_TRANSMISSION_PARAMETER_NAMES) names.add(name);
+  }
+
+  return {
+    names,
+    extended:
+      clearcoat ||
+      anisotropy ||
+      sheen ||
+      iridescence ||
+      transmission ||
+      mat.specularTexture !== undefined ||
+      mat.specularColorTexture !== undefined,
+  };
+}
+
 export function validateMaterialUvSets(
   mat: GltfMaterialIr,
   primitive: string,
@@ -834,6 +969,16 @@ export function validateMaterialUvSets(
     ['emissiveTexture', mat.emissiveTexture],
     ['transmissionTexture', mat.transmissionTexture],
     ['thicknessTexture', mat.thicknessTexture],
+    ['clearcoatTexture', mat.clearcoatTexture],
+    ['clearcoatRoughnessTexture', mat.clearcoatRoughnessTexture],
+    ['clearcoatNormalTexture', mat.clearcoatNormalTexture],
+    ['anisotropyTexture', mat.anisotropyTexture],
+    ['sheenColorTexture', mat.sheenColorTexture],
+    ['sheenRoughnessTexture', mat.sheenRoughnessTexture],
+    ['iridescenceTexture', mat.iridescenceTexture],
+    ['iridescenceThicknessTexture', mat.iridescenceThicknessTexture],
+    ['specularTexture', mat.specularTexture],
+    ['specularColorTexture', mat.specularColorTexture],
   ];
   for (const [slot, rawBinding] of slots) {
     const binding = textureInfo(rawBinding);
@@ -854,8 +999,67 @@ export function validateMaterialUvSets(
   return ok(undefined);
 }
 
+export function validateMaterialTangentInputs(
+  mat: GltfMaterialIr,
+  mesh: GltfMeshIr,
+  layer = 'clearcoat',
+): Result<void, MaterialError> {
+  // Anisotropy changes the base GGX lobe even when it has no texture map, so
+  // its tangent direction is part of the scalar layer contract.  Select UV 0
+  // for the scalar-only form; a mapped form keeps the map's explicit UV set.
+  const anisotropyDeclared =
+    mat.anisotropyStrength !== undefined ||
+    mat.anisotropyRotation !== undefined ||
+    mat.anisotropyTexture !== undefined;
+  const tangentSlot = anisotropyDeclared
+    ? { layer: 'anisotropy', info: mat.anisotropyTexture }
+    : mat.clearcoatNormalTexture !== undefined
+      ? { layer: 'clearcoat', info: mat.clearcoatNormalTexture }
+      : undefined;
+  if (tangentSlot === undefined) return ok(undefined);
+  const selected = textureInfo(tangentSlot.info);
+  const uvSet = selected?.texCoord ?? 0;
+  const uv = mesh[`texcoord${uvSet === 0 ? '0' : uvSet}` as keyof GltfMeshIr];
+  const attributes = ['NORMAL', `TEXCOORD_${uvSet}`, 'TANGENT'];
+  const fail = (reason: string): Result<void, MaterialError> =>
+    err(
+      createMaterialError('material-tangent-required', {
+        code: 'material-tangent-required',
+        material: mat.name ?? '<unnamed>',
+        mesh: mesh.name ?? '<unnamed>',
+        layer: tangentSlot.layer ?? layer,
+        uv: `TEXCOORD_${uvSet}`,
+        attributes,
+        reason,
+      }),
+    );
+  if (mesh.tangents !== undefined) {
+    if (
+      mesh.tangents.length !== (mesh.positions.length / 3) * 4 ||
+      mesh.tangents.some((value) => !Number.isFinite(value))
+    ) {
+      return fail('imported TANGENT must be finite vec4 per vertex');
+    }
+    return ok(undefined);
+  }
+  if (mesh.normals === undefined) return fail('NORMAL is required to generate tangent');
+  if (!(uv instanceof Float32Array))
+    return fail('the selected UV set is required to generate tangent');
+  const generated = computeTangentVec4(mesh.positions, mesh.normals, uv, mesh.indices);
+  if (!generated.ok) {
+    const detail = generated.error.detail;
+    const reason =
+      detail !== undefined && 'reason' in detail
+        ? String(detail.reason)
+        : 'tangent producer rejected topology';
+    return fail(reason);
+  }
+  return ok(undefined);
+}
+
 /** Convert a parsed GltfMaterialIr into a standard-root derived MaterialAsset. */
 export function toMaterialAsset(mat: GltfMaterialIr, ctx?: MaterialBridgeContext): MaterialAsset {
+  const rootContract = standardRootParameterNames(mat);
   const values: Record<string, NonNullable<MaterialAsset['values']>[string]> = {
     baseColor: mat.baseColorFactor,
     metallic: mat.metallicFactor,
@@ -873,6 +1077,16 @@ export function toMaterialAsset(mat: GltfMaterialIr, ctx?: MaterialBridgeContext
     ['emissiveTexture', mat.emissiveTexture],
     ['transmissionTexture', mat.transmissionTexture],
     ['thicknessTexture', mat.thicknessTexture],
+    ['clearcoatTexture', mat.clearcoatTexture],
+    ['clearcoatRoughnessTexture', mat.clearcoatRoughnessTexture],
+    ['clearcoatNormalTexture', mat.clearcoatNormalTexture],
+    ['anisotropyTexture', mat.anisotropyTexture],
+    ['sheenColorTexture', mat.sheenColorTexture],
+    ['sheenRoughnessTexture', mat.sheenRoughnessTexture],
+    ['iridescenceTexture', mat.iridescenceTexture],
+    ['iridescenceThicknessTexture', mat.iridescenceThicknessTexture],
+    ['specularTexture', mat.specularTexture],
+    ['specularColorTexture', mat.specularColorTexture],
   ];
   for (const [slot, info] of textureSlots) {
     const value = textureValue(info, slot, ctx);
@@ -881,11 +1095,37 @@ export function toMaterialAsset(mat: GltfMaterialIr, ctx?: MaterialBridgeContext
   if (mat.occlusionTexture !== undefined && values.occlusionStrength === undefined) {
     values.occlusionStrength = 1;
   }
-  if (mat.transmissionFactor !== undefined) values.transmission = mat.transmissionFactor;
-  if (mat.ior !== undefined) values.ior = mat.ior;
-  if (mat.thicknessFactor !== undefined) values.thickness = mat.thicknessFactor;
-  if (mat.attenuationColor !== undefined) values.attenuationColor = mat.attenuationColor;
-  if (mat.attenuationDistance !== undefined) values.attenuationDistance = mat.attenuationDistance;
+  if (rootContract.extended && rootContract.names.has('transmission')) {
+    values.transmission = mat.transmissionFactor ?? 0;
+    values.ior = mat.ior ?? 1.5;
+    values.thickness = mat.thicknessFactor ?? 0;
+    values.attenuationColor = mat.attenuationColor ?? [1, 1, 1];
+    if (mat.attenuationDistance !== undefined) values.attenuationDistance = mat.attenuationDistance;
+  }
+  if (rootContract.names.has('clearcoat')) {
+    values.clearcoat = mat.clearcoatFactor ?? 0;
+    values.clearcoatRoughness = mat.clearcoatRoughnessFactor ?? 0;
+  }
+  const clearcoatNormal = textureInfo(mat.clearcoatNormalTexture) as
+    | (GltfTextureInfoIr & { readonly scale?: number })
+    | undefined;
+  if (clearcoatNormal?.scale !== undefined) values.clearcoatNormalScale = clearcoatNormal.scale;
+  if (rootContract.names.has('anisotropyStrength')) {
+    values.anisotropyStrength = mat.anisotropyStrength ?? 0;
+    values.anisotropyRotation = mat.anisotropyRotation ?? 0;
+  }
+  if (rootContract.names.has('sheenColor')) {
+    values.sheenColor = mat.sheenColorFactor ?? [0, 0, 0];
+    values.sheenRoughness = mat.sheenRoughnessFactor ?? 0;
+  }
+  if (rootContract.names.has('iridescence')) {
+    values.iridescence = mat.iridescenceFactor ?? 0;
+    values.iridescenceIor = mat.iridescenceIor ?? 1.3;
+    values.iridescenceThicknessMinimum = mat.iridescenceThicknessMinimum ?? 100;
+    values.iridescenceThicknessMaximum = mat.iridescenceThicknessMaximum ?? 400;
+  }
+  if (mat.specularFactor !== undefined) values.specular = mat.specularFactor;
+  if (mat.specularColorFactor !== undefined) values.specularColor = mat.specularColorFactor;
 
   const module = ctx?.skinned === true ? 'forgeax::pbr-skin' : 'forgeax::default-standard-pbr';
 
@@ -932,8 +1172,13 @@ export function toMaterialAsset(mat: GltfMaterialIr, ctx?: MaterialBridgeContext
   return {
     kind: 'material',
     colorSpace: 'linear',
-    ...(ctx?.standardRootGuid === undefined ? {} : { parent: ctx.standardRootGuid }),
+    ...(!rootContract.extended && ctx?.standardRootGuid !== undefined
+      ? { parent: ctx.standardRootGuid }
+      : {}),
     passes: [pass],
+    ...(ctx?.standardRootGuid !== undefined && !rootContract.extended
+      ? {}
+      : { parameters: standardMaterialParameters(rootContract.names) }),
     values,
   };
 }

package/src/check-extensions.ts

@@ -2,9 +2,10 @@
 //
 // Required-extension support contains EXT_mesh_gpu_instancing,
 // EXT_meshopt_compression, KHR_lights_punctual, KHR_texture_transform, and
-// the KHR material transmission/IOR/volume extensions. The exported legacy
-// list remains the original mesh extension list for callers that display the
-// v1 mesh-only surface.
+// the KHR material transmission/IOR/volume/clearcoat/anisotropy/sheen/
+// iridescence/specular extensions. The exported list is the public supported
+// extension surface consumed by both the required-extension gate and callers
+// that need to discover support.
 // (feat-20260518-gltf-instancing-and-name-component plan-strategy section
 // 2 D-1 / D-3). Any extension listed in `extensionsRequired[]` outside
 // the supported extension set triggers `gltf-extension-unsupported` (hard fail).
@@ -18,25 +19,30 @@
 // diagnostics list is the single channel (no `console.error`).
 //
 // Future expansion (KHR_materials_unlit, ...) extends
-// `SUPPORTED_EXTENSIONS` in place; each addition lands under its own feat-*
+// `EXTENSION_ALLOWLIST` in place; each addition lands under its own feat-*
 // loop with breaking-change registry entry.
 
 import { err, type GltfError, gltfErr, ok, type Result } from './errors.js';
 
-/** Legacy v1 mesh-only list kept for callers that display that surface. */
+/** Public supported extension list used by the required/used declaration gate. */
 export const EXTENSION_ALLOWLIST: readonly string[] = [
   'EXT_mesh_gpu_instancing',
   'EXT_meshopt_compression',
-  'MSFT_lod',
-  'MSFT_screencoverage',
-];
-const SUPPORTED_EXTENSIONS: readonly string[] = [
-  ...EXTENSION_ALLOWLIST,
   'KHR_lights_punctual',
   'KHR_texture_transform',
   'KHR_materials_transmission',
   'KHR_materials_ior',
   'KHR_materials_volume',
+  'KHR_materials_clearcoat',
+  'KHR_materials_anisotropy',
+  'KHR_materials_sheen',
+  'KHR_materials_iridescence',
+  'KHR_materials_specular',
+];
+const SUPPORTED_EXTENSIONS: readonly string[] = [
+  ...EXTENSION_ALLOWLIST,
+  'MSFT_lod',
+  'MSFT_screencoverage',
 ];
 
 export interface ExtensionsCheckResult {