@forgeax/engine-render 0.1.27 → 0.1.29

package/src/assembly/dynamic-geometry-runtime.ts

@@ -0,0 +1,71 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { GpuResidencyCache } from '../device/gpu-residency';
+import {
+  createDynamicGeometryLifecycle,
+  type DynamicGeometryCandidate,
+  type DynamicGeometryLifecycle,
+} from '../dynamic-geometry';
+import { RendererContractFailureError, RendererOperationError } from '../errors/render';
+import type { RenderSystem } from '../render-system';
+import {
+  createDynamicGeometryHost,
+  type DynamicGeometryHostImplementation,
+} from './dynamic-geometry-host';
+
+export interface DynamicGeometryRuntime {
+  readonly lifecycle: DynamicGeometryLifecycle;
+  readonly host: DynamicGeometryHostImplementation;
+}
+
+/** Assemble the renderer-owned candidate lifecycle and its device host. */
+export function createDynamicGeometryRuntime(options: {
+  readonly attachedWorlds: ReadonlySet<World>;
+  readonly getGpuStore: () => GpuResidencyCache;
+  readonly currentGeneration: () => number;
+  readonly renderSystem: Pick<
+    RenderSystem,
+    'invalidateGeometryHistory' | 'isDynamicGeometryConsumed'
+  >;
+}): DynamicGeometryRuntime {
+  const lifecycle = createDynamicGeometryLifecycle();
+  const host = createDynamicGeometryHost({
+    lifecycle,
+    attachedWorlds: options.attachedWorlds,
+    getGpuStore: options.getGpuStore,
+    currentGeneration: options.currentGeneration,
+    onTopologyChanged: () => options.renderSystem.invalidateGeometryHistory(),
+    isConsumedByRenderFrame: (candidate: DynamicGeometryCandidate) =>
+      options.renderSystem.isDynamicGeometryConsumed(
+        candidate.world as World,
+        candidate.entity ?? -1,
+        candidate.meshHandle,
+      ),
+  });
+  return { lifecycle, host };
+}
+
+/** Reject a draw while a derived-physics publication is still unsettled. */
+export function validateDerivedPhysicsFrame(
+  worlds: readonly World[],
+): RendererOperationError<'frame-input-invalid'> | undefined {
+  for (const world of worlds) {
+    if (!world.hasResource('PhysicsWorld')) continue;
+    const physics = world.getResource<{
+      readonly getDerivedAdmission?: () => unknown;
+      readonly getDerivedRecoveryState?: () => string;
+    }>('PhysicsWorld');
+    if (
+      physics?.getDerivedAdmission?.() !== undefined ||
+      physics?.getDerivedRecoveryState?.() === 'rebuild-required'
+    ) {
+      return new RendererOperationError('frame-input-invalid', {
+        operation: 'draw',
+        cause: new RendererContractFailureError(
+          'draw',
+          'paired geometry admission must finish physics step and writeback in a healthy World before draw',
+        ),
+      });
+    }
+  }
+  return undefined;
+}

package/src/assembly/factory.ts

@@ -9,6 +9,9 @@ import type { RendererAssemblyImplementation } from './host-contract';
 import { toError } from './renderer-facade';
 import { tryCreateWebGPURenderer } from './webgpu-renderer';
 
+export { disposeObservationCaptureSet } from './webgpu-renderer';
+export { particleMaterialInputVertexBuffers } from './webgpu-vertex-layouts';
+
 /*
  * Renderer ownership stays explicit even though the implementation is split:
  * the delegated target owner comes from './render-target-host'. The concrete
@@ -69,6 +72,7 @@ export {
   resolveMaterialShaderUvSetCount,
   resolveMaterialShaderVariantSet,
   resolveMaterialShaderVertexInputContract,
+  selectGpuDrivenSceneIndexVariant,
   selectHdrpPbrPrewarmVariants,
   selectNoColorPbrVariant,
   selectPipelineLayoutForVariant,

package/src/assembly/gpu-driven-owner.ts

@@ -0,0 +1,29 @@
+import { err, type RhiDevice, RhiError } from '@forgeax/engine-rhi';
+import { GpuDrivenProduction } from '../gpu-driven/production-raster';
+import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
+
+/**
+ * Renderer-owned GPU-driven frame state boundary. The production object owns
+ * view resources and prepared generations; callers only supply the backend
+ * and shader factory and must not create a parallel frame loop.
+ */
+export function createGpuDrivenOwner(
+  device: RhiDevice,
+  shaderModuleFactory?: PipelineBuilderShaderModuleFactory,
+  recoveryCount = 0,
+): GpuDrivenProduction {
+  return new GpuDrivenProduction(
+    device,
+    shaderModuleFactory ?? {
+      createShaderModule: () =>
+        err(
+          new RhiError({
+            code: 'rhi-not-available',
+            expected: 'the renderer backend exposes shader module creation',
+            hint: 'construct the renderer through the backend pack before activating GPU-driven rendering',
+          }),
+        ),
+    },
+    recoveryCount,
+  );
+}

