@forgeax/engine-render 0.1.33 → 0.1.35

package/src/assembly/host-contract.ts

@@ -13,8 +13,8 @@ import type { RecoverFailure } from '../errors/recover';
 import type { ObservationUnavailableError, RenderError } from '../errors/render';
 import type { RenderFeature, RenderFeatureDiagnostics } from '../features/types';
 import type { GpuDrivenProductionInspection, LodOcclusionInspection } from '../inspection-types';
-import type { InstanceCollectionStore } from '../instances';
 import type { MeshMaterialBindingObservation } from '../mesh-material-bindings';
+import type { PublishedRenderFrameInput } from '../publication/contract';
 import type { FrameObservation, FrameObservationOptions } from '../record/frame';
 import type { CurrentGraphTarget, GraphTargetCaptureRequest } from '../record/frame-snapshot';
 import type {
@@ -35,6 +35,7 @@ import type {
 } from '../render-contract';
 import type { RenderSceneInspection } from '../render-system';
 import type { RenderSceneBounds } from '../scene/render-scene-types';
+import type { SurfaceDynamicInputFrame } from '../surface/dynamic-input';
 import type {
   RenderTarget,
   RenderTargetDescriptor,
@@ -62,8 +63,8 @@ export type RendererHostEventListener = (event: RendererHostEvent) => void;
  * the public Renderer type.
  */
 export interface RendererHostImplementation {
-  /** Renderer-owned authoring and update path for large instance collections. */
-  readonly instances: InstanceCollectionStore;
+  /** Publish one renderer-owned read-only Surface dynamic page for the next frame. */
+  setSurfaceDynamicInput(frame: SurfaceDynamicInputFrame | undefined): void;
   attach(world: World): RenderResult<RenderWorldLease, RenderError>;
   prepareDynamicGeometry(
     input: DynamicGeometryPrepareInput,
@@ -120,7 +121,9 @@ export interface RendererHostImplementation {
     readonly lodOcclusion: LodOcclusionInspection | undefined;
     readonly gpuDriven: GpuDrivenProductionInspection;
   };
-  drawFrame(request: RenderFrameInput): RenderResult<FrameReceipt, RhiError | RenderError>;
+  drawFrame(
+    request: RenderFrameInput | PublishedRenderFrameInput,
+  ): RenderResult<FrameReceipt, RhiError | RenderError>;
   /** Arm one upcoming frame for receipt-bound color observations. */
   requestObservation?: (
     domains: readonly import('../render-contract').FrameObservationDomain[],
@@ -154,7 +157,7 @@ export interface RendererLegacyHostAdapter {
   attachScene(world: World): RenderResult<void, RhiError>;
   detachScene(world: World): void;
   draw(
-    worldsOrRequest: readonly World[] | RenderFrameInput,
+    worldsOrRequest: readonly World[] | RenderFrameInput | PublishedRenderFrameInput,
     options?: DrawOwnerOptions,
   ): RenderResult<void | FrameReceipt, RhiError | RenderError>;
   observeCurrentFrame(

package/src/assembly/material/assembly.ts

@@ -245,7 +245,17 @@ function selectPublishedVariant(
     withColor = withColor.filter((variant) => variant.defines.COVERAGE_ONLY !== true);
   }
   if (options.variantSet !== undefined) {
-    return withColor.find((variant) => variant.definesKey === options.variantSet);
+    const requestedAxes = new Map(
+      options.variantSet.length === 0
+        ? []
+        : options.variantSet.split('+').map((entry) => {
+            const [name, value] = entry.split('=');
+            return [name ?? '', value === 'true'] as const;
+          }),
+    );
+    withColor = withColor.filter((variant) =>
+      [...requestedAxes].every(([name, value]) => variant.defines[name] === value),
+    );
   }
   // 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
@@ -296,12 +306,13 @@ export function resolveStandardPbrArtifact(
   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 manifestEntry: MaterialShaderManifestEntry | undefined;
+    for (const entry of shader.materialShaderManifestEntries?.() ?? []) {
+      if (entry.identifier === lookupId) {
+        manifestEntry = entry;
+        break;
+      }
+    }
     const selected =
       manifestEntry === undefined || manifestEntry.variants.length === 0
         ? undefined
@@ -356,12 +367,13 @@ export function resolveMaterialShaderArtifact(
   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 manifestEntry: MaterialShaderManifestEntry | undefined;
+    for (const entry of shader.materialShaderManifestEntries?.() ?? []) {
+      if (entry.identifier === lookupId) {
+        manifestEntry = entry;
+        break;
+      }
+    }
     let cache = publishedArtifacts.get(lookup.value);
     if (cache === undefined || cache.manifest !== manifestEntry) {
       cache = { manifest: manifestEntry, requests: new Map() };

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

@@ -1,6 +1,7 @@
 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 PipelineGroup2Contract, resolvePipelineGroup2Contract } from '../../pbr-pipeline';
 import type { LayoutKind } from '../material-shader-policy';
 import { type MaterialShaderArtifactRequest, resolveMaterialShaderArtifact } from './assembly';
 
@@ -42,7 +43,11 @@ export function resolveMaterialPipelineVertexEntry(
   vertexEntryPoint: string | undefined,
   authoredVertexEntry: string | undefined,
 ): string | undefined {
-  const sceneIndex = layoutKind === 'gpu-driven-pbr' || layoutKind === 'gpu-driven-skin';
+  const sceneIndex =
+    layoutKind === 'gpu-driven-pbr' ||
+    layoutKind === 'gpu-driven-skin' ||
+    layoutKind === 'gpu-driven-cluster-pbr' ||
+    layoutKind === 'gpu-driven-cluster-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.
@@ -51,6 +56,33 @@ export function resolveMaterialPipelineVertexEntry(
     : (authoredVertexEntry ?? vertexEntryPoint);
 }
 
+/** Keep the recorded group(2) receipt identical to the selected pipeline layout. */
+export function resolveMaterialPipelineGroup2Contract(
+  source: string,
+  layoutKind: LayoutKind | undefined,
+): PipelineGroup2Contract {
+  switch (layoutKind) {
+    case 'hdrp-pbr':
+    case 'gpu-driven-cluster-pbr':
+    case 'surface-direct-cluster-pbr':
+      return 'cluster';
+    case 'hdrp-skin':
+    case 'gpu-driven-cluster-skin':
+      return 'skin-cluster';
+    case 'pbr-skin':
+    case 'gpu-driven-skin':
+      return 'skin';
+    case 'pbr':
+    case 'gpu-driven-pbr':
+    case 'surface-direct-pbr':
+    case 'sprite-urp':
+    case 'unlit-urp':
+      return 'mesh';
+    case undefined:
+      return resolvePipelineGroup2Contract(source);
+  }
+}
+
 export interface MaterialPipelineBindGroupState {
   readonly meshBindGroupLayout: BindGroupLayout;
   readonly pbrSkinMeshBindGroupLayout: BindGroupLayout | null;
@@ -58,6 +90,8 @@ export interface MaterialPipelineBindGroupState {
   readonly hdrpMeshBindGroupLayout?: BindGroupLayout | null;
   readonly instancesBindGroupLayout: BindGroupLayout;
   readonly gpuDrivenInstancesBindGroupLayout?: BindGroupLayout | null;
+  readonly surfaceDirectInstancesBindGroupLayout?: BindGroupLayout | null;
+  readonly gpuDrivenClusterMeshBindGroupLayout?: BindGroupLayout | null;
 }
 
 export function resolveMaterialPipelineBindGroups(
@@ -66,20 +100,27 @@ export function resolveMaterialPipelineBindGroups(
   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'
+    layoutKind === 'gpu-driven-cluster-pbr' || layoutKind === 'surface-direct-cluster-pbr'
+      ? state.gpuDrivenClusterMeshBindGroupLayout
+      : clustered && layoutKind === 'gpu-driven-pbr'
+        ? state.hdrpMeshBindGroupLayout
+        : clustered && layoutKind === 'gpu-driven-skin'
+          ? state.hdrpSkinMeshBindGroupLayout
+          : layoutKind === 'gpu-driven-cluster-skin' || layoutKind === 'hdrp-skin'
             ? state.hdrpSkinMeshBindGroupLayout
-            : state.meshBindGroupLayout;
+            : layoutKind === 'pbr-skin' || layoutKind === 'gpu-driven-skin'
+              ? state.pbrSkinMeshBindGroupLayout
+              : state.meshBindGroupLayout;
   if (meshLayout == null) return null;
   const instancesLayout =
-    layoutKind === 'gpu-driven-pbr' || layoutKind === 'gpu-driven-skin'
-      ? state.gpuDrivenInstancesBindGroupLayout
-      : state.instancesBindGroupLayout;
+    layoutKind === 'surface-direct-pbr' || layoutKind === 'surface-direct-cluster-pbr'
+      ? state.surfaceDirectInstancesBindGroupLayout
+      : layoutKind === 'gpu-driven-pbr' ||
+          layoutKind === 'gpu-driven-skin' ||
+          layoutKind === 'gpu-driven-cluster-pbr' ||
+          layoutKind === 'gpu-driven-cluster-skin'
+        ? state.gpuDrivenInstancesBindGroupLayout
+        : state.instancesBindGroupLayout;
   return instancesLayout === null || instancesLayout === undefined
     ? null
     : { meshLayout, instancesLayout };

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

@@ -9,6 +9,7 @@ import { err, ok, RhiError } from '@forgeax/engine-rhi';
 import {
   DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
   findVariantByKey,
+  type MaterialShaderEntry,
   type MaterialShaderManifestEntry,
   type ShaderCatalog,
   type ShaderCatalogDevice,
@@ -543,6 +544,10 @@ export type LayoutKind =
   | 'pbr-skin'
   | 'gpu-driven-pbr'
   | 'gpu-driven-skin'
+  | 'gpu-driven-cluster-pbr'
+  | 'gpu-driven-cluster-skin'
+  | 'surface-direct-pbr'
+  | 'surface-direct-cluster-pbr'
   | 'hdrp-pbr'
   | 'hdrp-skin'
   | 'sprite-urp'
@@ -781,6 +786,48 @@ export function resolveMaterialShaderBackendArtifactKey(
   return fallback?.specializationKey ?? materialShaderId;
 }
 
+/**
+ * Remove the optional cloud-shadow sampler pair from a cooked material when
+ * the active device has no spare sampled-texture lanes. Pack-cooked material
+ * programs are immutable artifacts and therefore do not carry the engine
+ * manifest's capability Cartesian product. The low-limit renderer contract is
+ * still explicit: direct solar remains fully lit, while the view BGL stays at
+ * its 16-texture limit. Only the cloud sampler declarations and their sample
+ * are rewritten; the material's surface, parameters, and lighting remain
+ * unchanged.
+ */
+export function stripCloudShadowBindingsForLowLimit(source: string): string {
+  const textureDeclaration =
+    /@group\s*\(\s*0\s*\)\s*@binding\s*\(\s*16\s*\)\s*var\s+(\w+)\s*:\s*texture_2d<f32>\s*;\s*/u;
+  const samplerDeclaration =
+    /@group\s*\(\s*0\s*\)\s*@binding\s*\(\s*17\s*\)\s*var\s+(\w+)\s*:\s*sampler\s*;\s*/u;
+  const textureMatch = textureDeclaration.exec(source);
+  const samplerMatch = samplerDeclaration.exec(source);
+  if (textureMatch === null || samplerMatch === null) return source;
+  const textureName = textureMatch[1];
+  const samplerName = samplerMatch[1];
+  if (textureName === undefined || samplerName === undefined) return source;
+
+  let rewritten = source.replace(textureDeclaration, '').replace(samplerDeclaration, '');
+  const escapedTexture = textureName.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+  const escapedSampler = samplerName.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+  const cloudSample = new RegExp(
+    `textureSampleLevel\\(\\s*${escapedTexture}\\s*,\\s*${escapedSampler}\\s*,[^;\\n]*\\)`,
+    'gu',
+  );
+  rewritten = rewritten.replace(cloudSample, 'vec4<f32>(1.0)');
+  return rewritten;
+}
+
+export function prepareLowLimitMaterialShaderEntry<T extends MaterialShaderEntry>(
+  entry: T,
+  sampledTextureLimit: number | undefined,
+): T {
+  if ((sampledTextureLimit ?? 0) >= STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES) return entry;
+  const source = stripCloudShadowBindingsForLowLimit(entry.source);
+  return source === entry.source ? entry : ({ ...entry, source } as T);
+}
+
 export function allowsUnlitPreparedFallback(
   depthFormatOverride: GPUTextureFormat | null | undefined,
   vertexLayout: string | undefined,
@@ -822,6 +869,8 @@ export function selectPipelineLayoutForVariant(
     readonly pbrSkinProbePipelineLayout?: PipelineLayout | null;
     readonly gpuDrivenPbrPipelineLayout?: PipelineLayout | null;
     readonly gpuDrivenPbrSkinPipelineLayout?: PipelineLayout | null;
+    readonly gpuDrivenClusterPbrPipelineLayout?: PipelineLayout | null;
+    readonly gpuDrivenClusterPbrSkinPipelineLayout?: PipelineLayout | null;
     readonly hdrpSkinPipelineLayout?: PipelineLayout | null;
   } | null,
   variantSet: string | undefined,
@@ -835,6 +884,12 @@ export function selectPipelineLayoutForVariant(
   if (layoutKind === 'gpu-driven-skin') {
     return state.gpuDrivenPbrSkinPipelineLayout ?? null;
   }
+  if (layoutKind === 'gpu-driven-cluster-pbr') {
+    return state.gpuDrivenClusterPbrPipelineLayout ?? null;
+  }
+  if (layoutKind === 'gpu-driven-cluster-skin') {
+    return state.gpuDrivenClusterPbrSkinPipelineLayout ?? null;
+  }
   // bug-20260611: skin layout selection takes precedence over HDRP variant
   // resolution. HDRP × skin is OOS-1 (plan-strategy R-2 — left for a
   // dedicated feat); when an HDRP-variant skin call ever lands, we fail

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

@@ -2,7 +2,10 @@ import type { Result, RhiDevice, ShaderModule } from '@forgeax/engine-rhi';
 import { RhiError } from '@forgeax/engine-rhi';
 import type { ShaderCatalog } from '@forgeax/engine-shader';
 
-import { invokeDeviceCreateShaderModule } from './material-shader-policy';
+import {
+  invokeDeviceCreateShaderModule,
+  prepareLowLimitMaterialShaderEntry,
+} from './material-shader-policy';
 import { runShimStep } from './renderer-helpers';
 
 type AsyncCreateShaderModule = (
@@ -37,12 +40,18 @@ export async function prewarmRequiredMaterialShaders({
         hint: `add material shader '${materialShaderId}' to the shader manifest or remove it from the feature declaration`,
       });
     }
+    // Prewarm and lazy pipelines share a module label, so they must compile
+    // the same capability-adjusted source on the replacement device.
+    const entry = prepareLowLimitMaterialShaderEntry(
+      lookup.value,
+      rhiDevice.limits.maxSampledTexturesPerShaderStage,
+    );
     const label = `module-${materialShaderId}`;
     const shaderResult = await runShimStep(
       () =>
         asyncCreateShaderModule
-          ? asyncCreateShaderModule(rhiDevice, { code: lookup.value.source, label })
-          : invokeDeviceCreateShaderModule(rhiDevice, { code: lookup.value.source, label }),
+          ? asyncCreateShaderModule(rhiDevice, { code: entry.source, label })
+          : invokeDeviceCreateShaderModule(rhiDevice, { code: entry.source, label }),
       'shader-compile-failed',
       `declared render feature material shader '${materialShaderId}' compiled`,
       `inspect the composed WGSL for '${materialShaderId}' and check device.features`,
@@ -50,28 +59,30 @@ export async function prewarmRequiredMaterialShaders({
     if (!shaderResult.ok) throw shaderResult.error;
     seedShaderModule(label, shaderResult.value);
 
-    const prewarmedSources = new Map<string, ShaderModule>([
-      [lookup.value.source, shaderResult.value],
-    ]);
+    const prewarmedSources = new Map<string, ShaderModule>([[entry.source, shaderResult.value]]);
     const manifestEntry = [...registry.materialShaderManifestEntries()].find(
       (candidate) => candidate.identifier === materialShaderId,
     );
     if (manifestEntry === undefined) continue;
 
     for (const variant of manifestEntry.variants) {
+      const variantSource = prepareLowLimitMaterialShaderEntry(
+        { ...entry, source: variant.composedWgsl },
+        rhiDevice.limits.maxSampledTexturesPerShaderStage,
+      ).source;
       const variantLabel = `module-${materialShaderId}#${variant.definesKey}`;
       if (variantLabel === label) continue;
-      let variantModule = prewarmedSources.get(variant.composedWgsl);
+      let variantModule = prewarmedSources.get(variantSource);
       if (variantModule === undefined) {
         const variantResult = await runShimStep(
           () =>
             asyncCreateShaderModule
               ? asyncCreateShaderModule(rhiDevice, {
-                  code: variant.composedWgsl,
+                  code: variantSource,
                   label: variantLabel,
                 })
               : invokeDeviceCreateShaderModule(rhiDevice, {
-                  code: variant.composedWgsl,
+                  code: variantSource,
                   label: variantLabel,
                 }),
           'shader-compile-failed',
@@ -80,7 +91,7 @@ export async function prewarmRequiredMaterialShaders({
         );
         if (!variantResult.ok) throw variantResult.error;
         variantModule = variantResult.value;
-        prewarmedSources.set(variant.composedWgsl, variantModule);
+        prewarmedSources.set(variantSource, variantModule);
       }
       seedShaderModule(variantLabel, variantModule);
     }

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

@@ -30,6 +30,19 @@ export function attachDeviceLostFanout(
     onStaleLoss,
     onDeviceLost,
   } = registries;
+  if (pack._internal_getRawDevice && pack.translateErrorEventToRhiError) {
+    const backendDevice = pack._internal_getRawDevice(device);
+    if (backendDevice && typeof backendDevice === 'object') {
+      const target = backendDevice as {
+        onuncapturederror?: ((event: unknown) => void) | null;
+      };
+      target.onuncapturederror = (event: unknown): void => {
+        if (generation !== currentGeneration()) return;
+        const translated = pack.translateErrorEventToRhiError?.(event);
+        if (translated && !translated.ok) errorRegistry.fire(translated.error);
+      };
+    }
+  }
   const dispatch = (safe: {
     readonly reason: 'destroyed' | 'unknown';
     readonly message: string;

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

@@ -10,6 +10,7 @@ import type {
 import { err, ok, type Result, RhiError } from '@forgeax/engine-rhi';
 import type { MaterialShaderManifestEntry, ShaderCatalog } from '@forgeax/engine-shader';
 import type { Handle, ParamSchemaEntry } from '@forgeax/engine-types';
+import { AssetError } from '@forgeax/engine-types';
 import { DeviceScope } from '../../device/device-scope';
 import { GpuResidencyCache } from '../../device/gpu-residency';
 import { RecoverError, type RecoverFailure } from '../../errors/recover';
@@ -126,6 +127,8 @@ export interface RendererRecoveryDependencies {
   readonly getCandidateMaterialShaderUvSetCounts: () => Map<string, number> | undefined;
   readonly setCandidateMaterialShaderUvSetCounts: (state: Map<string, number> | undefined) => void;
   readonly setCandidateEmptyPostProcessBgl: (layout: BindGroupLayout | null | undefined) => void;
+  readonly getShaderModuleAdapter: () => ShaderDeviceAdapterInternal;
+  readonly getImmediateShaderModuleAdapter: () => ShaderDeviceAdapterInternal;
   readonly getShader: () => ShaderCatalog;
   readonly assets: AssetRegistry;
   readonly adaptMipmapShaderModuleFactory: (
@@ -197,6 +200,8 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
     getCandidateMaterialShaderUvSetCounts,
     setCandidateMaterialShaderUvSetCounts,
     setCandidateEmptyPostProcessBgl,
+    getShaderModuleAdapter,
+    getImmediateShaderModuleAdapter,
     getShader,
     assets,
     adaptMipmapShaderModuleFactory,
@@ -319,24 +324,8 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
     setCandidatePipelineCacheState(candidateState.pipelineCacheState);
     setCandidateMaterialShaderUvSetCounts(candidateState.materialShaderUvSetCounts);
     setCandidateEmptyPostProcessBgl(candidateState.emptyPostProcessBgl);
-    // Copy only the active catalog's CPU declarations into the candidate.
-    // Its manifest/module cache remains candidate-owned, so no lost-device
-    // ShaderModule can cross the recovery boundary while late-installed
-    // material shaders remain available to the normal builder.
-    const activeShaderCatalog = getActiveShaderState().shaderInstance;
-    if (activeShaderCatalog !== null) {
-      const candidateShaderCatalog = getShader();
-      for (const identifier of activeShaderCatalog.materialShaderIdentifiers()) {
-        const entry = activeShaderCatalog.findMaterialArtifact(identifier);
-        if (entry.ok && !candidateShaderCatalog.findMaterialArtifact(identifier).ok) {
-          candidateShaderCatalog.installMaterialArtifact(identifier, {
-            source: entry.value.source,
-            paramSchema: entry.value.paramSchema,
-            ...(entry.value.receipt === undefined ? {} : { receipt: entry.value.receipt }),
-          });
-        }
-      }
-    }
+    // getShader forks the admitted CPU catalog into the candidate on first
+    // access. Shader modules and all device-bound caches start empty.
     let candidatePostProcessResources: RecoveryPostProcessResources | undefined;
     let recoveryGraphCandidate: RecoveryGraphCandidate | undefined;
     let recoveryRootBundle: RecoveryRootBundle | undefined;
@@ -411,6 +400,14 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
       device,
       adaptMipmapShaderModuleFactory(internals.pack.createShaderModule),
       (world, pod) => {
+        if ('resolveAsset' in world)
+          return err(
+            new AssetError({
+              code: 'asset-not-found',
+              expected: 'source-owned environment asset allocation',
+              hint: 'publish the environment asset from its source owner before GPU preparation',
+            }),
+          );
         const handle: Handle<'EquirectAsset', 'shared'> = world.allocSharedRef(
           'EquirectAsset',
           pod,
@@ -486,6 +483,27 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
       if (preparation.kind === 'error') throw preparation.error;
       const abortedAfterShaders = abortDisposedRecovery('rehydrate');
       if (abortedAfterShaders !== undefined) return abortedAfterShaders;
+      // Rehydrate manifest-selected builtins before carrying over late-
+      // installed user declarations. Builtin material sources are capability
+      // variants: copying the active generation first can retain a shader that
+      // declares cloud bindings 16/17 while the replacement device only
+      // admits the low-limit view layout. The candidate catalog owns fresh CPU
+      // declarations and modules; only identifiers still absent after
+      // preparation cross the generation boundary.
+      const activeShaderCatalog = getActiveShaderState().shaderInstance;
+      if (activeShaderCatalog !== null) {
+        const candidateShaderCatalog = getShader();
+        for (const identifier of activeShaderCatalog.materialShaderIdentifiers()) {
+          const entry = activeShaderCatalog.findMaterialArtifact(identifier);
+          if (entry.ok && !candidateShaderCatalog.findMaterialArtifact(identifier).ok) {
+            candidateShaderCatalog.installMaterialArtifact(identifier, {
+              source: entry.value.source,
+              paramSchema: entry.value.paramSchema,
+              ...(entry.value.receipt === undefined ? {} : { receipt: entry.value.receipt }),
+            });
+          }
+        }
+      }
       setRecoveryPhase('compile-graph');
       const pipeline = await runRecoveryStep(
         async (attemptToken) => {
@@ -580,6 +598,20 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
       getParamSchema: { value: getParamSchema },
       getMaterialBindGroupLayout: { value: getMaterialBindGroupLayout },
       metrics: { value: metrics },
+      shaderModuleFactory: {
+        value: {
+          createShaderModule: (
+            descriptor: Parameters<ShaderDeviceAdapterInternal['createShaderModule']>[0],
+          ) => getShaderModuleAdapter().createShaderModule(descriptor),
+        },
+      },
+      immediateShaderModuleFactory: {
+        value: {
+          createShaderModule: (
+            descriptor: Parameters<ShaderDeviceAdapterInternal['createShaderModule']>[0],
+          ) => getImmediateShaderModuleAdapter().createShaderModule(descriptor),
+        },
+      },
       buildPostProcessPipeline: { value: buildPostProcessPipeline },
       getPipelineState: { value: () => candidatePipelineState },
       featureHost: { value: createdCandidateFeatureHost },

package/src/assembly/render-feature-post-processes.ts

@@ -0,0 +1,54 @@
+import { RhiError } from '@forgeax/engine-rhi';
+import {
+  SINGLE_LAYER_MEDIUM_MSAA_PAIRED_COLOR_WGSL,
+  SINGLE_LAYER_MEDIUM_MSAA_RAW_DEPTH_WGSL,
+  SINGLE_LAYER_MEDIUM_RAW_DEPTH_WGSL,
+} from '@forgeax/engine-shader';
+import type { RenderFeature } from '../features/types';
+import {
+  SINGLE_LAYER_MEDIUM_MSAA_PAIRED_COLOR_POST_PROCESS_ID,
+  SINGLE_LAYER_MEDIUM_MSAA_RAW_DEPTH_POST_PROCESS_ID,
+  SINGLE_LAYER_MEDIUM_RAW_DEPTH_POST_PROCESS_ID,
+} from '../pipeline/single-layer-medium-passes';
+
+export function collectRequiredFullscreenPostProcesses(
+  features: readonly RenderFeature<unknown>[],
+): readonly { readonly identity: string; readonly source: string }[] {
+  const entries = new Map<string, { readonly identity: string; readonly source: string }>([
+    [
+      SINGLE_LAYER_MEDIUM_RAW_DEPTH_POST_PROCESS_ID,
+      {
+        identity: SINGLE_LAYER_MEDIUM_RAW_DEPTH_POST_PROCESS_ID,
+        source: SINGLE_LAYER_MEDIUM_RAW_DEPTH_WGSL,
+      },
+    ],
+    [
+      SINGLE_LAYER_MEDIUM_MSAA_PAIRED_COLOR_POST_PROCESS_ID,
+      {
+        identity: SINGLE_LAYER_MEDIUM_MSAA_PAIRED_COLOR_POST_PROCESS_ID,
+        source: SINGLE_LAYER_MEDIUM_MSAA_PAIRED_COLOR_WGSL,
+      },
+    ],
+    [
+      SINGLE_LAYER_MEDIUM_MSAA_RAW_DEPTH_POST_PROCESS_ID,
+      {
+        identity: SINGLE_LAYER_MEDIUM_MSAA_RAW_DEPTH_POST_PROCESS_ID,
+        source: SINGLE_LAYER_MEDIUM_MSAA_RAW_DEPTH_WGSL,
+      },
+    ],
+  ]);
+  for (const feature of features) {
+    for (const entry of feature.requiredFullscreenPostProcesses ?? []) {
+      const existing = entries.get(entry.identity);
+      if (existing !== undefined && existing.source !== entry.source) {
+        throw new RhiError({
+          code: 'internal-error',
+          expected: `fullscreen identity '${entry.identity}' has one source across render features`,
+          hint: 'rename the conflicting fullscreen identity or make its WGSL source identical',
+        });
+      }
+      entries.set(entry.identity, entry);
+    }
+  }
+  return Object.freeze([...entries.values()]);
+}