@forgeax/engine-render 0.1.24 → 0.1.26

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

@@ -12,6 +12,7 @@ import {
   type MaterialShaderManifestEntry,
   type ShaderCatalog,
   type ShaderCatalogDevice,
+  STANDARD_PIPELINE_PARAM_SCHEMA,
   standardPhysicalTextureFields,
 } from '@forgeax/engine-shader';
 import type { AssetGuid as AssetGuidType, ParamSchemaEntry } from '@forgeax/engine-types';
@@ -282,11 +283,10 @@ export async function prepareMaterialShaders(
   const capValue = (rhiDevice.limits as Readonly<Record<string, number>>)
     .maxStorageBuffersPerShaderStage;
   const webgl2Downlevel = rhiDevice.caps.backendKind === 'wgpu-webgl2';
-  let storageBufferCapable = !webgl2Downlevel;
-  if (typeof capValue === 'number') {
+  const storageBufferCapable = rhiDevice.caps.storageBuffer;
+  if (storageBufferCapable && typeof capValue === 'number') {
     const capCheck = assertStorageBufferCap(capValue);
     if (!capCheck.ok) throw capCheck.error;
-    storageBufferCapable = !webgl2Downlevel && capCheck.value;
   }
   const extendedLightingShaderAvailable = deriveExtendedLightingCapability(rhiDevice).admitted;
   const projectorAvailable =
@@ -314,9 +314,10 @@ export async function prepareMaterialShaders(
     // engine-entry compile path, NOT by installMaterialArtifact.
     if (msEntry.identifier.startsWith('forgeax::engine-')) continue;
     // buildVariantKey logic: sorted key=value pairs joined with +; all-true = ''.
-    const variantDefines: Record<string, boolean> = {
-      STORAGE_BUFFER_AVAILABLE: storageBufferCapable,
-    };
+    const variantDefines: Record<string, boolean> = {};
+    if (msEntry.variants.some((variant) => 'STORAGE_BUFFER_AVAILABLE' in variant.defines)) {
+      variantDefines.STORAGE_BUFFER_AVAILABLE = storageBufferCapable;
+    }
     // User material manifests may declare WEBGL2_COMPAT alongside the shared
     // mesh-storage axis. The fallback backend must select that authored
     // branch at boot; otherwise it asks for the impossible bare
@@ -450,11 +451,12 @@ export async function prepareMaterialShaders(
       (candidate) => candidate.identifier === shadowCasterIdentifier,
     );
     if (manifestEntry !== undefined) {
-      // shadow_caster has no authored material parameters. M3 / w12-w13
-      // (D-2 / D-12): derive([]) is the graceful empty-schema path.
+      // shadow_caster evaluates the same default Surface as Standard. Keep
+      // its generated MaterialParameters contract aligned with the Standard
+      // pipeline even when a legacy manifest omitted the material entry.
       registry.installMaterialArtifact(shadowCasterIdentifier, {
         source: manifestEntry.composedWgsl,
-        paramSchema: [],
+        paramSchema: STANDARD_PIPELINE_PARAM_SCHEMA,
       });
       const shaderGuid = ENGINE_SHADER_GUIDS.get(shadowCasterIdentifier);
       if (shaderGuid !== undefined) {
@@ -462,7 +464,7 @@ export async function prepareMaterialShaders(
           kind: 'shader' as const,
           name: shadowCasterIdentifier,
           source: manifestEntry.composedWgsl,
-          paramSchema: [] as readonly import('@forgeax/engine-types').ParamSchemaEntry[],
+          paramSchema: STANDARD_PIPELINE_PARAM_SCHEMA,
         };
         // feat-20260614 M8 (D-17): catalogue by GUID; no handle minted.
         assets.catalog(shaderGuid, shaderAsset);
@@ -659,6 +661,82 @@ export function resolveMaterialShaderVertexInputContract(
     : 'none';
 }
 
+/**
+ * Resolve the number of UV sets declared by one material artifact.
+ *
+ * Runtime-published Surface programs do not necessarily have a manifest
+ * reflection row, so the authored vertex input is the fallback source of
+ * truth. The renderer then feeds this count into the geometry alias
+ * projection, which clamps missing mesh UV sets to the last available set.
+ */
+export function resolveMaterialShaderUvSetCount(
+  source: string | undefined,
+  reflectedCount?: number,
+): number | undefined {
+  if (reflectedCount !== undefined) return reflectedCount;
+  if (source === undefined) return undefined;
+
+  const withoutComments = source.replace(/\/\*[\s\S]*?\*\//gu, '').replace(/\/\/.*$/gmu, '');
+  const inputStructs = [
+    ...withoutComments.matchAll(/struct\s+([A-Za-z_]\w*)\s*\{([^}]*)\}/gu),
+  ].filter((match) => /@location\s*\(/u.test(match[2] ?? ''));
+  for (const inputStruct of inputStructs) {
+    const name = inputStruct[1];
+    const body = inputStruct[2];
+    if (name === undefined || body === undefined) continue;
+    const firstParameter = new RegExp(
+      `@vertex\\s*fn\\s+\\w+\\s*\\(\\s*\\w+\\s*:\\s*${name}\\b`,
+      'u',
+    );
+    if (!firstParameter.test(withoutComments)) continue;
+    let uvSetCount = 0;
+    for (const location of body.matchAll(/@location\s*\(\s*(\d+)\s*\)\s+([A-Za-z_]\w*)/gu)) {
+      const field = location[2];
+      if (field === 'uv') {
+        uvSetCount = Math.max(uvSetCount, 1);
+        continue;
+      }
+      const uvIndex = field?.match(/^uv(\d+)_?$/u)?.[1];
+      if (uvIndex !== undefined) uvSetCount = Math.max(uvSetCount, Number(uvIndex) + 1);
+    }
+    return uvSetCount > 0 ? uvSetCount : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Select a published material artifact that matches a downlevel backend.
+ *
+ * Cooked Surface publications carry immutable backend variants in their
+ * metadata. WebGL2 must select the uniform-fallback specialization before
+ * pipeline construction so its shader, bind-group layout, and cache key stay
+ * capability-consistent.
+ */
+export function resolveMaterialShaderBackendArtifactKey(
+  materialShaderId: string,
+  backendKind: 'webgpu' | 'wgpu-native' | 'wgpu-webgl2' | 'null',
+  artifact:
+    | {
+        readonly metadata?: Readonly<Record<string, unknown>>;
+      }
+    | undefined,
+): string {
+  if (backendKind !== 'wgpu-webgl2') return materialShaderId;
+  const variants = artifact?.metadata?.variants;
+  if (!Array.isArray(variants)) return materialShaderId;
+  const fallback = variants.find((variant): variant is { specializationKey: string } => {
+    if (typeof variant !== 'object' || variant === null) return false;
+    const candidate = variant as Record<string, unknown>;
+    return (
+      candidate.backend === 'webgl2' &&
+      candidate.capability === 'uniform-fallback' &&
+      typeof candidate.specializationKey === 'string' &&
+      candidate.specializationKey.length > 0
+    );
+  });
+  return fallback?.specializationKey ?? materialShaderId;
+}
+
 export function allowsUnlitPreparedFallback(
   depthFormatOverride: GPUTextureFormat | null | undefined,
   vertexLayout: string | undefined,

package/src/assembly/recovery/renderer-recover.ts

@@ -632,7 +632,7 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
       releaseCandidate();
       return err(new RecoverError('recover-device-unavailable'));
     }
-    const graphPreparation = renderSystem.prepareRecoveryGraphCandidate({
+    const graphPreparation = await renderSystem.prepareRecoveryGraphCandidate({
       internals: candidateInternals,
       pipelineState: candidatePipelineState,
     });

package/src/assembly/webgpu-ready.ts

@@ -54,7 +54,6 @@ import {
 } from '../ibl/skylight-bind-group';
 import type { BloomInspection } from '../inspection-types';
 import type { DeviceScope, RhiErrorListenerRegistry } from '../lifecycle';
-import { assertStorageBufferCap } from '../light-buffer-layout';
 import {
   buildPbrPipelineLayouts,
   buildPbrSkinLayouts,
@@ -218,22 +217,10 @@ export async function buildReadyWebGPU(
   setVolumetricFogShaderSources: (sources: VolumetricFogShaderSources) => void,
 ): Promise<PipelineState> {
   const extendedLightingShaderAvailable = deriveExtendedLightingCapability(rhiDevice).admitted;
-  // bug-20260610: WebGL2 fallback path — read storage-buffer capability up
-  // front so both Step 2 (shader-module compile, where we patch engine
-  // entries to the STORAGE_BUFFER_AVAILABLE=false variant) and Step 3
-  // (buildPbrPipelineLayouts, which switches between read-only-storage
-  // and uniform BGL entries) walk the same axis. Step 0 already ran in
-  // `prepareMaterialShaders`; this is an idempotent re-read driven by
-  // `device.limits.maxStorageBuffersPerShaderStage`, which is 0 on the
-  // wgpu-wasm WebGL2 backend (downlevel_webgl2_defaults).
-  const capValue = (rhiDevice.limits as Readonly<Record<string, number>>)
-    .maxStorageBuffersPerShaderStage;
+  // Shader layouts and record-stage buffer usage share the RHI capability.
+  // Backend names and numeric limits must not independently re-enable storage.
+  const storageBufferCapable = rhiDevice.caps.storageBuffer;
   const webgl2Downlevel = rhiDevice.caps.backendKind === 'wgpu-webgl2';
-  let storageBufferCapable = !webgl2Downlevel;
-  if (typeof capValue === 'number') {
-    const capCheck = assertStorageBufferCap(capValue);
-    storageBufferCapable = capCheck.ok ? !webgl2Downlevel && capCheck.value : !webgl2Downlevel;
-  }
   const directionalPcssAvailable =
     rhiDevice.caps.backendKind === 'webgpu' || rhiDevice.caps.backendKind === 'wgpu-native';
   const projectorAvailable =

package/src/assembly/webgpu-renderer.ts

@@ -30,7 +30,6 @@ import { createRenderReadLease, type RenderReadLease } from '@forgeax/engine-ecs
 import {
   deriveVertexBufferLayout,
   deriveVertexBufferLayoutFromProjection,
-  type GpuVertexBufferLayoutEntry,
   type VertexLayoutProjection,
 } from '@forgeax/engine-geometry';
 import type {
@@ -176,7 +175,9 @@ import {
   makeShaderDeviceAdapter,
   normalizeMaterialShaderVariantSet,
   prepareMaterialShaders,
+  resolveMaterialShaderBackendArtifactKey,
   resolveMaterialShaderBindingContract,
+  resolveMaterialShaderUvSetCount,
   resolveMaterialShaderVariantSet,
   resolveMaterialShaderVertexInputContract,
   type ShaderDeviceAdapterInternal,
@@ -214,14 +215,20 @@ import {
 import { STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES } from './shader-prewarm-policy';
 import { buildReadyWebGPU } from './webgpu-ready';
 import { DEPTH_TEXTURE_FORMAT, HDR_COLOR_ATTACHMENT_FORMAT } from './webgpu-ready-contract';
+import {
+  BILLBOARD_MATERIAL_INSTANCE_VERTEX_BUFFERS,
+  DEFAULT_VERTEX_ATTRS,
+  MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS,
+  PBR_SKIN_SENTINEL_ATTR_BUFFER,
+  POSITION_SIZE_COLOR_INSTANCE_VERTEX_BUFFERS,
+  PREPARED_INSTANCE_VERTEX_ATTRS,
+  PREPARED_MATERIAL_INSTANCE_VERTEX_ATTRS,
+  TOPOLOGY_SEGMENT_INSTANCE_VERTEX_BUFFERS,
+  toGpuVertexBufferLayouts,
+} from './webgpu-vertex-layouts';
 
 export type { BundlerOptions } from './bundler-contract';
 export { assembleMaterialProjection } from './material/assembly';
-export {
-  projectMaterialPipeline,
-  routeMaterialPipeline,
-  updateMaterialRuntimeValues,
-} from './material/pipeline-projection';
 export type {
   LayoutKind,
   MaterialShaderBindingContract,
@@ -231,7 +238,9 @@ export {
   allowsUnlitPreparedFallback,
   isSharedMaterialUserRegionCompatible,
   normalizeMaterialShaderVariantSet,
+  resolveMaterialShaderBackendArtifactKey,
   resolveMaterialShaderBindingContract,
+  resolveMaterialShaderUvSetCount,
   resolveMaterialShaderVariantSet,
   resolveMaterialShaderVertexInputContract,
   selectNoColorPbrVariant,
@@ -273,139 +282,6 @@ function adaptMipmapShaderModuleFactory(
 // Transform.world mat4 derivation (audio listener sync + picking read the
 // derived Transform.world from scripts).
 
-// feat-20260611-fox-skinning-vertex-attribute-chain M4 / w16 (D-4): a single
-// shared empty ArrayBuffer used by `buildPipelineContext` to synthesize the
-// 6-key VertexAttributeMap when no caller-supplied attributes are available
-// for the pbr-skin path. `deriveVertexBufferLayout` is the SSOT for the layout
-// (vertex-attribute-layout.ts) and reads only key presence -- value identity
-// never matters -- so a zero-byte ArrayBuffer per key produces the exact
-// 6-attribute / 72-byte stride layout that the @forgeax::pbr-skin shader's
-// @location(0..5) declarations expect.
-const PBR_SKIN_SENTINEL_ATTR_BUFFER = new ArrayBuffer(0);
-
-/** Default 4-attribute vertex layout used as fallback when meshAttributes is undefined. */
-const DEFAULT_VERTEX_ATTRS: VertexAttributeMap = {
-  position: new Float32Array(0),
-  normal: new Float32Array(0),
-  uv: new Float32Array(0),
-  tangent: new Float32Array(0),
-};
-
-const PREPARED_INSTANCE_VERTEX_ATTRS: VertexAttributeMap = {
-  position: new Float32Array(0),
-  normal: new Float32Array(0),
-  uv: new Float32Array(0),
-  tangent: new Float32Array(0),
-  uv1: new Float32Array(0),
-};
-
-const PREPARED_MATERIAL_INSTANCE_VERTEX_ATTRS: VertexAttributeMap = {
-  position: new Float32Array(0),
-  normal: new Float32Array(0),
-  uv: new Float32Array(0),
-  tangent: new Float32Array(0),
-  skinIndex: new Uint16Array(0),
-  skinWeight: new Float32Array(0),
-};
-
-const POSITION_SIZE_COLOR_INSTANCE_VERTEX_BUFFERS = [
-  {
-    arrayStride: 9 * 4,
-    stepMode: 'instance' as const,
-    attributes: [
-      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
-      { shaderLocation: 1, offset: 3 * 4, format: 'float32x2' as const },
-      { shaderLocation: 2, offset: 5 * 4, format: 'float32x4' as const },
-    ],
-  },
-] satisfies readonly GPUVertexBufferLayout[];
-
-const BILLBOARD_MATERIAL_INSTANCE_VERTEX_BUFFERS = [
-  {
-    arrayStride: 31 * 4,
-    stepMode: 'instance' as const,
-    attributes: [
-      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
-      { shaderLocation: 1, offset: 3 * 4, format: 'float32x2' as const },
-      { shaderLocation: 2, offset: 5 * 4, format: 'float32x2' as const },
-      { shaderLocation: 3, offset: 7 * 4, format: 'float32x4' as const },
-      { shaderLocation: 4, offset: 11 * 4, format: 'float32x4' as const },
-      { shaderLocation: 5, offset: 15 * 4, format: 'float32x4' as const },
-      { shaderLocation: 6, offset: 19 * 4, format: 'float32x4' as const },
-      { shaderLocation: 7, offset: 23 * 4, format: 'float32x4' as const },
-      { shaderLocation: 8, offset: 27 * 4, format: 'float32x4' as const },
-    ],
-  },
-] satisfies readonly GPUVertexBufferLayout[];
-
-const TOPOLOGY_SEGMENT_INSTANCE_VERTEX_BUFFERS = [
-  {
-    arrayStride: 12 * 4,
-    stepMode: 'instance' as const,
-    attributes: [
-      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
-      { shaderLocation: 1, offset: 3 * 4, format: 'float32x3' as const },
-      { shaderLocation: 2, offset: 6 * 4, format: 'float32x4' as const },
-      { shaderLocation: 3, offset: 10 * 4, format: 'float32x2' as const },
-    ],
-  },
-] satisfies readonly GPUVertexBufferLayout[];
-
-const MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS = [
-  {
-    arrayStride: 12 * 4,
-    stepMode: 'vertex' as const,
-    attributes: [
-      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
-      { shaderLocation: 1, offset: 3 * 4, format: 'float32x3' as const },
-      { shaderLocation: 2, offset: 6 * 4, format: 'float32x2' as const },
-      { shaderLocation: 3, offset: 8 * 4, format: 'float32x4' as const },
-    ],
-  },
-  {
-    arrayStride: 28 * 4,
-    stepMode: 'instance' as const,
-    attributes: [
-      { shaderLocation: 4, offset: 0, format: 'float32x3' as const },
-      { shaderLocation: 5, offset: 3 * 4, format: 'float32x3' as const },
-      { shaderLocation: 6, offset: 6 * 4, format: 'float32x3' as const },
-      { shaderLocation: 7, offset: 9 * 4, format: 'float32x3' as const },
-      { shaderLocation: 8, offset: 12 * 4, format: 'float32x4' as const },
-      { shaderLocation: 9, offset: 16 * 4, format: 'float32x4' as const },
-      { shaderLocation: 10, offset: 20 * 4, format: 'float32x4' as const },
-      { shaderLocation: 11, offset: 24 * 4, format: 'float32x4' as const },
-    ],
-  },
-] satisfies readonly GPUVertexBufferLayout[];
-
-function toGpuVertexFormat(
-  format: GpuVertexBufferLayoutEntry['attributes'][number]['format'],
-): GPUVertexFormat {
-  switch (format) {
-    case 'float32x2':
-    case 'float32x3':
-    case 'float32x4':
-    case 'uint16x4':
-      return format;
-    default:
-      throw new Error(`Unsupported geometry vertex format: ${format}`);
-  }
-}
-
-function toGpuVertexBufferLayouts(
-  entries: readonly GpuVertexBufferLayoutEntry[],
-): readonly GPUVertexBufferLayout[] {
-  return entries.map((entry) => ({
-    arrayStride: entry.arrayStride,
-    ...(entry.stepMode === undefined ? {} : { stepMode: entry.stepMode }),
-    attributes: entry.attributes.map((attribute) => ({
-      shaderLocation: attribute.shaderLocation,
-      offset: attribute.offset,
-      format: toGpuVertexFormat(attribute.format),
-    })),
-  }));
-}
-
 /**
  * Bundler-layer injection accepted by `createRenderer` (and proxied by
  * `createApp`) as the optional third argument.
@@ -1954,15 +1830,19 @@ async function makeWebGPURenderer(
         vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInstance)
         ? getOrBuildPreparedMaterialPipelineLayout(materialShaderId)
         : null;
+    const materialShaderLookup =
+      materialShaderId === undefined
+        ? undefined
+        : getShader().findMaterialArtifact(materialShaderId);
+    const materialShaderSource = materialShaderLookup?.ok
+      ? materialShaderLookup.value.source
+      : undefined;
     const vertexInputContract =
       materialShaderId === undefined
         ? 'render-material'
-        : (() => {
-            const lookup = getShader().findMaterialArtifact(materialShaderId);
-            return lookup.ok
-              ? resolveMaterialShaderVertexInputContract(lookup.value.source)
-              : 'render-material';
-          })();
+        : materialShaderSource !== undefined
+          ? resolveMaterialShaderVertexInputContract(materialShaderSource)
+          : 'render-material';
     const currentState = currentPipelineState();
     const pipelineLayout =
       group0Layout !== null
@@ -1979,9 +1859,16 @@ async function makeWebGPURenderer(
                   ? perShaderLayout.pipelineLayout
                   : selectPipelineLayoutForVariant(currentState, variantSet, layoutKind);
     if (pipelineLayout === null) return null;
+    const currentMaterialUvSetCounts = currentMaterialShaderUvSetCounts();
     const resolvedUvSetCount =
       materialShaderId !== undefined
-        ? currentMaterialShaderUvSetCounts().get(materialShaderId)
+        ? (currentMaterialUvSetCounts.get(materialShaderId) ??
+          (materialShaderSource !== undefined
+            ? resolveMaterialShaderUvSetCount(
+                materialShaderSource,
+                currentMaterialUvSetCounts.get(materialShaderId),
+              )
+            : undefined))
         : undefined;
     const vertexBuffers: readonly GPUVertexBufferLayout[] =
       vertexInputContract === 'none'
@@ -2110,6 +1997,8 @@ async function makeWebGPURenderer(
     shaderModuleMode?: RenderFeatureShaderModuleMode,
     layoutKindOverride?: LayoutKind,
     additionalColorFormats?: readonly GPUTextureFormat[],
+    vertexEntry?: string,
+    authoredFragmentEntry?: string,
   ): RenderPipeline | null => {
     const group2Contract = resolvePipelineGroup2Contract(entry.source);
     const ctx = buildPipelineContext(
@@ -2132,10 +2021,11 @@ async function makeWebGPURenderer(
     if (currentState === null) return null;
     const ldrColorFormat = colorFormatOverride ?? currentState.colorAttachmentFormat;
     const fragmentEntry =
-      isHdr &&
+      authoredFragmentEntry ??
+      (isHdr &&
       (materialShaderId === 'forgeax::sprite' || materialShaderId === 'forgeax::sprite-lit')
         ? 'fs_main_hdr'
-        : undefined;
+        : undefined);
     const built = buildPipelineForMaterialShader(
       cacheKey,
       // The catalog entry is projected into the material-shader entry shape.
@@ -2172,7 +2062,7 @@ async function makeWebGPURenderer(
               : {}),
           }
         : undefined,
-      undefined, // vertexEntry — default vs_main
+      vertexEntry,
       fragmentEntry,
       undefined, // defines — none
       passKind,
@@ -2239,6 +2129,8 @@ async function makeWebGPURenderer(
     shaderModuleMode: RenderFeatureShaderModuleMode = 'validated',
     layoutKindOverride?: LayoutKind,
     additionalColorFormats?: readonly GPUTextureFormat[],
+    vertexEntry?: string,
+    fragmentEntry?: string,
   ): RenderPipeline | null => {
     // WebGL2 is a downlevel backend even when the record stage asks for the
     // native-capability variant string. Resolve the variant axes at this
@@ -2252,15 +2144,31 @@ async function makeWebGPURenderer(
       (currentState !== null ? currentState.colorAttachmentFormat : 'bgra8unorm-srgb');
     // feat-20260629 M4: auto-fill shaderUvSetCount from naga reflection
     // (stored in materialShaderUvSetCounts during prepareMaterialShaders).
-    const resolvedUvSetCount =
-      shaderUvSetCount ?? currentMaterialShaderUvSetCounts().get(materialShaderId);
-    const manifestEntry = findMaterialShaderManifestEntry(materialShaderId);
+    const pipelineShaderId = resolveMaterialShaderBackendArtifactKey(
+      materialShaderId,
+      internals.device.caps.backendKind,
+      assets.getMaterialArtifact(materialShaderId),
+    );
+    const materialShaderLookup = getShader().findMaterialArtifact(pipelineShaderId);
+    const materialShaderSource = materialShaderLookup.ok
+      ? materialShaderLookup.value.source
+      : undefined;
+    const currentMaterialUvSetCounts = currentMaterialShaderUvSetCounts();
+    const materialUvSetCount = resolveMaterialShaderUvSetCount(
+      materialShaderSource,
+      currentMaterialUvSetCounts.get(pipelineShaderId),
+    );
+    if (materialUvSetCount !== undefined) {
+      currentMaterialUvSetCounts.set(pipelineShaderId, materialUvSetCount);
+    }
+    const resolvedUvSetCount = shaderUvSetCount ?? materialUvSetCount;
+    const manifestEntry = findMaterialShaderManifestEntry(pipelineShaderId);
     // Sprite's omitted request is the boot-selected default artifact. The
     // explicit empty key remains the PER_INSTANCE_REGION=true request used by
     // SpriteInstances, so only that path is capability-rewritten here.
     const resolvedVariantSet =
       variantSet === undefined &&
-      (materialShaderId === 'forgeax::sprite' || materialShaderId === 'forgeax::sprite-lit')
+      (pipelineShaderId === 'forgeax::sprite' || pipelineShaderId === 'forgeax::sprite-lit')
         ? undefined
         : resolveCachedMaterialShaderVariantSet(variantSet, manifestEntry);
     // The record stage also composes engine capability axes for user shaders.
@@ -2272,6 +2180,12 @@ async function makeWebGPURenderer(
     // A single-source manifest entry must stay on its canonical module key;
     // otherwise a synthesized capability axis races the prewarmed module.
     let effectiveVariantSet = normalizeMaterialShaderVariantSet(resolvedVariantSet, manifestEntry);
+    // Runtime-published authored materials are installed from their immutable
+    // cooked artifact, not from the build-time material-shader manifest. The
+    // published artifact identity already selects the backend-specific bytes;
+    // an absent manifest therefore means the source itself is the canonical
+    // pipeline module and must not carry a synthesized capability key.
+    if (manifestEntry === undefined) effectiveVariantSet = undefined;
     if (
       vertexLayoutProjection === undefined &&
       manifestEntry?.variants.some((variant) => 'VERTEX_COLOR_AVAILABLE' in variant.defines)
@@ -2294,7 +2208,7 @@ async function makeWebGPURenderer(
     }
     if (
       manifestEntry !== undefined &&
-      !materialShaderId.startsWith('forgeax::') &&
+      !pipelineShaderId.startsWith('forgeax::') &&
       effectiveVariantSet !== undefined &&
       effectiveVariantSet !== ''
     ) {
@@ -2323,7 +2237,13 @@ async function makeWebGPURenderer(
     const colorFormat: GPUTextureFormat = isHdr ? 'rgba16float' : ldrColorFormat;
     const isDepthOnlyPass = passKindPolicyTable[passKind]?.shape === 'depth-only';
     const spec: PipelineSpec = {
-      shader: { id: materialShaderId, passKind, variantSet: effectiveVariantSet },
+      shader: {
+        id: pipelineShaderId,
+        passKind,
+        variantSet: effectiveVariantSet,
+        ...(vertexEntry === undefined ? {} : { vertexEntry }),
+        ...(fragmentEntry === undefined ? {} : { fragmentEntry }),
+      },
       attachments: {
         colorFormats:
           additionalColorFormats === undefined
@@ -2362,7 +2282,7 @@ async function makeWebGPURenderer(
     const cached = currentPipelineCacheState().materialShaderPipelineCache.get(cacheKey);
     if (cached !== undefined) return cached;
     if (pipelineState === null) return null;
-    const lookup = getShader().findMaterialArtifact(materialShaderId);
+    const lookup = getShader().findMaterialArtifact(pipelineShaderId);
     if (!lookup.ok) {
       if (shouldDeferMissingPreparedMaterialShader(vertexLayout)) {
         // Prepared VFX draws bind only their feature-owned groups. The
@@ -2377,7 +2297,7 @@ async function makeWebGPURenderer(
       // the standard pipeline from the engine-shipped PBR entry.
       if (
         renderState === undefined &&
-        !allowsUnlitPreparedFallback(depthFormatOverride, vertexLayout, materialShaderId)
+        !allowsUnlitPreparedFallback(depthFormatOverride, vertexLayout, pipelineShaderId)
       ) {
         // A prepared feature declares the vertex layout it owns. Falling back
         // to default-unlit here would pair that data with the unlit shader's
@@ -2392,7 +2312,7 @@ async function makeWebGPURenderer(
         return buildAndCachePipeline(
           cacheKey,
           unlitLookup.value,
-          `pbr-pipeline-prepared-${materialShaderId}`,
+          `pbr-pipeline-prepared-${pipelineShaderId}`,
           // Reuse the eagerly compiled engine unlit module. The adapter cache
           // is seeded under this label during renderer readiness; a new label
           // would keep color-only prepared passes in perpetual warm-up.
@@ -2420,7 +2340,7 @@ async function makeWebGPURenderer(
       return buildAndCachePipeline(
         cacheKey,
         { source: pbrEntry.wgsl, paramSchema: [] },
-        `pbr-pipeline-fallback-${materialShaderId}${isHdr ? '-hdr' : ''}`,
+        `pbr-pipeline-fallback-${pipelineShaderId}${isHdr ? '-hdr' : ''}`,
         // w16-b: module identity is the fallback PBR source, stable across
         // topology / renderState / HDR (all baked into the PSO) so every
         // variant reuses one compiled module.
@@ -2454,8 +2374,8 @@ async function makeWebGPURenderer(
         // layout resolution so buildPipelineContext derives the layout that
         // matches the compiled module. Skin keeps its
         // own id so the pbr-skin fail-fast (null layout) is preserved.
-        materialShaderId === SKIN_MATERIAL_SHADER_ID
-          ? materialShaderId
+        pipelineShaderId === SKIN_MATERIAL_SHADER_ID
+          ? pipelineShaderId
           : 'forgeax::default-standard-pbr',
         // feat-20260611-fox-skinning-vertex-attribute-chain M4 / w16 (D-4):
         // forward meshAttributes through the fallback path so the pbr-skin
@@ -2489,7 +2409,7 @@ async function makeWebGPURenderer(
     if (effectiveVariantSet !== undefined) {
       const registry = getShader();
       for (const msEntry of registry.materialShaderManifestEntries()) {
-        if (msEntry.identifier === materialShaderId) {
+        if (msEntry.identifier === pipelineShaderId) {
           const variant = findVariantByKey(msEntry, effectiveVariantSet);
           if (variant) {
             // M3 / w12-w13: variant substitution carries the same source +
@@ -2516,7 +2436,7 @@ async function makeWebGPURenderer(
     return buildAndCachePipeline(
       cacheKey,
       shaderEntry,
-      `pbr-pipeline-${materialShaderId}${isHdr ? '-hdr' : ''}${passKindLabelSegment}`,
+      `pbr-pipeline-${pipelineShaderId}${isHdr ? '-hdr' : ''}${passKindLabelSegment}`,
       // feat-20260609 M4 / w31: when variantSet is non-empty, the module identity
       // includes the variant key so URP (STORAGE_BUFFER_AVAILABLE=true) and HDRP
       // (CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true) variants
@@ -2530,8 +2450,8 @@ async function makeWebGPURenderer(
       // empty-tail segment); module identity stays a function of the
       // exact variantSet string.
       effectiveVariantSet !== undefined
-        ? `module-${materialShaderId}#${effectiveVariantSet}`
-        : `module-${materialShaderId}`,
+        ? `module-${pipelineShaderId}#${effectiveVariantSet}`
+        : `module-${pipelineShaderId}`,
       isHdr,
       renderState,
       topology,
@@ -2547,7 +2467,7 @@ async function makeWebGPURenderer(
       // bug-20260611-skin-pipeline-layout: thread the registered materialShaderId
       // so buildPipelineContext can resolve LayoutKind='pbr-skin' for the skin
       // shader (2-entry mesh-array BGL).
-      materialShaderId,
+      pipelineShaderId,
       // feat-20260611-fox-skinning-vertex-attribute-chain M4 / w16 (D-4):
       // forward meshAttributes so the pbr-skin path's vertex buffer layout
       // is derived via the SSOT (deriveVertexBufferLayout). For URP/HDRP
@@ -2562,6 +2482,8 @@ async function makeWebGPURenderer(
       shaderModuleMode,
       layoutKindOverride,
       additionalColorFormats,
+      vertexEntry,
+      fragmentEntry,
     );
   };
   const getMaterialShaderPipelineEntry = (
@@ -3009,6 +2931,24 @@ async function makeWebGPURenderer(
         featureDiagnostics: internals.featureHost?.diagnostics() ?? Object.freeze([]),
         frustumStats: Object.freeze({ ...renderSystem.frustumStats }),
         visibilityStats: Object.freeze({ ...renderSystem.visibilityStats }),
+        instanceCollections: Object.freeze(
+          renderSystem.instanceCollectionsInspection.map((collection) =>
+            Object.freeze({
+              ...collection,
+              uploadRanges: Object.freeze(
+                collection.uploadRanges.map((range) => Object.freeze({ ...range })),
+              ),
+              ...(collection.error === undefined
+                ? {}
+                : {
+                    error: Object.freeze({
+                      ...collection.error,
+                      detail: Object.freeze({ ...collection.error.detail }),
+                    }),
+                  }),
+            }),
+          ),
+        ),
         renderScene: renderSystem.renderScene,
         reflectionProbes: renderSystem.reflectionProbes,
         ssrDependencies: renderSystem.ssrDependencies,