@forgeax/engine-render 0.1.32 → 0.1.34

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/motion-blur-registration.ts

@@ -0,0 +1,17 @@
+import { MOTION_BLUR_PARAMS_BYTE_SIZE } from '../features/motion-blur/motion-blur-params';
+import type { PostProcessShaderEntry } from '../fullscreen-post-process-pass';
+import type { RenderSystem } from '../render-system';
+
+export function registerMotionBlurPostProcess(
+  renderSystem: Pick<RenderSystem, 'registerBuiltinPostProcess'>,
+  source: string,
+): void {
+  renderSystem.registerBuiltinPostProcess('forgeax.motion-blur', {
+    source,
+    params: {
+      byteSize: MOTION_BLUR_PARAMS_BYTE_SIZE,
+      defaultValue: new Uint8Array(MOTION_BLUR_PARAMS_BYTE_SIZE),
+    },
+    reads: ['scene-color', 'scene-temporal'],
+  } satisfies PostProcessShaderEntry);
+}

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

@@ -126,6 +126,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 +199,8 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
     getCandidateMaterialShaderUvSetCounts,
     setCandidateMaterialShaderUvSetCounts,
     setCandidateEmptyPostProcessBgl,
+    getShaderModuleAdapter,
+    getImmediateShaderModuleAdapter,
     getShader,
     assets,
     adaptMipmapShaderModuleFactory,
@@ -319,24 +323,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;
@@ -486,6 +474,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 +589,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()]);
+}

package/src/assembly/renderer-facade.ts

@@ -15,6 +15,7 @@ import {
   type RendererOperationCause,
   RendererOperationError,
 } from '../errors/render';
