@forgeax/engine-render 0.1.23 → 0.1.25

package/src/materials.ts

@@ -1,3 +1,4 @@
+import { color } from '@forgeax/engine-math';
 import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '@forgeax/engine-shader';
 import type {
   MaterialAsset,
@@ -7,6 +8,11 @@ import type {
   MaterialRenderState,
   MaterialValue,
 } from '@forgeax/engine-types';
+import { deriveStandardLayerPlan } from '@forgeax/engine-types';
+import {
+  DEFAULT_STANDARD_SURFACE_MODULE,
+  projectStandardSurfacePasses,
+} from './assembly/material/surface-projection';
 
 export type MaterialTransmissionValidationReason =
   | 'non-finite'
@@ -56,10 +62,52 @@ export const SPRITE_PREMULTIPLIED_ALPHA_BLEND: GPUBlendState = {
   alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
 };
 
-const STANDARD_MODULE = 'forgeax_material::standard';
 const UNLIT_MODULE = 'forgeax_material::unlit';
 const SPRITE_MODULE = 'forgeax_material::sprite';
 
+export type MaterialColorTuple3 = readonly [number, number, number];
+export type MaterialColorTuple4 = readonly [number, number, number, number];
+export type MaterialColorInput3 = MaterialColorTuple3 | string | number;
+export type MaterialColorInput4 = MaterialColorTuple4 | string | number;
+
+function colorHexFromNumber(value: number): string {
+  if (!Number.isInteger(value) || value < 0 || value > 0xffffff) {
+    throw new Error(`material color number must be an integer in [0, 0xffffff], got ${value}`);
+  }
+  return `#${value.toString(16).padStart(6, '0')}`;
+}
+
+function linearColorFromInput(
+  input: MaterialColorInput3 | MaterialColorInput4,
+  channels: 3 | 4,
+): readonly number[] {
+  if (typeof input === 'number' || typeof input === 'string') {
+    const parsed = color.create();
+    color.fromCss(parsed, typeof input === 'number' ? colorHexFromNumber(input) : input);
+    return channels === 3
+      ? [parsed[0] as number, parsed[1] as number, parsed[2] as number]
+      : Array.from(parsed);
+  }
+  if (input.length !== channels) {
+    throw new Error(`material color tuple must contain ${channels} channels, got ${input.length}`);
+  }
+  return [...input];
+}
+
+/** Convert an explicit sRGB numeric tuple into the linear tuple factories store. */
+export function srgb(input: MaterialColorTuple3): MaterialColorTuple3;
+export function srgb(input: MaterialColorTuple4): MaterialColorTuple4;
+export function srgb(input: readonly number[]): readonly number[] {
+  if (input.length !== 3 && input.length !== 4) {
+    throw new Error(`sRGB material color tuple must contain 3 or 4 channels, got ${input.length}`);
+  }
+  const parsed = color.create(input[0] ?? 0, input[1] ?? 0, input[2] ?? 0, input[3] ?? 1);
+  color.srgbToLinear(parsed, parsed);
+  return input.length === 3
+    ? [parsed[0] as number, parsed[1] as number, parsed[2] as number]
+    : [parsed[0] as number, parsed[1] as number, parsed[2] as number, parsed[3] as number];
+}
+
 function authoredColorParameter(
   name: string,
   type: 'color' | 'vec3',
@@ -74,27 +122,148 @@ function authoredColorParameter(
   };
 }
 
-function standardParameters(colorSpace: MaterialColorSpace): readonly MaterialParameter[] {
-  return DEFAULT_STANDARD_PBR_PARAM_SCHEMA.map((entry) => {
-    const type = entry.type.startsWith('texture') ? 'texture' : entry.type;
-    const isRequired =
-      entry.name === 'baseColor' || entry.name === 'metallic' || entry.name === 'roughness';
-    const authoredColor =
-      entry.type === 'color' || (entry.type === 'vec3' && entry.name !== 'attenuationColor');
-    const schemaColorSpace = 'colorSpace' in entry ? entry.colorSpace : undefined;
-    const colorSpaceProjection: { colorSpace?: MaterialColorSpace } = {};
-    if (authoredColor && !(type === 'color' && colorSpace === 'srgb')) {
-      colorSpaceProjection.colorSpace = colorSpace;
-    } else if (!authoredColor && schemaColorSpace !== undefined) {
-      colorSpaceProjection.colorSpace = schemaColorSpace;
+function standardParameters(
+  colorSpace: MaterialColorSpace,
+  opts: StandardOpts,
+): readonly MaterialParameter[] {
+  const physicalNames = new Set<string>();
+  const addPhysical = (...names: readonly string[]) => {
+    for (const name of names) physicalNames.add(name);
+  };
+  if (
+    opts.clearcoat !== undefined ||
+    opts.clearcoatRoughness !== undefined ||
+    opts.clearcoatNormalScale !== undefined ||
+    opts.clearcoatTexture !== undefined ||
+    opts.clearcoatRoughnessTexture !== undefined ||
+    opts.clearcoatNormalTexture !== undefined
+  ) {
+    addPhysical(
+      'clearcoat',
+      'clearcoatRoughness',
+      'clearcoatNormalScale',
+      ...(opts.clearcoatTexture === undefined ? [] : ['clearcoatTexture']),
+      ...(opts.clearcoatRoughnessTexture === undefined ? [] : ['clearcoatRoughnessTexture']),
+      ...(opts.clearcoatNormalTexture === undefined ? [] : ['clearcoatNormalTexture']),
+    );
+  }
+  if (
+    opts.anisotropyStrength !== undefined ||
+    opts.anisotropyRotation !== undefined ||
+    opts.anisotropyTexture !== undefined
+  ) {
+    addPhysical('anisotropyStrength', 'anisotropyRotation');
+    if (opts.anisotropyTexture !== undefined) addPhysical('anisotropyTexture');
+  }
+  if (
+    opts.sheenColor !== undefined ||
+    opts.sheenRoughness !== undefined ||
+    opts.sheenColorTexture !== undefined ||
+    opts.sheenRoughnessTexture !== undefined
+  ) {
+    addPhysical('sheenColor', 'sheenRoughness');
+    if (opts.sheenColorTexture !== undefined) addPhysical('sheenColorTexture');
+    if (opts.sheenRoughnessTexture !== undefined) addPhysical('sheenRoughnessTexture');
+  }
+  if (
+    opts.iridescence !== undefined ||
+    opts.iridescenceIor !== undefined ||
+    opts.iridescenceThicknessMinimum !== undefined ||
+    opts.iridescenceThicknessMaximum !== undefined ||
+    opts.iridescenceTexture !== undefined ||
+    opts.iridescenceThicknessTexture !== undefined
+  ) {
+    addPhysical(
+      'iridescence',
+      'iridescenceIor',
+      'iridescenceThicknessMinimum',
+      'iridescenceThicknessMaximum',
+      ...(opts.iridescenceTexture === undefined ? [] : ['iridescenceTexture']),
+      ...(opts.iridescenceThicknessTexture === undefined ? [] : ['iridescenceThicknessTexture']),
+    );
+  }
+  const baseNames = new Set([
+    'baseColor',
+    'metallic',
+    'roughness',
+    'metallicChannel',
+    'roughnessChannel',
+    'aoChannel',
+    'extraChannel',
+    'emissive',
+    'emissiveIntensity',
+    'occlusionStrength',
+    'alphaCutoff',
+    'normalScale',
+    'baseColorTexture',
+    'metallicRoughnessTexture',
+    'normalTexture',
+    'emissiveTexture',
+    'occlusionTexture',
+    'specular',
+    'specularColor',
+    // IOR is part of the always-present dielectric F0 contract. The
+    // transmission layer may be absent, but the Standard shader still
+    // consumes this scalar for the base reflection path.
+    'ior',
+  ]);
+  if (opts.specularTexture !== undefined) baseNames.add('specularTexture');
+  if (opts.specularColorTexture !== undefined) baseNames.add('specularColorTexture');
+  if (
+    opts.transmission !== undefined ||
+    opts.ior !== undefined ||
+    opts.thickness !== undefined ||
+    opts.transmissionTexture !== undefined ||
+    opts.thicknessTexture !== undefined ||
+    opts.attenuationColor !== undefined ||
+    opts.attenuationDistance !== undefined
+  ) {
+    for (const name of [
+      'transmission',
+      'ior',
+      'thickness',
+      'attenuationColor',
+      'attenuationDistance',
+      'transmissionTexture',
+      'thicknessTexture',
+    ]) {
+      baseNames.add(name);
     }
-    return {
-      name: entry.name,
-      type,
-      ...colorSpaceProjection,
-      ...(isRequired ? {} : { optional: true }),
-    } as MaterialParameter;
-  });
+  }
+  // All Standard fields come from one root schema. Physical fields are
+  // projected by the authored option membership above; appending a second
+  // physical schema would create a parallel ABI authority.
+  const availableSchema = DEFAULT_STANDARD_PBR_PARAM_SCHEMA;
+  // Keep the generated Standard UBO's numeric run contiguous before any
+  // texture coordinate records. The built-in WGSL places the complete
+  // physical root (including clearcoat scalars) after the base numeric run
+  // and before all coordinate pairs; appending physical entries after the
+  // base texture records would otherwise derive a different ABI.
+  const numericSchema = availableSchema.filter((entry) => !entry.type.startsWith('texture'));
+  const textureSchema = availableSchema.filter((entry) => entry.type.startsWith('texture'));
+  const orderedSchema = [...numericSchema, ...textureSchema];
+  return orderedSchema
+    .filter((entry) => baseNames.has(entry.name) || physicalNames.has(entry.name))
+    .map((entry) => {
+      const type = entry.type.startsWith('texture') ? 'texture' : entry.type;
+      const isRequired =
+        entry.name === 'baseColor' || entry.name === 'metallic' || entry.name === 'roughness';
+      const authoredColor =
+        entry.type === 'color' || (entry.type === 'vec3' && entry.name !== 'attenuationColor');
+      const schemaColorSpace = 'colorSpace' in entry ? entry.colorSpace : undefined;
+      const colorSpaceProjection: { colorSpace?: MaterialColorSpace } = {};
+      if (authoredColor && !(type === 'color' && colorSpace === 'srgb')) {
+        colorSpaceProjection.colorSpace = colorSpace;
+      } else if (!authoredColor && schemaColorSpace !== undefined) {
+        colorSpaceProjection.colorSpace = schemaColorSpace;
+      }
+      return {
+        name: entry.name,
+        type,
+        ...colorSpaceProjection,
+        ...(isRequired ? {} : { optional: true }),
+      } as MaterialParameter;
+    });
 }
 
 function unlitParameters(colorSpace: MaterialColorSpace): readonly MaterialParameter[] {
@@ -141,8 +310,6 @@ function shadowCasterRenderState(
 }
 
 interface UnlitOpts {
-  /** Asset-side authored color space. Defaults to sRGB. */
-  readonly colorSpace?: MaterialColorSpace;
   readonly castShadow?: boolean;
   readonly baseColorTexture?: MaterialValue;
   readonly alphaCutoff?: number;
@@ -150,11 +317,11 @@ interface UnlitOpts {
   readonly queue?: number;
 }
 
-function unlit(rgba: readonly [number, number, number, number], opts?: UnlitOpts): MaterialAsset {
+function unlit(rgba: MaterialColorInput4, opts?: UnlitOpts): MaterialAsset {
   if (opts?.alphaCutoff !== undefined && (opts.alphaCutoff < 0 || opts.alphaCutoff > 1)) {
     throw new Error(`Materials.unlit: alphaCutoff must be in [0, 1], got ${opts.alphaCutoff}`);
   }
-  const values: Record<string, MaterialValue> = { baseColor: rgba };
+  const values: Record<string, MaterialValue> = { baseColor: linearColorFromInput(rgba, 4) };
   if (opts?.baseColorTexture !== undefined) values.baseColorTexture = opts.baseColorTexture;
   if (opts?.alphaCutoff !== undefined) values.alphaCutoff = opts.alphaCutoff;
   const passes: [MaterialPass, ...MaterialPass[]] = [
@@ -165,19 +332,16 @@ function unlit(rgba: readonly [number, number, number, number], opts?: UnlitOpts
   }
   return {
     kind: 'material',
-    ...(opts?.colorSpace === undefined || opts.colorSpace === 'srgb'
-      ? {}
-      : { colorSpace: opts.colorSpace }),
+    colorSpace: 'linear',
     passes,
-    parameters: unlitParameters(opts?.colorSpace ?? 'srgb'),
+    parameters: unlitParameters('linear'),
     values,
   };
 }
 
 interface StandardOpts {
-  /** Asset-side authored color space for baseColor/emissive/specularTint. Defaults to sRGB. */
-  readonly colorSpace?: MaterialColorSpace;
-  readonly baseColor: readonly [number, number, number, number];
+  /** Numeric tuples are linear; Hex/CSS strings and numbers are sRGB inputs. */
+  readonly baseColor: MaterialColorInput4;
   readonly metallic?: number;
   readonly roughness?: number;
   /** Texture channel used for the metallic factor; glTF defaults to B (2). */
@@ -186,9 +350,28 @@ interface StandardOpts {
   readonly roughnessChannel?: number;
   readonly clearcoat?: number;
   readonly clearcoatRoughness?: number;
-  readonly specularTint?: readonly [number, number, number];
-  readonly specularTintTexture?: MaterialValue;
-  readonly emissive?: readonly [number, number, number];
+  readonly clearcoatTexture?: MaterialValue;
+  readonly clearcoatRoughnessTexture?: MaterialValue;
+  readonly clearcoatNormalTexture?: MaterialValue;
+  readonly clearcoatNormalScale?: number;
+  readonly anisotropyStrength?: number;
+  readonly anisotropyRotation?: number;
+  readonly anisotropyTexture?: MaterialValue;
+  readonly sheenColor?: MaterialColorInput3;
+  readonly sheenRoughness?: number;
+  readonly sheenColorTexture?: MaterialValue;
+  readonly sheenRoughnessTexture?: MaterialValue;
+  readonly iridescence?: number;
+  readonly iridescenceIor?: number;
+  readonly iridescenceThicknessMinimum?: number;
+  readonly iridescenceThicknessMaximum?: number;
+  readonly iridescenceTexture?: MaterialValue;
+  readonly iridescenceThicknessTexture?: MaterialValue;
+  readonly specular?: number;
+  readonly specularColor?: MaterialColorInput3;
+  readonly specularTexture?: MaterialValue;
+  readonly specularColorTexture?: MaterialValue;
+  readonly emissive?: MaterialColorInput3;
   readonly emissiveIntensity?: number;
   readonly emissiveTexture?: MaterialValue;
   readonly baseColorTexture?: MaterialValue;
@@ -209,6 +392,70 @@ interface StandardOpts {
   readonly queue?: number;
 }
 
+/** Built-in Standard authoring surface with engine-owned parameter defaults. */
+export interface DefaultStandardOptions extends StandardOpts {
+  readonly surfaceModule?: never;
+  readonly parameters?: never;
+  readonly values?: never;
+}
+
+/** Import-first Standard Surface authoring; the root parameter contract stays caller-owned. */
+export interface CustomStandardSurfaceOptions {
+  readonly surfaceModule: string;
+  readonly parameters: readonly MaterialParameter[];
+  readonly values: Readonly<Record<string, MaterialValue>>;
+  readonly colorSpace?: MaterialColorSpace;
+  readonly renderState?: MaterialRenderState;
+  readonly castShadow?: boolean;
+  readonly queue?: number;
+  readonly baseColor?: never;
+  readonly metallic?: never;
+  readonly roughness?: never;
+  readonly metallicChannel?: never;
+  readonly roughnessChannel?: never;
+  readonly clearcoat?: never;
+  readonly clearcoatRoughness?: never;
+  readonly clearcoatTexture?: never;
+  readonly clearcoatRoughnessTexture?: never;
+  readonly clearcoatNormalTexture?: never;
+  readonly clearcoatNormalScale?: never;
+  readonly anisotropyStrength?: never;
+  readonly anisotropyRotation?: never;
+  readonly anisotropyTexture?: never;
+  readonly sheenColor?: never;
+  readonly sheenRoughness?: never;
+  readonly sheenColorTexture?: never;
+  readonly sheenRoughnessTexture?: never;
+  readonly iridescence?: never;
+  readonly iridescenceIor?: never;
+  readonly iridescenceThicknessMinimum?: never;
+  readonly iridescenceThicknessMaximum?: never;
+  readonly iridescenceTexture?: never;
+  readonly iridescenceThicknessTexture?: never;
+  readonly specular?: never;
+  readonly specularColor?: never;
+  readonly specularTexture?: never;
+  readonly specularColorTexture?: never;
+  readonly emissive?: never;
+  readonly emissiveIntensity?: never;
+  readonly emissiveTexture?: never;
+  readonly baseColorTexture?: never;
+  readonly metallicRoughnessTexture?: never;
+  readonly normalTexture?: never;
+  readonly occlusionTexture?: never;
+  readonly occlusionStrength?: never;
+  readonly alphaCutoff?: never;
+  readonly transmission?: never;
+  readonly transmissionTexture?: never;
+  readonly ior?: never;
+  readonly thickness?: never;
+  readonly thicknessTexture?: never;
+  readonly attenuationColor?: never;
+  readonly attenuationDistance?: never;
+}
+
+export type StandardOptions = DefaultStandardOptions | CustomStandardSurfaceOptions;
+
 function validateChannel(
   name: 'metallicChannel' | 'roughnessChannel',
   value: number | undefined,
@@ -233,7 +480,7 @@ function validateFiniteRange(
   }
 }
 
-function standard(opts: StandardOpts): MaterialAsset {
+function standardDefault(opts: DefaultStandardOptions): MaterialAsset {
   const occlusionStrength = opts.occlusionStrength ?? 1;
   if (occlusionStrength < 0 || occlusionStrength > 1) {
     throw new Error(
@@ -266,11 +513,13 @@ function standard(opts: StandardOpts): MaterialAsset {
     throw new MaterialTransmissionContractError('transmission', 'depth-write', true);
   }
   const values: Record<string, MaterialValue> = {
-    baseColor: opts.baseColor,
+    baseColor: linearColorFromInput(opts.baseColor, 4),
     metallic: opts.metallic ?? 0,
     roughness: opts.roughness ?? 0.5,
     occlusionStrength,
-    specularTint: opts.specularTint ?? [1, 1, 1],
+    specular: opts.specular ?? 1,
+    specularColor:
+      opts.specularColor === undefined ? [1, 1, 1] : linearColorFromInput(opts.specularColor, 3),
     transmission,
     ior,
     thickness,
@@ -280,7 +529,37 @@ function standard(opts: StandardOpts): MaterialAsset {
   if (opts.roughnessChannel !== undefined) values.roughnessChannel = opts.roughnessChannel;
   if (opts.clearcoat !== undefined) values.clearcoat = opts.clearcoat;
   if (opts.clearcoatRoughness !== undefined) values.clearcoatRoughness = opts.clearcoatRoughness;
-  if (opts.emissive !== undefined) values.emissive = opts.emissive;
+  if (opts.clearcoatTexture !== undefined) values.clearcoatTexture = opts.clearcoatTexture;
+  if (opts.clearcoatRoughnessTexture !== undefined) {
+    values.clearcoatRoughnessTexture = opts.clearcoatRoughnessTexture;
+  }
+  if (opts.clearcoatNormalTexture !== undefined) {
+    values.clearcoatNormalTexture = opts.clearcoatNormalTexture;
+  }
+  if (opts.clearcoatNormalScale !== undefined)
+    values.clearcoatNormalScale = opts.clearcoatNormalScale;
+  if (opts.anisotropyStrength !== undefined) values.anisotropyStrength = opts.anisotropyStrength;
+  if (opts.anisotropyRotation !== undefined) values.anisotropyRotation = opts.anisotropyRotation;
+  if (opts.anisotropyTexture !== undefined) values.anisotropyTexture = opts.anisotropyTexture;
+  if (opts.sheenColor !== undefined) values.sheenColor = linearColorFromInput(opts.sheenColor, 3);
+  if (opts.sheenRoughness !== undefined) values.sheenRoughness = opts.sheenRoughness;
+  if (opts.sheenColorTexture !== undefined) values.sheenColorTexture = opts.sheenColorTexture;
+  if (opts.sheenRoughnessTexture !== undefined) {
+    values.sheenRoughnessTexture = opts.sheenRoughnessTexture;
+  }
+  if (opts.iridescence !== undefined) values.iridescence = opts.iridescence;
+  if (opts.iridescenceIor !== undefined) values.iridescenceIor = opts.iridescenceIor;
+  if (opts.iridescenceThicknessMinimum !== undefined) {
+    values.iridescenceThicknessMinimum = opts.iridescenceThicknessMinimum;
+  }
+  if (opts.iridescenceThicknessMaximum !== undefined) {
+    values.iridescenceThicknessMaximum = opts.iridescenceThicknessMaximum;
+  }
+  if (opts.iridescenceTexture !== undefined) values.iridescenceTexture = opts.iridescenceTexture;
+  if (opts.iridescenceThicknessTexture !== undefined) {
+    values.iridescenceThicknessTexture = opts.iridescenceThicknessTexture;
+  }
+  if (opts.emissive !== undefined) values.emissive = linearColorFromInput(opts.emissive, 3);
   if (opts.emissiveIntensity !== undefined) values.emissiveIntensity = opts.emissiveIntensity;
   if (opts.emissiveTexture !== undefined) values.emissiveTexture = opts.emissiveTexture;
   if (opts.baseColorTexture !== undefined) values.baseColorTexture = opts.baseColorTexture;
@@ -289,8 +568,9 @@ function standard(opts: StandardOpts): MaterialAsset {
   }
   if (opts.normalTexture !== undefined) values.normalTexture = opts.normalTexture;
   if (opts.occlusionTexture !== undefined) values.occlusionTexture = opts.occlusionTexture;
-  if (opts.specularTintTexture !== undefined) {
-    values.specularTintTexture = opts.specularTintTexture;
+  if (opts.specularTexture !== undefined) values.specularTexture = opts.specularTexture;
+  if (opts.specularColorTexture !== undefined) {
+    values.specularColorTexture = opts.specularColorTexture;
   }
   if (opts.alphaCutoff !== undefined) values.alphaCutoff = opts.alphaCutoff;
   if (opts.transmissionTexture !== undefined) values.transmissionTexture = opts.transmissionTexture;
@@ -298,26 +578,58 @@ function standard(opts: StandardOpts): MaterialAsset {
   if (opts.attenuationDistance !== undefined) values.attenuationDistance = opts.attenuationDistance;
   const forwardRenderState =
     transmission > 0 ? { ...(opts.renderState ?? {}), depthWriteEnabled: false } : opts.renderState;
-  const passes: [MaterialPass, ...MaterialPass[]] = [
-    pass('forward', STANDARD_MODULE, forwardRenderState, 'fs_main', opts.queue),
-  ];
-  if (transmission === 0) {
-    passes.push(pass('deferred', STANDARD_MODULE, opts.renderState, 'fs_gbuffer', opts.queue));
-  }
-  if (opts.castShadow !== false) {
-    passes.push(pass('shadow-caster', STANDARD_MODULE, shadowCasterRenderState(opts.renderState)));
+  const parameters = standardParameters('linear', opts);
+  const declaredNames = new Set(parameters.map((parameter) => parameter.name));
+  for (const name of Object.keys(values)) {
+    if (!declaredNames.has(name)) delete values[name];
   }
+  const layerPlan = deriveStandardLayerPlan(parameters);
+  const projected = projectStandardSurfacePasses({
+    surfaceModule: DEFAULT_STANDARD_SURFACE_MODULE,
+    values,
+    ...(forwardRenderState === undefined ? {} : { renderState: forwardRenderState }),
+    ...(opts.castShadow === undefined ? {} : { castShadow: opts.castShadow }),
+    ...(opts.queue === undefined ? {} : { queue: opts.queue }),
+    layerPlan,
+  });
+  const passes = (
+    transmission > 0 ? projected.filter((entry) => entry.name !== 'deferred') : projected
+  ) as [MaterialPass, ...MaterialPass[]];
+  return {
+    kind: 'material',
+    colorSpace: 'linear',
+    passes,
+    parameters,
+    values,
+  };
+}
+
+function standardCustom(opts: CustomStandardSurfaceOptions): MaterialAsset {
+  const layerPlan = deriveStandardLayerPlan(
+    opts.parameters.filter((parameter) => parameter.optional !== true),
+  );
   return {
     kind: 'material',
     ...(opts.colorSpace === undefined || opts.colorSpace === 'srgb'
       ? {}
       : { colorSpace: opts.colorSpace }),
-    passes,
-    parameters: standardParameters(opts.colorSpace ?? 'srgb'),
-    values,
+    passes: projectStandardSurfacePasses({
+      surfaceModule: opts.surfaceModule,
+      values: opts.values,
+      ...(opts.renderState === undefined ? {} : { renderState: opts.renderState }),
+      ...(opts.castShadow === undefined ? {} : { castShadow: opts.castShadow }),
+      ...(opts.queue === undefined ? {} : { queue: opts.queue }),
+      layerPlan,
+    }),
+    parameters: opts.parameters,
+    values: opts.values,
   };
 }
 
-export const Materials = { unlit, standard } as const;
+export function standard(options: StandardOptions): MaterialAsset {
+  return options.surfaceModule === undefined ? standardDefault(options) : standardCustom(options);
+}
+
+export const Materials = { unlit, standard, srgb } as const;
 
 export { SPRITE_MODULE };

package/src/mesh-material-bindings.ts

@@ -12,6 +12,65 @@ export interface MeshMaterialBindingDiagnostic {
   readonly detail?: Readonly<AssetErrorDetail>;
 }
 
+/** Detached final-frame receipt for the Standard material IBL binding chain. */
+export interface IblBindingResourceInspection {
+  readonly viewIdentity: number;
+  readonly samplerIdentity: number;
+  readonly deviceGeneration: number;
+}
+
+export interface IblBindingEntryInspection {
+  readonly binding: number;
+  readonly kind: 'textureView' | 'sampler' | 'buffer';
+  readonly resourceIdentity: number;
+}
+
+export interface IblBindingInspection {
+  readonly status: 'binding-chain-consistent' | 'binding-chain-mismatch';
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+  readonly active: 'active' | 'fallback';
+  readonly cache: {
+    readonly identity: number;
+    readonly generation: number;
+    readonly prefilterMipCount: number;
+    readonly prefilterViewMipCount: number;
+  };
+  readonly sampler: {
+    readonly expected: {
+      readonly magFilter: 'linear';
+      readonly minFilter: 'linear';
+      readonly mipmapFilter: 'linear';
+      readonly addressModeU: 'clamp-to-edge';
+      readonly addressModeV: 'clamp-to-edge';
+      readonly addressModeW: 'clamp-to-edge';
+    };
+    readonly identities: readonly number[];
+  };
+  readonly resources: {
+    readonly irradiance: IblBindingResourceInspection;
+    readonly prefilter: IblBindingResourceInspection;
+    readonly brdfLut: IblBindingResourceInspection;
+    readonly intensityBufferIdentity: number;
+  };
+  readonly material?: {
+    readonly bindGroupIdentity: number;
+    readonly materialBglIdentity: number;
+    readonly cache: 'hit' | 'miss';
+    readonly skylightBindingStart: number;
+    readonly entries: readonly IblBindingEntryInspection[];
+    readonly reflectionBindings: readonly number[];
+  };
+  readonly pipeline?: {
+    readonly pipelineIdentity: number;
+    readonly effectiveMaterialLayoutIdentity: string | undefined;
+    readonly materialBglIdentity: number;
+    readonly bindGroupIdentity: number;
+    readonly drawFrameId: number;
+  };
+  readonly errors: readonly string[];
+}
+
 export interface ResolvedMeshMaterialBinding {
   readonly handle: number;
   readonly source: MeshMaterialBindingSource;

package/src/occlusion-proxy.ts

@@ -0,0 +1,64 @@
+import { mat4 } from '@forgeax/engine-math';
+import { computeProjectionMatrix, computeViewMatrix } from './record/helpers';
+import type { CameraSnapshot } from './render-contract';
+
+/** Build the camera-facing proxy geometry used by GPU occlusion queries. */
+export function buildOcclusionProxyVertices(
+  aabb: ArrayLike<number>,
+  world: ArrayLike<number>,
+  camera: CameraSnapshot,
+): Float32Array {
+  const view = computeViewMatrix(camera);
+  const projection = computeProjectionMatrix(camera);
+  const viewProjection = mat4.create();
+  mat4.multiply(viewProjection, projection, view);
+  const corners = [
+    [aabb[0] ?? 0, aabb[1] ?? 0, aabb[2] ?? 0],
+    [aabb[3] ?? 0, aabb[1] ?? 0, aabb[2] ?? 0],
+    [aabb[3] ?? 0, aabb[4] ?? 0, aabb[2] ?? 0],
+    [aabb[0] ?? 0, aabb[4] ?? 0, aabb[2] ?? 0],
+    [aabb[0] ?? 0, aabb[1] ?? 0, aabb[5] ?? 0],
+    [aabb[3] ?? 0, aabb[1] ?? 0, aabb[5] ?? 0],
+    [aabb[3] ?? 0, aabb[4] ?? 0, aabb[5] ?? 0],
+    [aabb[0] ?? 0, aabb[4] ?? 0, aabb[5] ?? 0],
+  ];
+  const triangles = [
+    0, 1, 2, 0, 2, 3, 4, 6, 5, 4, 7, 6, 0, 4, 5, 0, 5, 1, 3, 2, 6, 3, 6, 7, 0, 3, 7, 0, 7, 4, 1, 5,
+    6, 1, 6, 2,
+  ];
+  const output = new Float32Array(triangles.length * 4);
+  for (let index = 0; index < triangles.length; index += 1) {
+    const corner = corners[triangles[index] ?? 0] ?? [0, 0, 0];
+    const cx = corner[0] ?? 0;
+    const cy = corner[1] ?? 0;
+    const cz = corner[2] ?? 0;
+    const x = (world[0] ?? 0) * cx + (world[4] ?? 0) * cy + (world[8] ?? 0) * cz + (world[12] ?? 0);
+    const y = (world[1] ?? 0) * cx + (world[5] ?? 0) * cy + (world[9] ?? 0) * cz + (world[13] ?? 0);
+    const z =
+      (world[2] ?? 0) * cx + (world[6] ?? 0) * cy + (world[10] ?? 0) * cz + (world[14] ?? 0);
+    const w =
+      (world[3] ?? 0) * cx + (world[7] ?? 0) * cy + (world[11] ?? 0) * cz + (world[15] ?? 1);
+    const base = index * 4;
+    output[base] =
+      (viewProjection[0] ?? 0) * x +
+      (viewProjection[4] ?? 0) * y +
+      (viewProjection[8] ?? 0) * z +
+      (viewProjection[12] ?? 0) * w;
+    output[base + 1] =
+      (viewProjection[1] ?? 0) * x +
+      (viewProjection[5] ?? 0) * y +
+      (viewProjection[9] ?? 0) * z +
+      (viewProjection[13] ?? 0) * w;
+    output[base + 2] =
+      (viewProjection[2] ?? 0) * x +
+      (viewProjection[6] ?? 0) * y +
+      (viewProjection[10] ?? 0) * z +
+      (viewProjection[14] ?? 0) * w;
+    output[base + 3] =
+      (viewProjection[3] ?? 0) * x +
+      (viewProjection[7] ?? 0) * y +
+      (viewProjection[11] ?? 0) * z +
+      (viewProjection[15] ?? 0) * w;
+  }
+  return output;
+}