package/src/assembly/host-contract.ts

@@ -2,10 +2,18 @@ import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import type { World } from '@forgeax/engine-ecs';
 import type { Result, RhiDevice, RhiError, ShaderModule } from '@forgeax/engine-rhi';
 import type { RenderPipelineAsset } from '@forgeax/engine-types';
+import type {
+  DynamicGeometryCandidate,
+  DynamicGeometryError,
+  DynamicGeometryOrdering,
+  DynamicGeometryPrepareInput,
+  DynamicGeometryReceipt,
+} from '../dynamic-geometry';
 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 { FrameObservation, FrameObservationOptions } from '../record/frame';
 import type { CurrentGraphTarget, GraphTargetCaptureRequest } from '../record/frame-snapshot';
@@ -26,6 +34,7 @@ import type {
   RenderWorldLease,
 } from '../render-contract';
 import type { RenderSceneInspection } from '../render-system';
+import type { RenderSceneBounds } from '../scene/render-scene-types';
 import type {
   RenderTarget,
   RenderTargetDescriptor,
@@ -53,7 +62,28 @@ 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;
   attach(world: World): RenderResult<RenderWorldLease, RenderError>;
+  prepareDynamicGeometry(
+    input: DynamicGeometryPrepareInput,
+  ): Result<DynamicGeometryCandidate, DynamicGeometryError>;
+  acceptDynamicGeometry(
+    candidate: DynamicGeometryCandidate,
+    ordering: DynamicGeometryOrdering,
+  ): Result<DynamicGeometryCandidate, DynamicGeometryError>;
+  dynamicGeometryReceipt(candidate: DynamicGeometryCandidate): DynamicGeometryReceipt | undefined;
+  cancelDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
+  retireDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
+  publishDynamicGeometry(
+    frame: {
+      readonly frameId: number;
+      readonly deviceGeneration: number;
+      readonly completed?: Promise<unknown>;
+    },
+    worlds?: readonly object[],
+    fixedStep?: number,
+  ): readonly DynamicGeometryReceipt[];
   createRenderTarget(descriptor: RenderTargetDescriptor): RenderResult<RenderTarget, RenderError>;
   resizeRenderTarget(
     target: RenderTarget,
@@ -69,6 +99,8 @@ export interface RendererHostImplementation {
   ): RenderResult<RenderTargetReadbackTicket, RenderError>;
   destroyRenderTarget(target: RenderTarget): RenderResult<void, RenderError>;
   setProfile(profile: RenderProfile): RenderResult<void, RenderError>;
+  /** Detached world bounds for one record in the last extracted World; undefined if unavailable. */
+  bounds(world: World, entity: number): RenderSceneBounds | undefined;
   inspect(): RenderInspection;
   /**
    * Internal bounded inspection for high-cardinality producers. The public
@@ -80,6 +112,10 @@ export interface RendererHostImplementation {
     readonly gpuDriven: GpuDrivenProductionInspection;
   };
   drawFrame(request: RenderFrameInput): RenderResult<FrameReceipt, RhiError | RenderError>;
+  /** Arm one upcoming frame for receipt-bound color observations. */
+  requestObservation?: (
+    domains: readonly import('../render-contract').FrameObservationDomain[],
+  ) => RenderResult<void, RenderError>;
   observe(
     receipt: FrameReceipt,
     request: FrameObservationRequest,

package/src/assembly/material/assembly.ts

@@ -6,6 +6,10 @@ import {
   type CookedMaterialRecord,
   materialLayerPlanIdentity,
 } from '@forgeax/engine-pack/material-cook';
+import {
+  createStandardPbrArtifactReceipt,
+  type MaterialShaderArtifact,
+} from '@forgeax/engine-shader';
 import type { StandardLayerPlan } from '@forgeax/engine-types';
 import { projectStandardLayerPlan } from './standard-layer-projection.js';
 
@@ -30,3 +34,37 @@ export function assembleMaterialProjection(record: CookedMaterialRecord): Materi
     layerPlan,
   };
 }
+
+/**
+ * Assemble the one built-in Standard PBR artifact from the selected producer WGSL.
+ * 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,
+): 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);
+  return {
+    material: materialShaderId,
+    pass: 'forward',
+    wgsl,
+    layoutIdentity: receipt.reflection.layoutIdentity,
+    bindings: [],
+    deps: [],
+    vertexInputs: receipt.vertexInputs.map(
+      (input): Readonly<Record<string, unknown>> => ({
+        semantic: input.semantic,
+        location: input.location,
+        format: input.format,
+      }),
+    ),
+    receipt,
+  };
+}

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

@@ -283,16 +283,16 @@ export async function prepareMaterialShaders(
   const capValue = (rhiDevice.limits as Readonly<Record<string, number>>)
     .maxStorageBuffersPerShaderStage;
   const webgl2Downlevel = rhiDevice.caps.backendKind === 'wgpu-webgl2';
-  const storageBufferCapable = rhiDevice.caps.storageBuffer;
-  if (storageBufferCapable && typeof capValue === 'number') {
+  let storageBufferCapable = !webgl2Downlevel && rhiDevice.caps.storageBuffer;
+  if (typeof capValue === 'number') {
     const capCheck = assertStorageBufferCap(capValue);
     if (!capCheck.ok) throw capCheck.error;
+    storageBufferCapable = !webgl2Downlevel && rhiDevice.caps.storageBuffer && capCheck.value;
   }
   const extendedLightingShaderAvailable = deriveExtendedLightingCapability(rhiDevice).admitted;
   const projectorAvailable =
     (rhiDevice.limits.maxSampledTexturesPerShaderStage ?? 0) >=
     STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES;
-
   // ── Step 1: manifest load ─────────────────────────────────────────────────
   const registry = getShader();
   const loaded = await registry.loadManifest();
@@ -301,35 +301,46 @@ export async function prepareMaterialShaders(
   }
 
   // ── Step 1b: material shader variant resolution + registration ───────────
-  // feat-20260609-hdrp-cluster-fragment-ggx M1 / w7: dual-axis variant
-  // resolution. At boot time isHdrpActive is always false (URP default),
-  // so CLUSTER_FORWARD_AVAILABLE=false variant is selected. HDRP variant
-  // (CLUSTER_FORWARD_AVAILABLE=true) is resolved later when
-  // clustered Standard profile activation selects the clustered variant.
-  const isHdrpActive = false; // M4: wire to actual renderSystem.frameState.isHdrpActive
+  // feat-20260609-hdrp-cluster-fragment-ggx M1 / w7: the boot resolver selects
+  // the non-clustered variant; clustered Standard activation resolves its own
+  // variant later at record time.
   for (const msEntry of registry.materialShaderManifestEntries()) {
     // bug-20260610: skip synthetic non-material engine entries piggy-backing
     // on the materialShaders channel for variant surfacing (shadow_caster).
     // They use the `forgeax::engine-` prefix and are consumed by Step 2's
     // 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> = {};
-    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
-    // `STORAGE_BUFFER_AVAILABLE=false` key and fails before the first frame.
+    // The same closed resolver drives every manifest axis at boot. This keeps
+    // registration aligned with record-time capability/feature selection and
+    // supplies explicit defaults for opt-in axes such as shadow alpha-mask and
+    // GPU-driven scene-index variants.
+    // Build the exact boot key from the capability facts and explicit defaults.
+    // Record-time callers use resolveMaterialShaderVariantSet below; keeping
+    // the same axes here prevents a physical-material variant from being
+    // registered under a key that cannot be selected by the renderer.
+    const variantDefines: Record<string, boolean> = {
+      STORAGE_BUFFER_AVAILABLE: storageBufferCapable,
+    };
     if (msEntry.variants.some((v) => 'WEBGL2_COMPAT' in v.defines)) {
       variantDefines.WEBGL2_COMPAT = webgl2Downlevel;
     }
-    // Only include CLUSTER_FORWARD_AVAILABLE when the material shader declares
-    // the axis (has a variant with this key), preserving backward compat for
-    // entries without the pragma.
     if (msEntry.variants.some((v) => 'CLUSTER_FORWARD_AVAILABLE' in v.defines)) {
-      variantDefines.CLUSTER_FORWARD_AVAILABLE = isHdrpActive;
+      variantDefines.CLUSTER_FORWARD_AVAILABLE = false;
+    }
+    if (msEntry.variants.some((v) => 'GPU_DRIVEN_SCENE_INDEX_AVAILABLE' in v.defines)) {
+      variantDefines.GPU_DRIVEN_SCENE_INDEX_AVAILABLE = false;
+    }
+    if (msEntry.variants.some((v) => 'GPU_DRIVEN_SCENE_INDEX_EXPLICIT' in v.defines)) {
+      // The boot material is the compact visible-stream path.  Explicit
+      // scene-index dispatches select their own variant at record time; they
+      // must never make the default artifact key unsatisfiable.
+      variantDefines.GPU_DRIVEN_SCENE_INDEX_EXPLICIT = false;
+    }
+    if (msEntry.variants.some((v) => 'ALPHA_MASK' in v.defines)) {
+      // Alpha-mask admission is a per-draw producer fact.  Keep the boot
+      // artifact opaque and resolve ALPHA_MASK=true only for a receipt-owned
+      // shadow batch.
+      variantDefines.ALPHA_MASK = false;
     }
     if (msEntry.variants.some((v) => 'DIRECTIONAL_PCSS_AVAILABLE' in v.defines)) {
       variantDefines.DIRECTIONAL_PCSS_AVAILABLE = directionalPcssCapable(
@@ -345,10 +356,12 @@ export async function prepareMaterialShaders(
     if (msEntry.variants.some((v) => 'EXTENDED_LIGHTING_AVAILABLE' in v.defines)) {
       variantDefines.EXTENDED_LIGHTING_AVAILABLE = extendedLightingShaderAvailable;
     }
-    if (
-      msEntry.identifier === 'forgeax::default-standard-pbr' &&
-      msEntry.variants.some((v) => 'PROJECTOR_AVAILABLE' in v.defines)
-    ) {
+    // A material shader that declares the projector axis owns the same
+    // capability-selected resource pair, regardless of whether it is the
+    // engine Standard entry or a VFX particle entry. Omitting this value for
+    // particle variants asks the manifest for a partial key and fails before
+    // the first frame when the shader does not use the Standard root.
+    if (msEntry.variants.some((v) => 'PROJECTOR_AVAILABLE' in v.defines)) {
       variantDefines.PROJECTOR_AVAILABLE = projectorAvailable;
     }
     if (msEntry.variants.some((v) => 'TRANSMISSION_AVAILABLE' in v.defines)) {
@@ -516,7 +529,15 @@ export async function prepareMaterialShaders(
  * material-shader layouts add a `LayoutKind` member + a PipelineState slot
  * + a switch arm here in one cut (charter P3 extensibility).
  */
-export type LayoutKind = 'pbr' | 'pbr-skin' | 'hdrp-pbr' | 'hdrp-skin' | 'sprite-urp' | 'unlit-urp';
+export type LayoutKind =
+  | 'pbr'
+  | 'pbr-skin'
+  | 'gpu-driven-pbr'
+  | 'gpu-driven-skin'
+  | 'hdrp-pbr'
+  | 'hdrp-skin'
+  | 'sprite-urp'
+  | 'unlit-urp';
 
 function directionalPcssCapable(backendKind: RhiDevice['caps']['backendKind']): boolean {
   return backendKind === 'webgpu' || backendKind === 'wgpu-native';
@@ -627,6 +648,17 @@ export function resolveMaterialShaderBindingContract(
     /@group\s*\(\s*0\s*\)\s*@binding\s*\(\s*1\s*\)\s*var\s+scene_depth\s*:\s*texture_depth_2d\b/u.test(
       withoutComments,
     );
+  const declaresSceneDepthAtZero =
+    /@group\s*\(\s*0\s*\)\s*@binding\s*\(\s*0\s*\)\s*var\s+scene_depth\s*:\s*texture_depth_2d\b/u.test(
+      withoutComments,
+    );
+  const hasMaterialGroup = groups.includes(1);
+  if (declaresView && declaresSceneDepth && hasMaterialGroup) {
+    return 'render-material-and-scene-depth';
+  }
+  if (declaresSceneDepthAtZero && hasMaterialGroup) {
+    return 'render-material-with-scene-depth';
+  }
   if (declaresView && declaresSceneDepth && groups.every((group) => group === 0)) {
     return 'view-and-scene-depth';
   }
@@ -760,8 +792,11 @@ export function shouldDeferMissingPreparedMaterialShader(
 ): boolean {
   return (
     vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInstance ||
+    vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInputInstance ||
     vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentInstance ||
-    vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInstance
+    vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentMaterialInputInstance ||
+    vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInstance ||
+    vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInputInstance
   );
 }
 
@@ -773,6 +808,8 @@ export function selectPipelineLayoutForVariant(
     readonly hdrpProbePbrPipelineLayout?: PipelineLayout | null;
     readonly pbrSkinPipelineLayout: PipelineLayout | null;
     readonly pbrSkinProbePipelineLayout?: PipelineLayout | null;
+    readonly gpuDrivenPbrPipelineLayout?: PipelineLayout | null;
+    readonly gpuDrivenPbrSkinPipelineLayout?: PipelineLayout | null;
     readonly hdrpSkinPipelineLayout?: PipelineLayout | null;
   } | null,
   variantSet: string | undefined,
@@ -780,6 +817,12 @@ export function selectPipelineLayoutForVariant(
 ): PipelineLayout | null {
   if (state === null) return null;
   const probeBlendVariant = variantSet?.includes('PROBE_BLEND_AVAILABLE=true') === true;
+  if (layoutKind === 'gpu-driven-pbr') {
+    return state.gpuDrivenPbrPipelineLayout ?? null;
+  }
+  if (layoutKind === 'gpu-driven-skin') {
+    return state.gpuDrivenPbrSkinPipelineLayout ?? 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/recovery/failure-location.ts

@@ -0,0 +1,62 @@
+import type { DeviceResourceKind } from '../../device/resource-types';
+import type { RecoveryGuidance, RecoveryPhase } from '../renderer-lifecycle';
+
+export interface RecoveryFailureLocation {
+  readonly phase: RecoveryPhase;
+  readonly retryable: boolean;
+  readonly guidance: RecoveryGuidance;
+  readonly owner: string;
+  readonly resourceKind: DeviceResourceKind;
+  readonly cause: unknown;
+}
+
+function recoveryCauseCode(cause: unknown): string | undefined {
+  if (typeof cause !== 'object' || cause === null) return undefined;
+  const directCode = (cause as { readonly code?: unknown }).code;
+  if (typeof directCode === 'string') return directCode;
+  const detail = (cause as { readonly detail?: unknown }).detail;
+  if (typeof detail !== 'object' || detail === null) return undefined;
+  const detailCode = (detail as { readonly code?: unknown }).code;
+  if (typeof detailCode === 'string') return detailCode;
+  return recoveryCauseCode((detail as { readonly cause?: unknown }).cause);
+}
+
+export function createRecoveryFailureLocation(
+  phase: RecoveryPhase,
+  cause: unknown,
+  overrides: Partial<Omit<RecoveryFailureLocation, 'phase' | 'cause'>> = {},
+): RecoveryFailureLocation {
+  const code = recoveryCauseCode(cause) ?? '';
+  const resourceKind: DeviceResourceKind = code.includes('shader')
+    ? 'shader'
+    : code.includes('buffer')
+      ? 'buffer'
+      : code.includes('texture')
+        ? 'texture'
+        : code.includes('binding')
+          ? 'binding'
+          : phase === 'rehydrate'
+            ? 'shader'
+            : phase === 'acquire-adapter' || phase === 'acquire-device'
+              ? 'surface'
+              : phase === 'publish' || phase === 'cleanup'
+                ? 'surface'
+                : 'pipeline';
+  const owner =
+    code.includes('shader') || phase === 'rehydrate'
+      ? 'shader'
+      : phase === 'acquire-adapter' || phase === 'acquire-device'
+        ? 'backend'
+        : phase === 'compile-graph'
+          ? 'pipeline'
+          : 'renderer';
+  return {
+    phase,
+    retryable: false,
+    guidance: 'repair-owner',
+    owner,
+    resourceKind,
+    cause,
+    ...overrides,
+  };
+}

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

@@ -19,18 +19,14 @@ import {
   postProcessShaderEntrySignature,
   postProcessShaderPipelineLabel,
 } from '../../fullscreen-post-process-pass';
-import { createRecoveryColdWorkGuard } from '../../record/recovery-pipeline';
-import type {
-  PipelineState,
-  RecoveryColdWorkGuard,
-  RenderSystemInternals,
-} from '../../record/render-context';
+import { resolveStandardPbrProgram } from '../../gpu-driven/pbr-program';
+import type { PipelineState, RenderSystemInternals } from '../../record/render-context';
 import type {
   RecoveryGraphCandidate,
   RecoveryPostProcessResources,
   RecoveryRootBundle,
-  RenderSystem,
-} from '../../render-system';
+} from '../../recovery/types';
+import type { RenderSystem } from '../../render-system';
 import type { RhiBackendPack } from '../backend-contract';
 import {
   type LayoutKind,
@@ -42,8 +38,9 @@ import type { MeshSsboGrowResult, MeshSsboState } from '../mesh-ssbo-grow';
 import { structuredRendererCause } from '../renderer-facade';
 import { ensureContextConfigured } from '../renderer-helpers';
 import type { RecoveryContinuation, RecoveryDeadline, RecoveryPhase } from '../renderer-lifecycle';
-import type { RecoveryFailureLocation, WebGPURendererInternals } from '../webgpu-renderer';
+import type { WebGPURendererInternals } from '../webgpu-renderer';
 import { attachDeviceLostFanout } from './device-loss-fanout';
+import type { RecoveryFailureLocation } from './failure-location';
 import { buildGenerationAggregate, type GenerationAggregate } from './generation';
 import {
   acquireDeviceGeneration,
@@ -166,7 +163,6 @@ export interface RendererRecoveryDependencies {
     candidatePostProcessResources: RecoveryPostProcessResources,
     recoveryRootBundle: RecoveryRootBundle,
     recoveryGraphCandidate: RecoveryGraphCandidate | undefined,
-    recoveryColdWorkGuard: RecoveryColdWorkGuard,
   ) => void;
 }
 
@@ -253,7 +249,6 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
     // old roots remain authoritative until the final synchronous publication.
     const candidateGpuStore = new GpuResidencyCache();
     const candidateDynamicTextureStore = new DynamicTextureStore();
-    const recoveryColdWorkGuard = createRecoveryColdWorkGuard();
     // Re-acquire through the SAME backend pack (the
     // idempotent factory primitives tryCreateWebGPURenderer uses). On the
     // adapter / device failure paths, health stays `device-lost` (A-AC-07):
@@ -568,14 +563,22 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
     const candidateInternals = Object.create(internals) as WebGPURendererInternals &
       RenderSystemInternals;
     Object.defineProperties(candidateInternals, {
+      assets: { value: assets },
       device: { value: candidateState.device },
       context: { value: candidateState.context },
       deviceScope: { value: candidateState.scope },
       gpuStore: { value: candidateState.gpuStore },
       dynamicTextureStore: { value: candidateState.dynamicTextureStore },
-      recoveryColdWorkGuard: { value: undefined },
       getMaterialShaderPipeline: { value: getMaterialShaderPipeline },
       getMaterialShaderPipelineEntry: { value: getMaterialShaderPipelineEntry },
+      getMaterialShaderArtifact: {
+        value: (materialShaderId: string, vertexColorAvailable = false) =>
+          resolveStandardPbrProgram(
+            candidatePipelineState.gpuDrivenPbrPrograms,
+            materialShaderId,
+            vertexColorAvailable,
+          )?.artifact,
+      },
       getMaterialShaderBindingContract: { value: getCachedMaterialShaderBindingContract },
       getParamSchema: { value: getParamSchema },
       getMaterialBindGroupLayout: { value: getMaterialBindGroupLayout },
@@ -594,20 +597,20 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
         value: (
           id: string,
           bgl: BindGroupLayout,
-          colorFormat: GPUTextureFormat,
+          colorFormats: readonly GPUTextureFormat[],
           entryOverride?: PostProcessShaderEntry,
         ) => {
           const entry = entryOverride ?? candidateInternals.lookupPostProcess?.(id);
           if (entry === undefined || candidateInternals.buildPostProcessPipeline === undefined) {
             return null;
           }
-          const key = `${id}|${colorFormat}|${postProcessShaderEntrySignature(entry)}`;
+          const key = `${id}|${colorFormats.join(',')}|${postProcessShaderEntrySignature(entry)}`;
           const cached = candidatePostProcessPipelineCache.get(key);
           if (cached !== undefined) return cached;
           const built = candidateInternals.buildPostProcessPipeline(
             entry,
             bgl,
-            colorFormat,
+            colorFormats,
             postProcessShaderPipelineLabel(id, entry.source),
           );
           if (built === null) return null;
@@ -632,7 +635,7 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
       releaseCandidate();
       return err(new RecoverError('recover-device-unavailable'));
     }
-    const graphPreparation = await renderSystem.prepareRecoveryGraphCandidate({
+    const graphPreparation = renderSystem.prepareRecoveryGraphCandidate({
       internals: candidateInternals,
       pipelineState: candidatePipelineState,
     });
@@ -872,7 +875,6 @@ export function createRendererRecovery(deps: RendererRecoveryDependencies): Rend
         candidatePostProcessResources,
         preparedRecoveryRoots,
         recoveryGraphCandidate,
-        recoveryColdWorkGuard,
       );
       if (recoveryGraphCandidate !== undefined) {
         recoveryGraphCandidate = undefined;

package/src/assembly/renderer-facade.ts

@@ -3,6 +3,11 @@
 // lease/receipt contract and owns the profile/error projection helpers.
 
 import { err, ok, type RhiError } from '@forgeax/engine-rhi';
+import type {
+  DynamicGeometryCandidate,
+  DynamicGeometryOrdering,
+  DynamicGeometryPrepareInput,
+} from '../dynamic-geometry';
 import { type RecoverFailure, RecoveryFailedError } from '../errors/recover';
 import {
   type RenderError,
@@ -16,6 +21,7 @@ import {
   STANDARD_POST_STAGE_NAMES,
 } from '../pipeline/standard-profile';
 import type {
+  FrameObservationDomain,
   Renderer,
   RendererError,
   RendererEventListener,
@@ -83,6 +89,8 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
   });
 
   return {
+    instances: renderer.instances,
+    bounds: (world, entity) => (disposed ? undefined : renderer.bounds(world, entity)),
     attach: (world) => {
       const result = renderer.attach(world);
       return result.ok
@@ -94,6 +102,18 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
             }),
           );
     },
+    prepareDynamicGeometry: (input: DynamicGeometryPrepareInput) =>
+      renderer.prepareDynamicGeometry(input),
+    acceptDynamicGeometry: (
+      candidate: DynamicGeometryCandidate,
+      ordering: DynamicGeometryOrdering,
+    ) => renderer.acceptDynamicGeometry(candidate, ordering),
+    dynamicGeometryReceipt: (candidate: DynamicGeometryCandidate) =>
+      renderer.dynamicGeometryReceipt(candidate),
+    cancelDynamicGeometry: (candidate: DynamicGeometryCandidate) =>
+      renderer.cancelDynamicGeometry(candidate),
+    retireDynamicGeometry: (candidate: DynamicGeometryCandidate) =>
+      renderer.retireDynamicGeometry(candidate),
     createRenderTarget: (descriptor) => renderer.createRenderTarget(descriptor),
     resizeRenderTarget: (target, descriptor) => renderer.resizeRenderTarget(target, descriptor),
     createRenderTargetTextureSource: (target, options) =>
@@ -130,10 +150,19 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
           kind: 'frame-submitted',
           frameId: result.value.frameId,
           deviceGeneration: result.value.deviceGeneration,
+          receipt: result.value,
         }),
       );
       return ok(result.value);
     },
+    requestObservation: (domains: readonly FrameObservationDomain[]) =>
+      renderer.requestObservation?.(domains) ??
+      err(
+        new RendererOperationError('renderer-state-invalid', {
+          operation: 'request-observation',
+          state: lifecycle.state(),
+        }),
+      ),
     inspect: () => ({ ...renderer.inspect(), state: lifecycle.state() }),
     observe: (receipt, request) => renderer.observe(receipt, request),
     subscribe: (listener) => {