+import { MotionBlurValidationError } from '../features/motion-blur/motion-blur-params';
 import {
   STANDARD_LIGHT_COUNTS,
   STANDARD_PIPELINE_ID,
@@ -63,6 +64,7 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
           cause: structuredRendererCause(cause, 'renderer-event'),
         });
   const drawError = (cause: RhiError | RenderError): RenderError => {
+    if (cause instanceof MotionBlurValidationError) return cause;
     if (cause instanceof RendererOperationError) return cause;
     if (cause instanceof RendererContractFailureError) {
       return new RendererOperationError('device-operation-failed', {
@@ -90,7 +92,7 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
   });
 
   return {
-    instances: renderer.instances,
+    setSurfaceDynamicInput: (frame) => renderer.setSurfaceDynamicInput(frame),
     bounds: (world, entity) => (disposed ? undefined : renderer.bounds(world, entity)),
     attach: (world) => {
       const result = renderer.attach(world);
@@ -153,6 +155,9 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
           kind: 'frame-submitted',
           frameId: result.value.frameId,
           deviceGeneration: result.value.deviceGeneration,
+          ...(result.value.graphGeneration === undefined
+            ? {}
+            : { graphGeneration: result.value.graphGeneration }),
           receipt: result.value,
         }),
       );

package/src/assembly/renderer-feature-inspection.ts

@@ -1,13 +1,19 @@
+import type { CloudLayerInspection } from '../cloud/inspection';
 import type { RenderFeatureHost } from '../features/host';
 import type { RenderInspection } from '../render-contract';
 
 /** Project feature-host lifecycle facts without exposing the live host. */
 export function projectRendererFeatureInspection(
   featureHost: RenderFeatureHost | undefined,
-): Pick<RenderInspection, 'features' | 'featureDiagnostics' | 'featureHost'> {
+): Pick<RenderInspection, 'features' | 'featureDiagnostics' | 'featureHost' | 'cloudLayer'> {
+  const featureDiagnostics = featureHost?.diagnostics() ?? Object.freeze([]);
+  const cloudLayer = featureDiagnostics.find(
+    (diagnostic) => diagnostic.identity === 'forgeax.cloud-layer',
+  )?.inspection as CloudLayerInspection | undefined;
   return {
     features: Object.freeze((featureHost?.features ?? []).map((feature) => feature.identity)),
-    featureDiagnostics: featureHost?.diagnostics() ?? Object.freeze([]),
+    featureDiagnostics,
+    ...(cloudLayer === undefined ? {} : { cloudLayer }),
     ...(featureHost?.inspection === undefined ? {} : { featureHost: featureHost.inspection() }),
   };
 }

package/src/assembly/renderer-frame-transaction.ts

@@ -64,6 +64,29 @@ export interface ContinuationTerminator {
   guard(kind: ContinuationKind): boolean;
 }
 
+export type FrameCompletionResult<T, E> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };
+
+/**
+ * Preserve producer Result failures while fencing a fulfilled GPU completion
+ * against disposal or device-generation loss.
+ */
+export function guardFrameCompletion<T, E>(
+  completion: PromiseLike<FrameCompletionResult<T, E>>,
+  isCurrent: () => boolean,
+  staleError: () => E,
+  rejectedError: (cause: unknown) => E,
+): Promise<FrameCompletionResult<T, E>> {
+  return Promise.resolve(completion).then(
+    (result) => {
+      if (!result.ok) return result;
+      return isCurrent() ? result : { ok: false, error: staleError() };
+    },
+    (cause) => ({ ok: false, error: rejectedError(cause) }),
+  );
+}
+
 export function createContinuationTerminator(): ContinuationTerminator {
   let termination: ContinuationTerminationReason | undefined;
   let resolveTermination: ((reason: ContinuationTerminationReason) => void) | undefined;

package/src/assembly/renderer-inspection.ts

@@ -2,6 +2,7 @@ import type { CompiledRenderGraphInfo } from '@forgeax/engine-render-graph';
 import type { RhiCanvasSurfacePresentationProof, TextureFormat } from '@forgeax/engine-rhi';
 import type { AutoExposureInspection } from '../pipeline/standard-output/auto-exposure/inspection';
 import type { StandardLutInspection } from '../pipeline/standard-output/lut-state';
+import type { PipelineState } from '../record/render-context';
 import {
   type RenderOutputInspection,
   type RenderStandardOutputColorInspection,
@@ -112,6 +113,33 @@ export function projectRendererOutputInspection(
   };
 }
 
+/** Assemble output inspection inputs from the live surface owner. */
+export function projectRendererOutputInspectionFromSurface(input: {
+  readonly graph: CompiledRenderGraphInfo | undefined;
+  readonly surfaceReleased: boolean;
+  readonly pipelineState: PipelineState | null;
+  readonly rgba16floatRenderable: boolean;
+  readonly presentationProof?: RhiCanvasSurfacePresentationProof | undefined;
+  readonly autoExposure?: AutoExposureInspection | undefined;
+  readonly standardLut?: StandardLutInspection | undefined;
+}): RenderOutputInspection {
+  return projectRendererOutputInspection({
+    graph: input.graph,
+    surfaceAvailable: !input.surfaceReleased && input.pipelineState !== null,
+    surfaceStorage: input.pipelineState?.format ?? 'rgba8unorm',
+    surfaceDisplay: input.pipelineState?.colorAttachmentFormat ?? 'rgba8unorm',
+    ...(input.pipelineState?.surfaceProfile === undefined
+      ? {}
+      : { surfaceProfile: input.pipelineState.surfaceProfile }),
+    rgba16floatRenderable: input.rgba16floatRenderable,
+    autoExposure: input.autoExposure,
+    standardLut: input.standardLut,
+    ...(input.presentationProof === undefined
+      ? {}
+      : { presentationProof: input.presentationProof }),
+  });
+}
+
 /** Detached inspection projection helper; live renderer objects never cross this boundary. */
 export function detachRendererInspection<T extends object>(inspection: T): Readonly<T> {
   return Object.freeze({ ...inspection });

package/src/assembly/skin-palette-owner.ts

@@ -15,7 +15,7 @@ export function createSkinPaletteOwner(
   const limitKey = storageBufferCapable
     ? 'maxStorageBufferBindingSize'
     : 'maxUniformBufferBindingSize';
-  const deviceLimit = (device.limits as Readonly<Record<string, number>>)[limitKey];
+  const deviceLimit = device.limits[limitKey];
   const maxBindingBytes = typeof deviceLimit === 'number' && deviceLimit > 0 ? deviceLimit : 65536;
   return createSkinPaletteAllocator(device, maxBindingBytes, storageBufferCapable);
 }

package/src/assembly/temporal-post-process-prewarm.ts

@@ -0,0 +1,40 @@
+import type { Result, RhiDevice, RhiError, ShaderModule } from '@forgeax/engine-rhi';
+import type { ManifestEntry } from '@forgeax/engine-types';
+import { postProcessShaderModuleLabel } from '../fullscreen-post-process-pass';
+import { invokeDeviceCreateShaderModule } from './material-shader-policy';
+import { runShimStep } from './renderer-helpers';
+
+export type AsyncShaderModuleFactory =
+  | ((
+      device: RhiDevice,
+      desc: { readonly code: string; readonly label?: string },
+    ) => Promise<Result<ShaderModule, RhiError>>)
+  | undefined;
+
+/** Create the shared readiness prewarmer for temporal/fullscreen shader entries. */
+export function createTemporalShaderPrewarmer(input: {
+  readonly device: RhiDevice;
+  readonly asyncCreateShaderModule: AsyncShaderModuleFactory;
+  readonly seedShaderModule: (label: string, module: ShaderModule) => void;
+}): (entry: ManifestEntry | undefined, id: string) => Promise<void> {
+  return async (entry, id): Promise<void> => {
+    if (entry === undefined) return;
+    const prewarm = await runShimStep(
+      () =>
+        input.asyncCreateShaderModule
+          ? input.asyncCreateShaderModule(input.device, {
+              code: entry.wgsl,
+              label: postProcessShaderModuleLabel(entry.wgsl),
+            })
+          : invokeDeviceCreateShaderModule(input.device, {
+              code: entry.wgsl,
+              label: postProcessShaderModuleLabel(entry.wgsl),
+            }),
+      'shader-compile-failed',
+      `${id} shader module compiled (unified post-process prewarm)`,
+      `inspect manifest ${id} entry composed wgsl; check device.features`,
+    );
+    if (!prewarm.ok) throw prewarm.error;
+    input.seedShaderModule(postProcessShaderModuleLabel(entry.wgsl), prewarm.value);
+  };
+}