@forgeax/engine-render 0.1.29 → 0.1.31

package/src/assembly/material/assembly.ts

@@ -9,8 +9,13 @@ import {
 import {
   createStandardPbrArtifactReceipt,
   type MaterialShaderArtifact,
+  type MaterialShaderArtifactReceipt,
+  type MaterialShaderEntry,
+  type MaterialShaderManifestEntry,
+  type ShaderRegistry,
 } from '@forgeax/engine-shader';
-import type { StandardLayerPlan } from '@forgeax/engine-types';
+import type { MaterialProgramAddress, StandardLayerPlan } from '@forgeax/engine-types';
+import { resolveMaterialShaderUvSetCount } from '../material-shader-policy';
 import { projectStandardLayerPlan } from './standard-layer-projection.js';
 
 export type { MaterialRenderPassProjection } from '@forgeax/engine-assets-runtime';
@@ -36,28 +41,142 @@ export function assembleMaterialProjection(record: CookedMaterialRecord): Materi
 }
 
 /**
- * Assemble the one built-in Standard PBR artifact from the selected producer WGSL.
+ * Assemble the one built-in Standard PBR artifact from the registry-owned entry.
  * Both rigid and skinned identifiers use this producer; unsupported identifiers
  * stay outside the GPU-driven Standard PBR lane.
  */
 export function assembleStandardPbrArtifact(
   materialShaderId: string,
   wgsl: string,
-  vertexColorAvailable = false,
+  vertexColorAvailable?: boolean,
+): MaterialShaderArtifact | undefined;
+export function assembleStandardPbrArtifact(
+  materialShaderId: string,
+  shaderEntry: MaterialShaderEntry,
+  options?: MaterialShaderArtifactRequest,
+): MaterialShaderArtifact | undefined;
+export function assembleStandardPbrArtifact(
+  materialShaderId: string,
+  shaderEntryOrWgsl: MaterialShaderEntry | string,
+  optionsOrVertexColor: MaterialShaderArtifactRequest | boolean = {},
 ): MaterialShaderArtifact | undefined {
   const skinned =
     materialShaderId === 'forgeax::pbr-skin' ||
     materialShaderId === 'forgeax::default-standard-pbr-skin';
   if (materialShaderId !== 'forgeax::default-standard-pbr' && !skinned) return undefined;
 
-  const receipt = createStandardPbrArtifactReceipt(skinned, vertexColorAvailable);
+  const options =
+    typeof optionsOrVertexColor === 'boolean'
+      ? { vertexColorAvailable: optionsOrVertexColor }
+      : optionsOrVertexColor;
+  const shaderEntry: MaterialShaderEntry =
+    typeof shaderEntryOrWgsl === 'string'
+      ? {
+          source: shaderEntryOrWgsl,
+          paramSchema: [],
+          receipt: createStandardPbrArtifactReceipt(skinned, options.vertexColorAvailable ?? false),
+        }
+      : shaderEntryOrWgsl;
+
+  const publishedReceipt = shaderEntry.receipt;
+  // The legacy no-request call remains source-compatible for the built-in
+  // Standard lane. Once a geometry fact is requested, however, the receipt
+  // must come from the producer-selected artifact; synthesising a different
+  // color layout here would let source, pipeline, and vertex ABI diverge.
+  if (
+    options.vertexColorAvailable !== undefined &&
+    (publishedReceipt === undefined ||
+      receiptHasVertexColor(publishedReceipt) !== options.vertexColorAvailable)
+  ) {
+    return undefined;
+  }
+  const receipt = publishedReceipt ?? createStandardPbrArtifactReceipt(skinned);
+  return {
+    material: materialShaderId,
+    pass: options.pass ?? 'forward',
+    wgsl: shaderEntry.source,
+    layoutIdentity: receipt.reflection.layoutIdentity,
+    bindings: [],
+    deps: [],
+    ...(options.variantSet === undefined ? {} : { variantSet: options.variantSet }),
+    ...(options.address === undefined
+      ? {}
+      : {
+          vertexEntry:
+            options.address === 'scene-index' ? receipt.sceneIndexEntry : receipt.directEntry,
+        }),
+    vertexInputs: receipt.vertexInputs.map(
+      (input): Readonly<Record<string, unknown>> => ({
+        semantic: input.semantic,
+        location: input.location,
+        format: input.format,
+      }),
+    ),
+    receipt,
+  };
+}
+
+export interface MaterialShaderArtifactRequest {
+  /** Geometry-owned COLOR_0 fact used to select the matching published variant. */
+  readonly vertexColorAvailable?: boolean;
+  /** Deformation lane used to select a skin-compatible shadow variant. */
+  readonly deformation?: 'rigid' | 'skin';
+  readonly clustered?: boolean;
+  readonly reflectionFallback?: boolean;
+  readonly variantSet?: string;
+  /** Submission address requested by the consumer; GPU-driven uses scene-index. */
+  readonly address?: MaterialProgramAddress;
+  /** Concrete Pass whose entry metadata is being assembled. */
+  readonly pass?: 'forward' | 'shadow' | 'depth';
+}
+
+function receiptHasVertexColor(receipt: MaterialShaderArtifactReceipt): boolean {
+  return receipt.vertexInputs.some((input) => input.semantic === 'color');
+}
+
+function receiptUvSetCount(receipt: MaterialShaderArtifactReceipt): number {
+  let count = 0;
+  for (const input of receipt.vertexInputs) {
+    if (input.semantic === 'uv') count = Math.max(count, 1);
+    else if (/^uv([1-7])$/.test(input.semantic)) {
+      count = Math.max(count, Number(input.semantic.slice(2)) + 1);
+    }
+  }
+  return count;
+}
+
+function assemblePublishedArtifact(
+  materialShaderId: string,
+  shaderEntry: MaterialShaderEntry,
+  options: MaterialShaderArtifactRequest,
+  reflectedUvSetCount?: number,
+): MaterialShaderArtifact | undefined {
+  const receipt = shaderEntry.receipt;
+  if (receipt === undefined) return undefined;
+  if (
+    options.vertexColorAvailable !== undefined &&
+    receiptHasVertexColor(receipt) !== options.vertexColorAvailable
+  ) {
+    return undefined;
+  }
   return {
     material: materialShaderId,
-    pass: 'forward',
-    wgsl,
+    pass: options.pass ?? 'forward',
+    wgsl: shaderEntry.source,
     layoutIdentity: receipt.reflection.layoutIdentity,
     bindings: [],
     deps: [],
+    uvSetCount:
+      resolveMaterialShaderUvSetCount(shaderEntry.source, reflectedUvSetCount) ??
+      receiptUvSetCount(receipt),
+    ...(options.variantSet === undefined ? {} : { variantSet: options.variantSet }),
+    ...(options.address === undefined
+      ? {}
+      : {
+          vertexEntry:
+            options.address === 'scene-index' ? receipt.sceneIndexEntry : receipt.directEntry,
+        }),
+    ...(options.pass === 'shadow' ? { fragmentEntry: 'fs_shadow' } : {}),
     vertexInputs: receipt.vertexInputs.map(
       (input): Readonly<Record<string, unknown>> => ({
         semantic: input.semantic,
@@ -68,3 +187,228 @@ export function assembleStandardPbrArtifact(
     receipt,
   };
 }
+
+function selectedMaterialShaderEntry(
+  entry: Pick<MaterialShaderEntry, 'paramSchema'>,
+  source: string,
+  receipt: MaterialShaderArtifactReceipt | undefined,
+): MaterialShaderEntry {
+  return {
+    source,
+    paramSchema: entry.paramSchema,
+    ...(receipt === undefined ? {} : { receipt }),
+  };
+}
+
+function selectPublishedVariant(
+  entry: {
+    readonly variants: readonly {
+      readonly definesKey: string;
+      readonly defines: Readonly<Record<string, boolean>>;
+      readonly composedWgsl: string;
+      readonly receipt?: MaterialShaderArtifactReceipt;
+    }[];
+  },
+  options: MaterialShaderArtifactRequest,
+): (typeof entry.variants)[number] | undefined {
+  const desiredColor = options.vertexColorAvailable;
+  const declaresColorAxis = entry.variants.some((variant) =>
+    Object.hasOwn(variant.defines, 'VERTEX_COLOR_AVAILABLE'),
+  );
+  let withColor =
+    desiredColor === undefined || !declaresColorAxis
+      ? [...entry.variants]
+      : entry.variants.filter((variant) => variant.defines.VERTEX_COLOR_AVAILABLE === desiredColor);
+  const declaresSkinningAxis = entry.variants.some((variant) =>
+    Object.hasOwn(variant.defines, 'SKINNING_DISABLED'),
+  );
+  if (options.deformation !== undefined && declaresSkinningAxis) {
+    const skinningDisabled = options.deformation !== 'skin';
+    withColor = withColor.filter(
+      (variant) => variant.defines.SKINNING_DISABLED === skinningDisabled,
+    );
+  }
+  for (const [axis, requested] of [
+    ['CLUSTER_FORWARD_AVAILABLE', options.clustered],
+    ['REFLECTION_FALLBACK_AVAILABLE', options.reflectionFallback],
+  ] as const) {
+    if (
+      requested !== undefined &&
+      entry.variants.some((variant) => Object.hasOwn(variant.defines, axis))
+    ) {
+      withColor = withColor.filter((variant) => variant.defines[axis] === requested);
+    }
+  }
+  if (options.variantSet === undefined) {
+    // Coverage-only is an explicit temporal producer variant. Ordinary
+    // material publication must stay on the color-producing shader.
+    withColor = withColor.filter((variant) => variant.defines.COVERAGE_ONLY !== true);
+  }
+  if (options.variantSet !== undefined) {
+    return withColor.find((variant) => variant.definesKey === options.variantSet);
+  }
+  // GPU-driven Standard owns the storage-backed scene-index variant. Prefer that exact family, then fall back to the closest variant
+  // carrying the requested COLOR_0 fact. This keeps the selection deterministic
+  // without making capability names an admission whitelist.
+  const ranked = withColor
+    .map((variant) => ({
+      variant,
+      score:
+        (variant.defines.STORAGE_BUFFER_AVAILABLE === true ? 8 : 0) +
+        (variant.defines.GPU_DRIVEN_SCENE_INDEX_AVAILABLE === true ? 4 : 0) +
+        (variant.defines.CLUSTER_FORWARD_AVAILABLE === false ? 2 : 0) +
+        (variant.defines.PROBE_BLEND_AVAILABLE === false ? 1 : 0) +
+        (variant.defines.TRANSMISSION_AVAILABLE === false ? 1 : 0),
+    }))
+    .sort(
+      (left, right) =>
+        right.score - left.score || left.variant.definesKey.localeCompare(right.variant.definesKey),
+    );
+  return ranked[0]?.variant;
+}
+
+function materialShaderLookupIds(materialShaderId: string): readonly string[] {
+  return materialShaderId === 'forgeax::pbr-skin'
+    ? ['forgeax::pbr-skin', 'forgeax::default-standard-pbr-skin']
+    : materialShaderId === 'forgeax::default-standard-pbr-skin'
+      ? ['forgeax::default-standard-pbr-skin', 'forgeax::pbr-skin']
+      : [materialShaderId];
+}
+
+const STANDARD_SHADOW_CASTER_ID = 'forgeax::default-shadow-caster';
+
+function isBuiltinStandardPbrMaterialShader(materialShaderId: string): boolean {
+  return (
+    materialShaderId === 'forgeax::default-standard-pbr' ||
+    materialShaderId === 'forgeax::default-standard-pbr-skin' ||
+    materialShaderId === 'forgeax::pbr-skin'
+  );
+}
+
+/** Resolve the registry-owned Standard PBR artifact, including the historical skin alias. */
+export function resolveStandardPbrArtifact(
+  materialShaderId: string,
+  shader: Pick<ShaderRegistry, 'findMaterialArtifact'> &
+    Partial<Pick<ShaderRegistry, 'materialShaderManifestEntries'>>,
+  options: MaterialShaderArtifactRequest = {},
+): MaterialShaderArtifact | undefined {
+  const lookupIds = materialShaderLookupIds(materialShaderId);
+  for (const lookupId of lookupIds) {
+    const lookup = shader.findMaterialArtifact(lookupId);
+    if (!lookup.ok) continue;
+    const manifestEntry =
+      shader.materialShaderManifestEntries === undefined
+        ? undefined
+        : Array.from(shader.materialShaderManifestEntries()).find(
+            (entry) => entry.identifier === lookupId,
+          );
+    const selected =
+      manifestEntry === undefined || manifestEntry.variants.length === 0
+        ? undefined
+        : selectPublishedVariant(manifestEntry, options);
+    const selectedEntry =
+      selected === undefined
+        ? lookup.value
+        : selectedMaterialShaderEntry(lookup.value, selected.composedWgsl, selected.receipt);
+    const artifact = assembleStandardPbrArtifact(materialShaderId, selectedEntry, options);
+    if (artifact === undefined) return undefined;
+    // A variant source without producer receipt is not safe to admit on a
+    // geometry-specific path. The assembly helper keeps its legacy fallback
+    // only for callers that did not provide a geometry fact.
+    if (
+      options.vertexColorAvailable !== undefined &&
+      artifact.receipt !== undefined &&
+      receiptHasVertexColor(artifact.receipt) !== options.vertexColorAvailable
+    ) {
+      return undefined;
+    }
+    return selected === undefined ? artifact : { ...artifact, variantSet: selected.definesKey };
+  }
+  return undefined;
+}
+
+// Registry entries and manifest publications are immutable. Replace the projection
+// when either owner identity changes; old registrations remain weakly held.
+const publishedArtifacts = new WeakMap<
+  MaterialShaderEntry,
+  {
+    readonly manifest: MaterialShaderManifestEntry | undefined;
+    readonly requests: Map<string, MaterialShaderArtifact>;
+  }
+>();
+
+/**
+ * Resolve any producer-published material artifact through the same manifest
+ * variant relation as Standard. Unlike the Standard compatibility helper this
+ * never fabricates a receipt: a custom shader without producer ABI remains
+ * outside the GPU-driven lane with a structured preparation error.
+ */
+export function resolveMaterialShaderArtifact(
+  materialShaderId: string,
+  shader: Pick<ShaderRegistry, 'findMaterialArtifact'> &
+    Partial<Pick<ShaderRegistry, 'materialShaderManifestEntries'>>,
+  options: MaterialShaderArtifactRequest = {},
+): MaterialShaderArtifact | undefined {
+  const lookupIds =
+    options.pass === 'shadow' && isBuiltinStandardPbrMaterialShader(materialShaderId)
+      ? [STANDARD_SHADOW_CASTER_ID]
+      : materialShaderLookupIds(materialShaderId);
+  for (const lookupId of lookupIds) {
+    const lookup = shader.findMaterialArtifact(lookupId);
+    if (!lookup.ok) continue;
+    const manifestEntry =
+      shader.materialShaderManifestEntries === undefined
+        ? undefined
+        : Array.from(shader.materialShaderManifestEntries()).find(
+            (entry) => entry.identifier === lookupId,
+          );
+    let cache = publishedArtifacts.get(lookup.value);
+    if (cache === undefined || cache.manifest !== manifestEntry) {
+      cache = { manifest: manifestEntry, requests: new Map() };
+      publishedArtifacts.set(lookup.value, cache);
+    }
+    const requestKey = JSON.stringify([
+      materialShaderId,
+      options.vertexColorAvailable,
+      options.deformation,
+      options.clustered,
+      options.reflectionFallback,
+      options.variantSet,
+      options.address,
+      options.pass,
+    ]);
+    const cached = cache.requests.get(requestKey);
+    if (cached !== undefined) return cached;
+    const selected =
+      manifestEntry === undefined || manifestEntry.variants.length === 0
+        ? undefined
+        : selectPublishedVariant(manifestEntry, options);
+    // A published variant set is an explicit producer contract. Falling back
+    // to the primary entry when the requested axes have no variant would pair
+    // one source with another artifact's receipt.
+    if (
+      manifestEntry !== undefined &&
+      manifestEntry.variants.length > 0 &&
+      selected === undefined
+    ) {
+      continue;
+    }
+    const selectedEntry =
+      selected === undefined
+        ? lookup.value
+        : selectedMaterialShaderEntry(lookup.value, selected.composedWgsl, selected.receipt);
+    const artifact = assemblePublishedArtifact(
+      lookupId === STANDARD_SHADOW_CASTER_ID ? lookupId : materialShaderId,
+      selectedEntry,
+      options,
+      manifestEntry?.uvSetCount,
+    );
+    if (artifact !== undefined) {
+      const published =
+        selected === undefined ? artifact : { ...artifact, variantSet: selected.definesKey };
+      cache.requests.set(requestKey, published);
+      return published;
+    }
+  }
+  return undefined;
+}

package/src/assembly/material/pipeline-helpers.ts

@@ -0,0 +1,100 @@
+import type { BindGroupLayout } from '@forgeax/engine-rhi';
+import type { MaterialShaderArtifact, ShaderRegistry } from '@forgeax/engine-shader';
+import { type GpuDrivenPbrProgram, resolveStandardPbrProgram } from '../../gpu-driven/pbr-program';
+import type { LayoutKind } from '../material-shader-policy';
+import { type MaterialShaderArtifactRequest, resolveMaterialShaderArtifact } from './assembly';
+
+type MaterialArtifactRegistry = Pick<ShaderRegistry, 'findMaterialArtifact'> &
+  Partial<Pick<ShaderRegistry, 'materialShaderManifestEntries'>>;
+
+export function resolveRendererMaterialShaderArtifact(
+  materialShaderId: string,
+  shader: MaterialArtifactRegistry,
+  programs: ReadonlyMap<string, GpuDrivenPbrProgram> | undefined,
+  options: MaterialShaderArtifactRequest | boolean = {},
+): MaterialShaderArtifact | undefined {
+  if (typeof options === 'boolean') {
+    return resolveStandardPbrProgram(programs, materialShaderId, options)?.artifact;
+  }
+  const resolved = resolveMaterialShaderArtifact(materialShaderId, shader, options);
+  if (resolved !== undefined) return resolved;
+  // Legacy callers without geometry facts may reuse a prewarmed Standard
+  // program; geometry-specific requests remain fail-closed.
+  return Object.keys(options).length === 0
+    ? resolveStandardPbrProgram(programs, materialShaderId, false)?.artifact
+    : undefined;
+}
+
+export function resolveMaterialPipelineShaderId(
+  materialShaderId: string,
+  passKind: string,
+): string {
+  return passKind === 'shadow-caster' &&
+    (materialShaderId === 'forgeax::default-standard-pbr' ||
+      materialShaderId === 'forgeax::default-standard-pbr-skin' ||
+      materialShaderId === 'forgeax::pbr-skin')
+    ? 'forgeax::default-shadow-caster'
+    : materialShaderId;
+}
+
+export function resolveMaterialPipelineVertexEntry(
+  layoutKind: LayoutKind | undefined,
+  vertexEntryPoint: string | undefined,
+  authoredVertexEntry: string | undefined,
+): string | undefined {
+  const sceneIndex = layoutKind === 'gpu-driven-pbr' || layoutKind === 'gpu-driven-skin';
+  // Scene-index is a renderer submission ABI. An authored/direct entry may
+  // accompany the artifact for diagnostics, but it must not replace the
+  // receipt entry when the GPU-driven layout is selected.
+  return sceneIndex
+    ? (vertexEntryPoint ?? authoredVertexEntry)
+    : (authoredVertexEntry ?? vertexEntryPoint);
+}
+
+export interface MaterialPipelineBindGroupState {
+  readonly meshBindGroupLayout: BindGroupLayout;
+  readonly pbrSkinMeshBindGroupLayout: BindGroupLayout | null;
+  readonly hdrpSkinMeshBindGroupLayout: BindGroupLayout | null;
+  readonly hdrpMeshBindGroupLayout?: BindGroupLayout | null;
+  readonly instancesBindGroupLayout: BindGroupLayout;
+  readonly gpuDrivenInstancesBindGroupLayout?: BindGroupLayout | null;
+}
+
+export function resolveMaterialPipelineBindGroups(
+  layoutKind: LayoutKind,
+  state: MaterialPipelineBindGroupState,
+  clustered = false,
+): { readonly meshLayout: BindGroupLayout; readonly instancesLayout: BindGroupLayout } | null {
+  const meshLayout =
+    clustered && layoutKind === 'gpu-driven-pbr'
+      ? state.hdrpMeshBindGroupLayout
+      : clustered && layoutKind === 'gpu-driven-skin'
+        ? state.hdrpSkinMeshBindGroupLayout
+        : layoutKind === 'pbr-skin' || layoutKind === 'gpu-driven-skin'
+          ? state.pbrSkinMeshBindGroupLayout
+          : layoutKind === 'hdrp-skin'
+            ? state.hdrpSkinMeshBindGroupLayout
+            : state.meshBindGroupLayout;
+  if (meshLayout == null) return null;
+  const instancesLayout =
+    layoutKind === 'gpu-driven-pbr' || layoutKind === 'gpu-driven-skin'
+      ? state.gpuDrivenInstancesBindGroupLayout
+      : state.instancesBindGroupLayout;
+  return instancesLayout === null || instancesLayout === undefined
+    ? null
+    : { meshLayout, instancesLayout };
+}
+
+export function isEngineOwnedMaterialShader(materialShaderId: string): boolean {
+  return (
+    materialShaderId === 'forgeax::default-unlit' ||
+    materialShaderId === 'forgeax::default-shadow-caster' ||
+    materialShaderId === 'forgeax::sprite' ||
+    materialShaderId === 'forgeax::sprite-lit' ||
+    materialShaderId === 'forgeax::default-sprite' ||
+    materialShaderId === 'forgeax::msdf-text' ||
+    materialShaderId === 'forgeax::default-standard-pbr' ||
+    materialShaderId === 'forgeax::pbr-skin' ||
+    materialShaderId === 'forgeax::default-standard-pbr-skin'
+  );
+}

package/src/assembly/material-shader-policy.ts

@@ -280,8 +280,7 @@ export async function prepareMaterialShaders(
   ]);
 
   // ── Step 0: storage-buffer cap gate ───────────────────────────────────────
-  const capValue = (rhiDevice.limits as Readonly<Record<string, number>>)
-    .maxStorageBuffersPerShaderStage;
+  const capValue = rhiDevice.limits.maxStorageBuffersPerShaderStage;
   const webgl2Downlevel = rhiDevice.caps.backendKind === 'wgpu-webgl2';
   let storageBufferCapable = !webgl2Downlevel && rhiDevice.caps.storageBuffer;
   if (typeof capValue === 'number') {
@@ -350,6 +349,12 @@ export async function prepareMaterialShaders(
     if (msEntry.variants.some((v) => 'VERTEX_COLOR_AVAILABLE' in v.defines)) {
       variantDefines.VERTEX_COLOR_AVAILABLE = false;
     }
+    if (msEntry.variants.some((v) => 'COVERAGE_ONLY' in v.defines)) {
+      // Coverage-only is a producer-owned opt-in for sprite/temporal paths.
+      // Keep the ordinary boot material on the opaque variant; record-time
+      // coverage batches request the true variant explicitly.
+      variantDefines.COVERAGE_ONLY = false;
+    }
     if (msEntry.variants.some((v) => 'PROBE_BLEND_AVAILABLE' in v.defines)) {
       variantDefines.PROBE_BLEND_AVAILABLE = false;
     }
@@ -422,6 +427,9 @@ export async function prepareMaterialShaders(
       registry.installMaterialArtifact(msEntry.identifier, {
         source: wgsl,
         paramSchema,
+        ...(chosen?.receipt === undefined && msEntry.receipt === undefined
+          ? {}
+          : { receipt: chosen?.receipt ?? msEntry.receipt }),
       });
       // feat-20260629 M4: store uvSetCount from naga reflection for
       // auto-fill in getMaterialShaderPipeline clamp-to-last alias.
@@ -470,6 +478,7 @@ export async function prepareMaterialShaders(
       registry.installMaterialArtifact(shadowCasterIdentifier, {
         source: manifestEntry.composedWgsl,
         paramSchema: STANDARD_PIPELINE_PARAM_SCHEMA,
+        ...(manifestEntry.receipt === undefined ? {} : { receipt: manifestEntry.receipt }),
       });
       const shaderGuid = ENGINE_SHADER_GUIDS.get(shadowCasterIdentifier);
       if (shaderGuid !== undefined) {
@@ -604,9 +613,12 @@ export function selectNoColorPbrVariant(
 ): MaterialShaderManifestEntry['variants'][number] | undefined {
   const hdrpRequested = variantSet === '' || requestsClusterVariant(variantSet);
   const probeBlendRequested = requestsProbeBlendVariant(variantSet);
+  const coverageOnlyRequested = variantSet?.includes('COVERAGE_ONLY=true') === true;
   return manifestEntry?.variants.find(
     (variant) =>
       variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
+      (!('COVERAGE_ONLY' in variant.defines) ||
+        variant.defines.COVERAGE_ONLY === coverageOnlyRequested) &&
       (!('EXTENDED_LIGHTING_AVAILABLE' in variant.defines) ||
         variant.defines.EXTENDED_LIGHTING_AVAILABLE === extendedLightingShaderAvailable) &&
       variant.defines.VERTEX_COLOR_AVAILABLE === false &&
@@ -896,6 +908,7 @@ export function resolveMaterialShaderVariantSet(
 ): string | undefined {
   const declaredAxes = new Set(variants.flatMap((variant) => Object.keys(variant.defines)));
   const declaresCapabilityVariants =
+    declaredAxes.has('COVERAGE_ONLY') ||
     declaredAxes.has('WEBGL2_COMPAT') ||
     declaredAxes.has('STORAGE_BUFFER_AVAILABLE') ||
     declaredAxes.has('EXTENDED_LIGHTING_AVAILABLE') ||
@@ -933,23 +946,31 @@ export function resolveMaterialShaderVariantSet(
           ? backendKind !== 'wgpu-webgl2' && storageBuffer
           : axis === 'SKINNING_DISABLED'
             ? (requested[axis] ?? true)
-            : axis === 'CLUSTER_FORWARD_AVAILABLE'
-              ? storageBuffer && backendKind !== 'wgpu-webgl2' && (requested[axis] ?? false)
-              : axis === 'PER_INSTANCE_REGION'
-                ? requestedVariantSet === '' || (requested[axis] ?? false)
-                : axis === 'VERTEX_COLOR_AVAILABLE'
+            : axis === 'ALPHA_MASK' ||
+                axis === 'GPU_DRIVEN_SCENE_INDEX_AVAILABLE' ||
+                axis === 'GPU_DRIVEN_SCENE_INDEX_EXPLICIT' ||
+                axis === 'COVERAGE_ONLY'
+              ? (requested[axis] ?? false)
+              : axis === 'CLUSTER_FORWARD_AVAILABLE'
+                ? storageBuffer && backendKind !== 'wgpu-webgl2' && (requested[axis] ?? false)
+                : axis === 'PER_INSTANCE_REGION'
                   ? requestedVariantSet === '' || (requested[axis] ?? false)
-                  : axis === 'EXTENDED_LIGHTING_AVAILABLE'
-                    ? extendedLightingAvailable
-                    : axis === 'PROBE_BLEND_AVAILABLE'
-                      ? storageBuffer && (requested[axis] ?? false)
-                      : axis === 'TRANSMISSION_AVAILABLE'
-                        ? (requested[axis] ?? false)
-                        : axis === 'DIRECTIONAL_PCSS_AVAILABLE'
-                          ? directionalPcssCapable(backendKind)
-                          : axis === 'PROJECTOR_AVAILABLE'
-                            ? projectorAvailable
-                            : (requested[axis] ?? false);
+                  : axis === 'VERTEX_COLOR_AVAILABLE'
+                    ? requestedVariantSet === '' || (requested[axis] ?? false)
+                    : axis === 'EXTENDED_LIGHTING_AVAILABLE'
+                      ? extendedLightingAvailable
+                      : axis === 'PROBE_BLEND_AVAILABLE'
+                        ? storageBuffer && (requested[axis] ?? false)
+                        : axis === 'TRANSMISSION_AVAILABLE' ||
+                            axis === 'REFLECTION_FALLBACK_AVAILABLE'
+                          ? (requested[axis] ?? false)
+                          : axis === 'DIRECTIONAL_PCSS_AVAILABLE'
+                            ? directionalPcssCapable(backendKind)
+                            : axis === 'PROJECTOR_AVAILABLE'
+                              ? projectorAvailable
+                              : // Authored axes keep the manifest's all-true default.
+                                // Only Engine-owned admission axes default to disabled.
+                                (requested[axis] ?? true);
   }
   const sorted = Object.entries(filtered).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
   return sorted.every(([, value]) => value)

package/src/assembly/recovery/device-loss-fanout.ts

@@ -50,6 +50,11 @@ export function attachDeviceLostFanout(
     }
     onDeviceLost?.(detail);
     lostRegistry.fire(safe);
+    // A `destroyed` loss is the terminal signal from an intentional
+    // GPUDevice.destroy() call. It is observable through the lost channel,
+    // but must not put the renderer into recoverable device-lost health or
+    // emit an error during normal teardown. Only an unexpected loss keeps the
+    // recovery/error fan-out active.
     if (safe.reason !== 'destroyed') {
       pack.instrumentation?.onDeviceLost?.();
       healthRegistry.fire({

package/src/assembly/recovery/recovery-attempt.ts

@@ -12,6 +12,7 @@ import {
 } from '@forgeax/engine-rhi';
 import { ok, type Result } from '@forgeax/engine-types';
 import type { RhiBackendPack } from '../backend-contract';
+import { deviceOptionsForAdapter } from '../device-feature-admission';
 import {
   RECOVERY_ADAPTER_DEADLINE_MS,
   RECOVERY_DEVICE_DEADLINE_MS,
@@ -20,13 +21,7 @@ import {
   type RecoveryPhase,
 } from '../renderer-lifecycle';
 
-const COMPRESSION_FEATURES: GPUFeatureName[] = [
-  'texture-compression-bc',
-  'texture-compression-etc2',
-  'texture-compression-astc',
-];
-
-export const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 17;
+export { deviceOptionsForAdapter } from '../device-feature-admission';
 
 const PROBE_TEXTURE_USAGE_COPY_SRC = 0x01;
 const PROBE_TEXTURE_USAGE_RENDER_ATTACHMENT = 0x10;
@@ -573,28 +568,6 @@ export async function probeCandidateGraphExecution(
   }
 }
 
-export function deviceOptionsForAdapter(adapter: Pick<RhiAdapter, 'features' | 'limits'>):
-  | {
-      requiredFeatures?: GPUFeatureName[];
-      requiredLimits?: GPUDeviceDescriptor['requiredLimits'];
-    }
-  | undefined {
-  const requiredFeatures = COMPRESSION_FEATURES.filter((feature) => adapter.features.has(feature));
-  const supportsTransmission =
-    (adapter.limits.maxSampledTexturesPerShaderStage ?? 0) >=
-    STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES;
-  return {
-    ...(requiredFeatures.length > 0 ? { requiredFeatures } : {}),
-    ...(supportsTransmission
-      ? {
-          requiredLimits: {
-            maxSampledTexturesPerShaderStage: STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES,
-          },
-        }
-      : {}),
-  };
-}
-
 export interface AcquiredDeviceGeneration {
   readonly adapter: RhiAdapter;
   readonly device: RhiDevice;