@forgeax/engine-render 0.1.28 → 0.1.30

package/src/record/recovery-pipeline.ts

@@ -1,13 +1,9 @@
 import {
+  DEFAULT_VERTEX_ATTRIBUTE_MAP,
   deriveVertexLayoutProjection,
   type VertexLayoutProjection,
 } from '@forgeax/engine-geometry';
-import type {
-  MaterialRenderState,
-  PassKind,
-  PrimitiveTopology,
-  VertexAttributeMap,
-} from '@forgeax/engine-types';
+import type { MaterialRenderState, PassKind, PrimitiveTopology } from '@forgeax/engine-types';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
 import {
   isStandardPbrMaterialShader,
@@ -42,6 +38,7 @@ import type {
 export interface RecoveryPipelineReadiness {
   readonly pipelineSpecs: readonly PipelineSpec[];
   /** Re-resolve every candidate request and assert a stable cache hit. */
+  readonly assertPreparedCache: () => void;
   readonly assertFirstRecoveryFrame: () => void;
 }
 
@@ -53,6 +50,7 @@ export interface RecoveryPipelineReadiness {
  */
 export function createRecoveryColdWorkGuard(): RecoveryColdWorkGuard {
   let armed = false;
+  let recording = false;
   let finished = false;
   let pipelineColdWork = 0;
   let uploadColdWork = 0;
@@ -71,11 +69,17 @@ export function createRecoveryColdWorkGuard(): RecoveryColdWorkGuard {
       pipelineColdWork = 0;
       uploadColdWork = 0;
     },
+    beginFrame(): void {
+      recording = true;
+    },
+    endFrame(): void {
+      recording = false;
+    },
     notePipelineColdWork(): void {
-      if (armed && !finished) fail('pipeline');
+      if (armed && recording && !finished) fail('pipeline');
     },
     noteUploadColdWork(): void {
-      if (armed && !finished) fail('upload');
+      if (armed && recording && !finished) fail('upload');
     },
     finish(): void {
       if (!armed || finished) return;
@@ -96,13 +100,6 @@ interface RecoveryPipelineRequest {
   readonly resolve: () => MaterialShaderPipelineEntry | null;
 }
 
-const DEFAULT_VERTEX_ATTRIBUTES: VertexAttributeMap = {
-  position: new Float32Array(0),
-  normal: new Float32Array(0),
-  uv: new Float32Array(0),
-  tangent: new Float32Array(0),
-};
-
 function optionalRenderState(
   state: MaterialRenderState | undefined,
 ): { readonly renderState: MaterialRenderState } | Record<string, never> {
@@ -174,6 +171,9 @@ function addRequest(input: {
   readonly additionalColorFormats?: readonly GPUTextureFormat[];
   readonly depthFormatOverride?: GPUTextureFormat | null;
   readonly vertexLayoutProjection?: VertexLayoutProjection;
+  readonly vertexEntry?: string;
+  readonly fragmentEntry?: string;
+  readonly layoutKindOverride?: 'pbr' | 'pbr-skin';
   readonly preserveUndefinedVariant?: boolean;
   readonly variantAlreadyResolved?: boolean;
 }): void {
@@ -204,6 +204,8 @@ function addRequest(input: {
       id: input.materialShaderId,
       passKind,
       variantSet: resolvedVariantSet,
+      ...(input.vertexEntry === undefined ? {} : { vertexEntry: input.vertexEntry }),
+      ...(input.fragmentEntry === undefined ? {} : { fragmentEntry: input.fragmentEntry }),
     }),
     attachments: Object.freeze({
       colorFormats: Object.freeze([...colorFormats]),
@@ -213,7 +215,7 @@ function addRequest(input: {
     geometry: Object.freeze({
       topology: input.topology ?? 'triangle-list',
       stripIndexFormat: input.indexFormat,
-      vertexLayout: DEFAULT_VERTEX_ATTRIBUTES,
+      vertexLayout: DEFAULT_VERTEX_ATTRIBUTE_MAP,
       ...(projection === undefined ? {} : { vertexLayoutProjection: projection }),
       ...(shaderUvSetCount !== undefined && shaderUvSetCount > 1
         ? {
@@ -243,8 +245,11 @@ function addRequest(input: {
       undefined,
       projection,
       undefined,
+      input.layoutKindOverride,
       undefined,
       input.additionalColorFormats,
+      input.vertexEntry,
+      input.fragmentEntry,
     ) ?? null;
   input.requests.push({ spec, resolve });
 }
@@ -261,12 +266,7 @@ function addStandardMaterialRequests(input: {
   readonly colorFormatOverride?: GPUTextureFormat;
   readonly reflectionFallbackAvailable: boolean;
 }): void {
-  const pointsLinesProjection = deriveVertexLayoutProjection({
-    position: new Float32Array(0),
-    normal: new Float32Array(0),
-    uv: new Float32Array(0),
-    tangent: new Float32Array(0),
-  });
+  const pointsLinesProjection = deriveVertexLayoutProjection(DEFAULT_VERTEX_ATTRIBUTE_MAP);
   for (const entry of input.validated) {
     if (entry.source.pointsLines !== undefined) {
       const pointsLinesMaterial = entry.source.material;
@@ -299,7 +299,7 @@ function addStandardMaterialRequests(input: {
     // The probe record is an object-level ABI extension of the built-in
     // Standard PBR family. Recovery must request the same variant that the
     // live record path will select, otherwise the first post-recovery draw
-    // discovers a cold PSO and the cold-work guard correctly rejects it.
+    // discovers avoidable cold PSO work.
     const probeBlendRecordAvailable =
       input.internals.device.caps.storageBuffer && entry.source.probeBlendRecord !== undefined;
     const standardPbrCapabilityVariantSet = standardTopologyVariantSet(
@@ -376,9 +376,7 @@ function addStandardMaterialRequests(input: {
           : undefined
         : entry.variantSet === undefined
           ? materialCapabilityVariantSet
-          : materialCapabilityVariantSet === ''
-            ? entry.variantSet
-            : `${materialCapabilityVariantSet}+${entry.variantSet}`;
+          : `${materialCapabilityVariantSet}+${entry.variantSet}`;
       const reflectionFallbackVariant =
         input.reflectionFallbackAvailable && materialShaderId === 'forgeax::default-standard-pbr'
           ? (() => {
@@ -527,80 +525,60 @@ function addShadowRequests(input: {
   readonly validated: readonly ValidatedRenderable[];
   readonly dispatch: readonly DispatchEntry[];
 }): void {
-  addRequest({
-    requests: input.requests,
-    requestKeys: input.requestKeys,
-    internals: input.internals,
-    pipelineState: input.pipelineState,
-    materialShaderId: SHADOW_CASTER_SHADER_ID,
-    isHdrTarget: false,
-    topology: 'triangle-list',
-    variantSet: shadowCasterVariantSet(input.internals.device.caps.storageBuffer, false),
-    passKind: 'shadow-caster',
-    sampleCount: 1,
-    variantAlreadyResolved: true,
-  });
-  const customByRenderable = new Map<
-    number,
-    Map<number, { id: string; state: MaterialRenderState | undefined }>
-  >();
-  for (const dispatch of input.dispatch) {
-    if (dispatch.tags.LightMode !== 'ShadowCaster' || dispatch.materialShaderId === undefined)
+  // Recovery has no record context, so it cannot use the context-backed
+  // shadowShaderMap. Group the producer dispatch facts directly and warm every
+  // authored ShadowCaster pass for the matching renderable/material pair.
+  const dispatches = new Map<number, Map<number, DispatchEntry[]>>();
+  for (const candidate of input.dispatch) {
+    if (candidate.tags.LightMode !== 'ShadowCaster' || candidate.materialShaderId === undefined)
       continue;
-    let materials = customByRenderable.get(dispatch.renderableIndex);
-    if (materials === undefined) {
-      materials = new Map();
-      customByRenderable.set(dispatch.renderableIndex, materials);
+    const byMaterial = dispatches.get(candidate.renderableIndex);
+    if (byMaterial === undefined) {
+      dispatches.set(candidate.renderableIndex, new Map([[candidate.materialHandle, [candidate]]]));
+    } else {
+      const entries = byMaterial.get(candidate.materialHandle);
+      if (entries === undefined) byMaterial.set(candidate.materialHandle, [candidate]);
+      else entries.push(candidate);
     }
-    materials.set(dispatch.materialHandle, {
-      id: dispatch.materialShaderId,
-      state: dispatch.renderState,
-    });
   }
   for (const entry of input.validated) {
-    const triangles = entry.mesh.submeshes.filter(
-      (submesh) => submesh.topology === 'triangle-list' || submesh.topology === 'triangle-strip',
-    );
-    if (triangles.length === 0) continue;
-    if (entry.source.skin !== undefined) {
-      addRequest({
-        requests: input.requests,
-        requestKeys: input.requestKeys,
-        internals: input.internals,
-        pipelineState: input.pipelineState,
-        materialShaderId: SHADOW_CASTER_SHADER_ID,
-        isHdrTarget: false,
-        topology: entry.mesh.submeshes[0]?.topology ?? 'triangle-list',
-        indexFormat: entry.mesh.indexFormat,
-        variantSet: shadowCasterVariantSet(input.internals.device.caps.storageBuffer, true),
-        passKind: 'shadow-caster',
-        sampleCount: 1,
-        vertexLayoutProjection: entry.mesh.layoutProjection,
-        variantAlreadyResolved: true,
-      });
-    }
-    for (const submesh of triangles) {
+    for (const submesh of entry.mesh.submeshes) {
+      if (submesh.topology !== 'triangle-list' && submesh.topology !== 'triangle-strip') continue;
       const material = entry.source.materials[submesh.materialSlot] ?? entry.source.material;
-      const custom = customByRenderable
-        .get(entry.renderableIndex)
-        ?.get(material.materialHandle ?? 0);
-      if (
-        entry.source.skin === undefined &&
-        custom !== undefined &&
-        (custom.id !== 'forgeax::default-shadow-caster' || custom.state !== undefined)
-      ) {
+      const shadowDispatches =
+        dispatches.get(entry.renderableIndex)?.get(material.materialHandle ?? 0) ?? [];
+      for (const dispatch of shadowDispatches.length === 0 ? [undefined] : shadowDispatches) {
+        const materialShaderId =
+          dispatch?.materialShaderId === 'forgeax::default-standard-pbr' ||
+          dispatch?.materialShaderId === undefined
+            ? SHADOW_CASTER_SHADER_ID
+            : dispatch.materialShaderId;
         addRequest({
           requests: input.requests,
           requestKeys: input.requestKeys,
           internals: input.internals,
           pipelineState: input.pipelineState,
-          materialShaderId: custom.id,
+          materialShaderId,
           isHdrTarget: false,
-          ...optionalRenderState(custom.state),
-          topology: 'triangle-list',
+          ...optionalRenderState(dispatch?.renderState),
+          topology: submesh.topology,
+          indexFormat: entry.mesh.indexFormat,
+          ...optionalVariant(
+            materialShaderId === SHADOW_CASTER_SHADER_ID
+              ? shadowCasterVariantSet(
+                  input.internals.device.caps.storageBuffer,
+                  entry.source.skin !== undefined,
+                )
+              : undefined,
+          ),
           passKind: 'shadow-caster',
           sampleCount: 1,
-          preserveUndefinedVariant: true,
+          vertexLayoutProjection: entry.mesh.layoutProjection,
+          layoutKindOverride: entry.source.skin === undefined ? 'pbr' : 'pbr-skin',
+          ...(dispatch?.vertexEntry === undefined ? {} : { vertexEntry: dispatch.vertexEntry }),
+          ...(dispatch?.fragmentEntry === undefined
+            ? {}
+            : { fragmentEntry: dispatch.fragmentEntry }),
           variantAlreadyResolved: true,
         });
       }
@@ -671,7 +649,7 @@ export function prepareRecoveryPipelineReadiness(input: {
       dispatch: input.dispatch,
     });
   }
-  const assertFirstRecoveryFrame = (): void => {
+  const assertPreparedCache = (): void => {
     for (const request of requests) {
       const first = request.resolve();
       const second = request.resolve();
@@ -687,9 +665,10 @@ export function prepareRecoveryPipelineReadiness(input: {
       }
     }
   };
-  assertFirstRecoveryFrame();
+  assertPreparedCache();
   return {
     pipelineSpecs: Object.freeze(requests.map((request) => request.spec)),
-    assertFirstRecoveryFrame,
+    assertPreparedCache,
+    assertFirstRecoveryFrame: assertPreparedCache,
   };
 }

package/src/record/render-context.ts

@@ -15,6 +15,7 @@ import type {
   RhiDevice,
   RenderPipeline as RhiRenderPipeline,
   Sampler,
+  ShaderModule,
   Texture,
   TextureFormat,
   TextureView,
@@ -40,6 +41,9 @@ import type { MeshGpuHandles } from '../device/gpu-residency';
 import type { EngineMetrics } from '../engine-metrics';
 import type { RenderFeatureHost } from '../features/host';
 import type { RenderFeatureShaderModuleMode } from '../features/types';
+import type { GpuDrivenPbrProgram } from '../gpu-driven/pbr-program';
+import type { GpuDrivenShadowBatchProjection } from '../gpu-driven/production-raster';
+import type { ShadowViewStatePool } from '../gpu-driven/shadow-views';
 import {
   GPU_TEXTURE_USAGE_COPY_SRC,
   GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
@@ -56,7 +60,9 @@ import type { PointsLinesInspection } from '../points-lines/inspection';
 import type { PointsLinesRecordPlan } from '../points-lines/record';
 import type { ReflectionProbeTable } from '../reflection/gpu-table';
 import type { ReflectionProbeSelectionResult } from '../reflection/projection';
+import type { FrameObservationDomain } from '../render-contract';
 import type { SsrAdmissionIdentity } from '../ssr/identity';
+import type { TypedFrameObservationCapture } from '../typed-render-graph-primitives';
 import type { GpuPassTimingReason } from './gpu-pass-timing/errors';
 import type {
   GpuPassTimingCapture,
@@ -82,7 +88,7 @@ export interface ReflectionProbeRecordState {
   >;
   /** Demand is derived from this frame's renderable/source selection. */
   readonly fallbackDemand?: boolean;
-  /** True when at least one selected row must prove a non-zero readback. */
+  /** Non-neutral sources require a nonzero diagnostic sample when capture is enabled. */
   readonly fallbackHasNonNeutral?: boolean;
   readonly completeSubmission: (
     submitted: boolean,
@@ -109,27 +115,19 @@ export interface MaterialShaderPipelineEntry {
   readonly group2Contract: PipelineGroup2Contract;
 }
 
-/**
- * Armed only for the first published recovery frame. Candidate preparation
- * must make every pipeline and static residency lookup a cache hit before this
- * guard is armed; a miss is a hard failure before queue submission.
- */
-export interface RecoveryColdWorkGuard {
-  arm(): void;
-  notePipelineColdWork(): void;
-  noteUploadColdWork(): void;
-  finish(): void;
-}
-
 import type {
+  AtmosphereShaderSources,
   RenderDebugOverlay,
   RenderPipelineContext,
   RenderRecordPhase,
+  SsrShaderSources,
   VolumetricFogShaderSources,
 } from '../render-contract';
+import type { GpuDrivenStandardPbrFrameResources } from '../render-pipeline';
 import type {
   DispatchEntry,
   MaterialSnapshot,
+  ShadowCasterMembership,
   SkyboxSnapshot,
   SkylightSnapshot,
 } from '../render-system-extract';
@@ -146,11 +144,43 @@ import type {
 } from './frame-snapshot';
 import type { FoldDispatchPlan } from './mesh-ssbo';
 
+/**
+ * Armed only for the first published recovery frame. Candidate preparation
+ * must make every pipeline and static residency lookup a cache hit before this
+ * guard is armed; a miss during draw is a hard failure before queue submission.
+ * Explicit preparation between draws remains allowed, including new geometry
+ * admitted on the first fixed step after device recovery.
+ */
+export interface RecoveryColdWorkGuard {
+  arm(): void;
+  beginFrame(): void;
+  endFrame(): void;
+  notePipelineColdWork(): void;
+  noteUploadColdWork(): void;
+  finish(): void;
+}
+
 export interface RenderSystemRuntime {
   readonly device: RhiDevice;
+  /** Current renderer device generation used to fence receipt-bound captures. */
+  readonly deviceGeneration?: number;
+  /** Public receipt identity reserved before graph encoding. */
+  readonly observationFrameId?: number | undefined;
+  /** Graph identity written by the typed graph for the current receipt. */
+  observationGraphGeneration?: number | undefined;
+  /** Renderer-owned capture bridge consumed after queue submission. */
+  readonly observationCaptureOwner?:
+    | {
+        register(capture: TypedFrameObservationCapture): void;
+        consume(frameNumber: number): readonly TypedFrameObservationCapture[];
+        drain(): readonly TypedFrameObservationCapture[];
+      }
+    | undefined;
   /** Internal backend-fixture hook evaluated at the submit transaction edge. */
   readonly beforeSubmit?: ((device: RhiDevice) => RhiError | undefined) | undefined;
   readonly deviceScope: DeviceScope;
+  /** Domains explicitly armed for the frame being encoded. */
+  readonly observationCaptureDomains?: readonly FrameObservationDomain[] | undefined;
   /** Resolve a recorder/backend wrapper before configuring the native surface. */
   readonly resolveSurfaceDevice?: (device: RhiDevice) => Result<RhiDevice, RhiError>;
   readonly errorRegistry: RhiErrorListenerRegistry;
@@ -164,6 +194,16 @@ export interface RenderSystemRuntime {
   /** Producer-owned cooked Standard PBR artifact used by GPU-driven projection. */
   readonly getMaterialShaderArtifact?: (
     materialShaderId: string,
+    request?:
+      | {
+          readonly vertexColorAvailable?: boolean;
+          readonly deformation?: 'rigid' | 'skin';
+          readonly clustered?: boolean;
+          readonly reflectionFallback?: boolean;
+          readonly pass?: 'forward' | 'shadow' | 'depth';
+          readonly address?: 'direct' | 'scene-index';
+        }
+      | boolean,
   ) => MaterialShaderArtifact | undefined;
   readonly getMaterialShaderPipeline?: (
     materialShaderId: string,
@@ -181,10 +221,14 @@ export interface RenderSystemRuntime {
     vertexLayout?: string,
     vertexLayoutProjection?: VertexLayoutProjection,
     shaderModuleMode?: RenderFeatureShaderModuleMode,
-    layoutKindOverride?: 'pbr' | 'pbr-skin',
+    layoutKindOverride?: 'pbr' | 'pbr-skin' | 'gpu-driven-pbr' | 'gpu-driven-skin',
+    /** Optional vertex entry override for receipt-owned scene-index passes. */
+    vertexEntryPoint?: string,
     additionalColorFormats?: readonly GPUTextureFormat[],
     vertexEntry?: string,
     fragmentEntry?: string,
+    particleInputLanes?: number,
+    fragmentConstants?: Readonly<Record<string, number>>,
   ) => RhiRenderPipeline | null;
   readonly getMaterialShaderPipelineEntry?: (
     materialShaderId: string,
@@ -202,22 +246,36 @@ export interface RenderSystemRuntime {
     vertexLayout?: string,
     vertexLayoutProjection?: VertexLayoutProjection,
     shaderModuleMode?: RenderFeatureShaderModuleMode,
-    layoutKindOverride?: 'pbr' | 'pbr-skin',
+    layoutKindOverride?: 'pbr' | 'pbr-skin' | 'gpu-driven-pbr' | 'gpu-driven-skin',
+    /** Optional vertex entry override for receipt-owned scene-index passes. */
+    vertexEntryPoint?: string,
     additionalColorFormats?: readonly GPUTextureFormat[],
     vertexEntry?: string,
     fragmentEntry?: string,
+    particleInputLanes?: number,
+    fragmentConstants?: Readonly<Record<string, number>>,
   ) => MaterialShaderPipelineEntry | null;
   /** Reflection-derived UV count included in the material PipelineSpec cache key. */
   readonly getMaterialShaderUvSetCount?: (materialShaderId: string) => number | undefined;
   readonly getMaterialShaderBindingContract?: (
     materialShaderId: string,
-  ) => 'group-0' | 'group-0-resource' | 'view-only' | 'view-and-scene-depth' | 'render-material';
+  ) =>
+    | 'group-0'
+    | 'group-0-resource'
+    | 'view-only'
+    | 'view-and-scene-depth'
+    | 'render-material-with-scene-depth'
+    | 'render-material-and-scene-depth'
+    | 'render-material';
   readonly getParamSchema?: (materialShaderId: string) => readonly ParamSchemaEntry[] | undefined;
   readonly getMaterialBindGroupLayout?: (
     materialShaderId: string,
     materialParamSchema?: readonly ParamSchemaEntry[],
   ) => BindGroupLayout | undefined;
-  recoveryColdWorkGuard?: RecoveryColdWorkGuard | undefined;
+  /** Handle-first factory for built-in same-frame GPU producers. */
+  readonly immediateShaderModuleFactory?: PipelineBuilderShaderModuleFactory;
+  /** Optional guard for the first recovery frame's cold-work boundary. */
+  readonly recoveryColdWorkGuard?: RecoveryColdWorkGuard | undefined;
   readonly metrics: EngineMetrics;
   readonly lookupPostProcess?: (
     id: string,
@@ -226,7 +284,7 @@ export interface RenderSystemRuntime {
   readonly getPostProcessPipeline?: (
     id: string,
     bgl: BindGroupLayout,
-    colorFormat: GPUTextureFormat,
+    colorFormats: readonly GPUTextureFormat[],
     entry?: import('../fullscreen-post-process-pass').PostProcessShaderEntry,
   ) => RhiRenderPipeline | null;
   /** Candidate-owned post-process pipelines transferred at publication. */
@@ -371,15 +429,27 @@ export interface PipelineState {
   readonly probeInstancesBindGroupLayout?: BindGroupLayout;
   readonly identityInstanceBuffer: Buffer;
   readonly defaultSampler: Sampler;
-  readonly nearestSampler: Sampler;
   readonly fallbackTextureView: TextureView;
   readonly unlitPipeline: RhiRenderPipeline | null;
   readonly standardPipeline: RhiRenderPipeline | null;
+  /** Producer-owned Standard PBR module for this device generation. */
+  readonly standardPbrShaderModule: ShaderModule | null;
+  /** Producer-owned skinned Standard PBR module for this device generation. */
+  readonly pbrSkinShaderModule: ShaderModule | null;
+  /** Producer-resolved Standard PBR UV ABI count for geometry projection. */
+  readonly standardPbrShaderUvSetCount: number;
   readonly unlitPipelineMsaa: RhiRenderPipeline | null;
   readonly unlitPipelineHdrMsaa: RhiRenderPipeline | null;
   readonly pbrPipelineLayout: PipelineLayout | null;
+  /** Dedicated slot-3 layout for scene-index GPU-driven Standard PBR draws. */
+  readonly gpuDrivenInstancesBindGroupLayout?: BindGroupLayout | null;
+  readonly gpuDrivenPbrPipelineLayout?: PipelineLayout | null;
+  /** Device-owned shader modules paired with their exact Standard PBR receipts. */
+  readonly gpuDrivenPbrPrograms?: ReadonlyMap<string, GpuDrivenPbrProgram>;
+  readonly gpuDrivenPbrSkinPipelineLayout?: PipelineLayout | null;
   readonly pbrProbePipelineLayout?: PipelineLayout | null;
   readonly hdrpPbrPipelineLayout: PipelineLayout | null;
+  readonly hdrpMeshBindGroupLayout?: BindGroupLayout | null;
   readonly hdrpProbePbrPipelineLayout?: PipelineLayout | null;
   readonly hdrpClusterMembershipPipeline: ComputePipeline | null;
   readonly hdrpClusterMembershipBindGroupLayout: BindGroupLayout | null;
@@ -420,6 +490,7 @@ export interface RenderSystemInternals extends RenderSystemRuntime {
   readonly build?: string | undefined;
   /** Host identity binding for the renderer-owned SSR dependency seam. */
   readonly ssrIdentity?: SsrAdmissionIdentity | undefined;
+  readonly captureReflectionFallbackReadback?: boolean | undefined;
   readonly standardProfile?: StandardProfile | undefined;
   readonly standardPipeline: RenderFrameState['activePipeline'];
   readonly featureHost?: RenderFeatureHost | undefined;
@@ -453,7 +524,7 @@ export interface RenderSystemInternals extends RenderSystemRuntime {
     | ((
         entry: import('../fullscreen-post-process-pass').PostProcessShaderEntry,
         bgl: BindGroupLayout,
-        colorFormat: GPUTextureFormat,
+        colorFormats: readonly GPUTextureFormat[],
         label: string,
       ) => RhiRenderPipeline | null)
     | undefined;
@@ -469,9 +540,15 @@ export interface RenderSystemInternals extends RenderSystemRuntime {
   ) => void;
   /** Composed renderer utility sources installed atomically at build-ready. */
   volumetricFogShaders?: VolumetricFogShaderSources | undefined;
+  /** Composed renderer utility sources installed atomically at build-ready. */
+  ssrShaders?: SsrShaderSources | undefined;
+  /** Composed renderer utility sources installed atomically at build-ready. */
+  atmosphereShaders?: AtmosphereShaderSources | undefined;
 }
 
 export interface _StandardForwardSceneView {
+  readonly environmentIbl?: { readonly irradiance: TextureView; readonly prefilter: TextureView };
+  readonly captureDispatch?: readonly DispatchEntry[];
   readonly assets: AssetRegistry;
   readonly store: import('../device/gpu-residency').GpuResidencyCache;
   readonly pipelineState: PipelineState;
@@ -492,9 +569,6 @@ export interface _StandardForwardSceneView {
   readonly profilePhase?: <T>(phase: RenderRecordPhase, action: () => T) => T;
   readonly directionalShadowCacheReuse: boolean;
   readonly world: World;
-  readonly gpuDrivenEntityKeys: ReadonlySet<number>;
-  /** Renderer-local world namespace paired with gpuDrivenEntityKeys. */
-  readonly gpuDrivenWorldKeys?: readonly number[];
   readonly tonemapActive: boolean;
   readonly geometryColorView: TextureView | null;
   readonly geometryDepthView: TextureView | null;
@@ -513,8 +587,33 @@ export interface _StandardForwardSceneView {
   readonly foldDispatchPlan: FoldDispatchPlan | null;
   readonly materialSlotIndices: readonly (readonly number[])[];
   readonly materialSlots: readonly MaterialSnapshot[];
-  readonly materialSlotOwners: readonly number[];
+  readonly materialSlotOwners: readonly ValidatedRenderable[];
   readonly materialSlotCount: number;
+  /** Filled by main-pass material producers before the GPU-driven raster tail. */
+  readonly gpuDrivenStandardPbrFrameResources?: GpuDrivenStandardPbrFrameResources;
+  /** Scene table retained by the renderer even when no draw is GPU-admitted. */
+  readonly gpuDrivenSceneMaterialBuffer?: Buffer;
+  /** Concrete main-pass draw identities already claimed by the capable GPU lane. */
+  readonly gpuDrivenDrawKeys?: ReadonlySet<string>;
+  readonly gpuDrivenShadowViews?: ShadowViewStatePool;
+  readonly gpuDrivenShadowBatchProjections?: ReadonlyMap<
+    string,
+    ReadonlyMap<number, GpuDrivenShadowBatchProjection>
+  >;
+  /** Concrete ShadowCaster keys already claimed by the capable GPU subset. */
+  readonly gpuDrivenShadowDrawKeys?: ReadonlySet<string>;
+  /** View-scoped ShadowCaster claims for exact CPU residual routing. */
+  readonly gpuDrivenShadowDrawKeysByView?: ReadonlyMap<string, ReadonlySet<string>>;
+  /** Extracted structured ShadowCaster ownership facts. */
+  readonly shadowCasterMembership?: readonly ShadowCasterMembership[];
+  /** Complete retained ShadowCaster rows, including camera-culled casters. */
+  readonly shadowValidatedOrdered?: readonly ValidatedRenderable[];
+  /** Dispatch entries remapped to the complete retained ShadowCaster rows. */
+  readonly shadowDispatch?: readonly DispatchEntry[];
+  /** Mesh-SSBO slot base reserved for the retained ShadowCaster rows. */
+  readonly shadowMeshSsboBase?: number;
+  /** Renderer-stable world keys used by ShadowCaster ownership identities. */
+  readonly shadowCasterWorldKeys?: readonly number[];
   readonly pointsLines: PointsLinesRecordOwner | undefined;
   readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
   /** Record-stage proof callback; invoked only after a real draw command is encoded. */