@forgeax/engine-render 0.1.33 → 0.1.35

package/src/render-system-extract-tail.ts

@@ -37,11 +37,11 @@ import {
   ASSET_ERROR_HINTS,
   AssetError,
   derive,
-  err,
   handleSlot,
   materialValuesToLinearRuntime,
   toShared,
 } from '@forgeax/engine-types';
+import { type ExtractedCloudLayer, extractCloudLayer } from './cloud/extract';
 import {
   Atmosphere,
   DirectionalLight,
@@ -92,11 +92,7 @@ import type {
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types';
 import { ensureGlyphMeshMaterialSlots } from './glyph-text-layout-system';
-import {
-  InstanceCollectionError,
-  type InstanceCollectionId,
-  type InstanceCollectionStore,
-} from './instances';
+import { type InstanceProjectionStore, validateInstanceTransforms } from './instances';
 import { deriveInstancesUnionBounds } from './instances-derived-bounds';
 import {
   type MeshMaterialBindingDiagnostic,
@@ -187,7 +183,7 @@ import {
 } from './render-system-extract';
 import { buildShadowFrusta } from './scene/shadow-visibility';
 import { SHADOW_ATLAS_DEFAULT_LAYERS } from './shadow-atlas';
-import type { SkinPaletteReceipt } from './systems/skin-palette-types';
+import type { SkinPaletteReceipt, SkinPose } from './systems/skin-palette-types';
 
 function skinPaletteIdentity(world: World, entity: number): string {
   return `skin:${world.identity}:${entity}`;
@@ -234,11 +230,12 @@ export function extractFrames(
       request?: {
         readonly vertexColorAvailable?: boolean;
         readonly deformation?: 'rigid' | 'skin';
+        readonly variantSet?: string;
         readonly pass?: 'forward' | 'shadow' | 'depth';
         readonly address?: 'direct' | 'scene-index';
       },
     ) => MaterialShaderArtifact | undefined;
-    readonly instanceCollections?: InstanceCollectionStore;
+    readonly instanceCollections?: InstanceProjectionStore;
   } = {},
 ): ExtractedFrame {
   // w4: normalize the owner argument. A bare number is the legacy single-owner
@@ -569,6 +566,7 @@ export function extractFrames(
   };
 
   const volumetricFog = resourceOwnerFrame?.volumetricFog;
+  const cloudLayer = resourceOwnerFrame?.cloudLayer;
   const skylight = resourceOwnerFrame?.skylight;
   const skylightCount = resourceOwnerFrame?.skylightCount ?? 0;
   const skybox = resourceOwnerFrame?.skybox;
@@ -651,6 +649,7 @@ export function extractFrames(
     ...(volumetricFog === undefined
       ? {}
       : { volumetricFog: { ...volumetricFog, worldId: resourceOwner } }),
+    ...(cloudLayer === undefined ? {} : { cloudLayer }),
     renderables,
     dispatch: dispatchEntries,
     shadowCasterEntityKeys,
@@ -795,6 +794,16 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // calls survive untouched, only the entity source changes).
   const worldInternal = createWorldInternalView(world);
   let volumetricFog = extractVolumeSnapshot(world, assets, worldInternal);
+  let cloudLayer: ExtractedCloudLayer | undefined;
+  const extractedCloudLayer = extractCloudLayer(world);
+  if (extractedCloudLayer.ok) {
+    cloudLayer = extractedCloudLayer.value;
+  } else {
+    worldInternal._routeError(extractedCloudLayer.error, {
+      severity: Severity.Error,
+      systemName: 'RenderSystem.extract (cloud-layer)',
+    });
+  }
 
   const cameraRoles = selectCameraRoles(world, context.cameraEntityKey);
   const cameras = [...cameraRoles.display];
@@ -1708,13 +1717,6 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // extraction. Shared handles are immutable inputs for the frame, while
   // dispatch entries still need to be rebuilt for each entity.
   const materialSnapshotCache: MaterialSnapshotCache = new Map();
-  // A collection can be associated with more than one entity. Snapshot its
-  // renderer-owned bytes once per extracted frame so culling and every
-  // submission lane consume the same detached revision without repeat copies.
-  const instanceSnapshotCache = new Map<
-    InstanceCollectionId,
-    ReturnType<InstanceCollectionStore['snapshot']>
-  >();
   const skinnedMaterialSnapshotCache: MaterialSnapshotCache = new Map();
   // tweak-20260611 M1: MeshRenderer renderable archetype walk routes
   // through one World-owned Query. K-2 sniffing scheme B
@@ -1779,22 +1781,25 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   const flushPendingDispatch = (pending: readonly DispatchEntry[]): void => {
     for (const entry of pending) dispatch.push(entry);
   };
-  for (const row of meshRendererQuery) {
-    if (
-      context.renderables === 'full' &&
-      renderableEntities !== undefined &&
-      !renderableEntities.has(row.entity)
-    ) {
-      continue;
-    }
+  const requestedRows =
+    renderableEntities === undefined
+      ? meshRendererQuery
+      : {
+          *[Symbol.iterator]() {
+            for (const entity of renderableEntities) {
+              const row = meshRendererQuery.at(entity as EntityHandle);
+              if (row !== undefined) yield row;
+            }
+          },
+        };
+  for (const row of requestedRows) {
     // K-2 archetype-edge sniff (scheme B): a missing optional component
     // surfaces as an absent bundle key, not a row-internal optional chain.
     // Presence-only checks use QueryRow.has so large array-bearing components
     // are not materialised merely to answer a boolean question.
     const hasTransform = row.has(Transform);
     const meshFilter = row.get(MeshFilter);
-    const instancesData = row.get(Instances);
-    const hasInstances = instancesData !== undefined;
+    const hasInstances = row.has(Instances);
     const skin = row.get(Skin);
     const morphWeightsView = worldInternal._getArrayView(row.entity, MorphWeights, 'weights');
     const hasMeshFilter = meshFilter !== undefined;
@@ -2574,6 +2579,16 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               baseColor,
               metallic: metallicPv,
               roughness: roughnessPv,
+              ...(resolved.surface?.model === undefined
+                ? {}
+                : { surfaceModel: resolved.surface.model }),
+              deferredPass: allPasses.some(
+                (pass) =>
+                  String(
+                    (pass.renderState?.tags as Record<string, unknown> | undefined)?.LightMode ??
+                      pass.name,
+                  ) === 'Deferred',
+              ),
               ...(specularColorPv !== undefined && {
                 specularColor: [
                   specularColorPv[0] ?? 1,
@@ -2724,6 +2739,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         // resolve / validate / write chain (D-9 reset already fired at
         // extractFrame entry; per-entity allocate + writeJointPalette here).
         let skinSlice: SkinPaletteReceipt | undefined;
+        let skinPose: SkinPose | undefined;
         const skinIdentity = hasSkin ? skinPaletteIdentity(world, entity) : undefined;
         const releaseSkinIdentity = (): void => {
           if (skinIdentity !== undefined) {
@@ -2835,6 +2851,17 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               });
               skinPaletteAllocator.writePersistentJointPalette(receipt, ibms, jointWorlds);
               skinSlice = receipt;
+            } else {
+              skinPose = {
+                identity: skinPaletteIdentity(world, entity),
+                generation: ((skeletonHandleRaw >>> 0) ^ skeleton.jointCount) >>> 0,
+                jointCount: skeleton.jointCount,
+                ...(hasFiniteOrderedLocalAabb(skeleton.bounds)
+                  ? { bounds: new Float32Array(skeleton.bounds) }
+                  : {}),
+                inverseBindMatrices: ibms,
+                jointWorlds,
+              };
             }
           }
         }
@@ -2843,7 +2870,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         // projection. Do not publish a renderable or its staged dispatch when
         // palette extraction was unavailable; the record stage must never
         // reinterpret a skinned vertex stream through an ordinary mesh group.
-        if (skinSlice === undefined && hasSkin) {
+        if (skinSlice === undefined && skinPose === undefined && hasSkin) {
           releaseSkinIdentity();
           if (
             materialSnap.materialShaderId === 'forgeax::pbr-skin' ||
@@ -3073,49 +3100,29 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         // make the cull and draw disagree within one frame).
         let instancesSnap: InstancesSnapshot | undefined;
         if (hasInstances) {
-          const collectionId = instancesData?.collectionId as InstanceCollectionId | undefined;
-          let collectionResult =
-            collectionId !== undefined ? instanceSnapshotCache.get(collectionId) : undefined;
-          if (collectionResult === undefined) {
-            collectionResult =
-              collectionId !== undefined && collectionId > 0 && instanceCollections !== undefined
-                ? instanceCollections.snapshot(collectionId)
-                : err(
-                    new InstanceCollectionError(
-                      'instance-collection-invalid',
-                      'Instances.collectionId references a live renderer-owned collection',
-                      'create the collection through renderer.instances before attaching Instances',
-                      {
-                        operation: 'inspect',
-                        expected: 'a positive collectionId with a live renderer owner',
-                        actual: Number(collectionId ?? 0),
-                        ...(collectionId === undefined ? {} : { collectionId }),
-                      },
-                    ),
-                  );
-            if (collectionId !== undefined)
-              instanceSnapshotCache.set(collectionId, collectionResult);
-          }
-          if (collectionResult === undefined) continue;
-          if (!collectionResult.ok) {
-            worldInternal._routeError(collectionResult.error, {
+          const transforms =
+            worldInternal._getArrayView(entity, Instances, 'transforms') ?? new Float32Array();
+          const invalid = validateInstanceTransforms(transforms);
+          if (invalid !== undefined) {
+            worldInternal._routeError(invalid, {
               severity: Severity.Error,
-              systemName: 'RenderSystem.extract (Instances collection)',
+              systemName: 'RenderSystem.extract (Instances transforms)',
             });
             continue;
           }
+          const projected = instanceCollections?.project(world, entity, transforms);
           instancesSnap = {
-            transforms: collectionResult.value.transforms,
-            generations: collectionResult.value.generations,
-            instanceCount: collectionResult.value.count,
-            collectionId: collectionResult.value.collectionId,
-            revision: collectionResult.value.revision,
-            capacity: collectionResult.value.capacity,
-            dirtyRanges: collectionResult.value.dirtyRanges,
+            transforms: projected?.transforms ?? new Float32Array(transforms),
+            instanceCount: transforms.length / 16,
             cacheKey: entity,
-            // Explicit collection revisions supersede ECS archetype content
-            // hashes; retain zero as the legacy sprite-only field value.
-            archVersion: 0,
+            archVersion: projected === undefined ? archVersion : 0,
+            ...(projected === undefined
+              ? {}
+              : {
+                  collectionId: projected.collectionId,
+                  revision: projected.revision,
+                  generations: projected.generations,
+                }),
           };
         }
 
@@ -3133,6 +3140,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           entityKey: entity,
           ...(authorVisible ? {} : { authorVisible: false }),
           ...(skinSlice !== undefined ? { skin: skinSlice } : {}),
+          ...(skinPose === undefined ? {} : { skinPose }),
           ...(skin?.joints === undefined
             ? {}
             : { skinJointEntities: Array.from(skin.joints, (joint) => Number(joint)) }),
@@ -3141,21 +3149,24 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           ...(spriteInstancesSnap !== undefined ? { spriteInstances: spriteInstancesSnap } : {}),
           ...(pointsLines !== undefined ? { pointsLines } : {}),
         };
-        const gpuDrivenDraws = buildGpuDrivenDraws({
-          mesh: gpuDrivenMesh,
-          materials: materialsArr,
-          fallbackMaterial: materialSnap,
-          baseSnapshot: baseRenderable,
-          ...(getMaterialShaderArtifact === undefined ? {} : { getMaterialShaderArtifact }),
-          ...(lods === undefined
-            ? {}
-            : {
-                lodMeshes: lods.map((lod) => {
-                  const lower = assets?.lookup<Asset>(lod.mesh);
-                  return lower?.kind === 'mesh' ? lower : undefined;
-                }),
-              }),
-        });
+        const gpuDrivenDraws =
+          skinPose === undefined
+            ? buildGpuDrivenDraws({
+                mesh: gpuDrivenMesh,
+                materials: materialsArr,
+                fallbackMaterial: materialSnap,
+                baseSnapshot: baseRenderable,
+                ...(getMaterialShaderArtifact === undefined ? {} : { getMaterialShaderArtifact }),
+                ...(lods === undefined
+                  ? {}
+                  : {
+                      lodMeshes: lods.map((lod) => {
+                        const lower = assets?.lookup<Asset>(lod.mesh);
+                        return lower?.kind === 'mesh' ? lower : undefined;
+                      }),
+                    }),
+              })
+            : [];
         for (const draw of gpuDrivenDraws) {
           if (draw.preparationError === undefined) continue;
           worldInternal._routeError(draw.preparationError, {
@@ -3391,6 +3402,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     environment,
     environmentReady: true,
     ...(volumetricFog === undefined ? {} : { volumetricFog }),
+    ...(cloudLayer === undefined ? {} : { cloudLayer }),
     renderables,
     dispatch,
     shadowCasterEntityKeys,

package/src/render-system-extract.ts

@@ -78,18 +78,11 @@ import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-c
 //                               non-renderable state and is skipped
 //                               (charter proposition 5; AC-11).
 //
-// Renderer-owned Large Instances:
-//   `Instances { collectionId }` is an ECS association to the renderer's
-//   `InstanceCollectionStore`, not an ECS transform-array column. The extract
-//   tail resolves the identity against that store and snapshots canonical
-//   transforms together with collection revision, capacity, dirty ranges,
-//   and residency facts. Invalid or stale associations route the existing
-//   typed `InstanceCollectionError` through the World error boundary; the
-//   record stage owns GPU residency and upload decisions.
-//
-// `SpriteInstances` remains the separate ECS-owned array-view path. Its
-// snapshot is intentionally independent from renderer-owned Large Instances,
-// so the extract stage does not duplicate collection storage or GPU policy.
+// World owns Instances.transforms. Extraction borrows the managed array during
+// the read phase and retains a detached projection only when its values change.
+// RenderScene accepts that projection with the source publication; recording
+// owns device residency, upload revisions and backend-specific chunking.
+// SpriteInstances remains the independent 2D component and snapshot contract.
 
 import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import {
@@ -127,6 +120,7 @@ import type {
   MaterialPass,
   MaterialProgramAbi,
   MaterialRenderState,
+  MaterialSurfaceModel,
   MaterialTextureCoordinates,
   MaterialTextureValue,
   MeshLodLevel,
@@ -142,6 +136,7 @@ import {
 import { buildCubeCameraFaceViews } from './capture/cube-views';
 import {
   antialiasFromF32,
+  BarrelDistortion,
   CAMERA_EXPOSURE_MODE_MANUAL,
   Camera,
   CubeCamera,
@@ -159,6 +154,7 @@ import {
   validateCameraBloom,
   validateDynamicResolutionCamera,
 } from './components';
+import { validateBarrelDistortionParameters } from './components/barrel-distortion';
 import { DepthOfField } from './components/depth-of-field';
 import type { DirectionalShadowQuality } from './components/directional-shadow-filter';
 import type { LightValidationError } from './components/light-helpers';
@@ -185,7 +181,7 @@ import type {
   RenderFeatureHiddenEntityReport,
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types';
-import type { InstanceCollectionId, InstanceCollectionStore } from './instances';
+import type { InstanceCollectionId, InstanceProjectionStore } from './instances';
 import type {
   MeshMaterialBindingDiagnostic,
   MeshMaterialBindingSource,
@@ -658,15 +654,16 @@ export interface SkyboxSnapshot {
 }
 
 /**
- * Resource-owner projection for the single ECS VolumetricFog singleton.
+ * Resource-owner projection for an ECS VolumetricFog collection.
  *
  * The renderer carries the validated authoring facts and the source POD all
  * the way to the record stage.  No profile flag or source/catalog byte is
  * allowed to enable the graph: `status: 'available'` is produced only after
  * the ECS component, its shared TextureAsset, and the volume validator all
- * agree on one linear 3D density owner.
+ * agree on every linear 3D density owner.
  */
 export interface ExtractedVolumetricFog {
+  readonly additional?: readonly ExtractedVolumetricFog[];
   readonly status: 'off' | 'available' | 'degraded';
   readonly fog?: ValidatedVolumetricFog;
   readonly densityHandle?: Handle<'TextureAsset', 'shared'>;
@@ -795,6 +792,8 @@ export interface RenderableSnapshot {
    * Absent (`undefined`) means the entity is not skinned.
    */
   readonly skin?: SkinPaletteReceipt;
+  /** Source pose waiting for the receiving Renderer to assign a palette. */
+  readonly skinPose?: import('./systems/skin-palette-types').SkinPose;
   /** Joint identities consumed by the retained scene dependency index. */
   readonly skinJointEntities?: readonly number[];
   /** Source pass ownership retained with the scene record across view changes. */
@@ -857,8 +856,6 @@ export interface InstancesSnapshot {
   readonly instanceCount: number;
   /** Collection revision captured by this detached frame snapshot. */
   readonly revision?: number;
-  /** Logical collection capacity at snapshot time. */
-  readonly capacity?: number;
   /** Coalesced matrix ordinals dirtied since the previous authoring update. */
   readonly dirtyRanges?: readonly {
     readonly start: number;
@@ -944,6 +941,10 @@ export interface MaterialSnapshot {
   readonly baseColor: Vec3;
   readonly metallic: number;
   readonly roughness: number;
+  /** Root-owned Surface model used only for typed pass routing. */
+  readonly surfaceModel?: MaterialSurfaceModel | undefined;
+  /** Whether this material publishes a Deferred pass consumed before the forward-only lane. */
+  readonly deferredPass?: boolean | undefined;
   /** Authored Standard PBR specular color in linear runtime color space. */
   readonly specularColor?: readonly [number, number, number] | undefined;
   /**
@@ -1243,6 +1244,8 @@ export interface ExtractedFrame {
   readonly environmentReady: boolean;
   /** One resource-owner volume projection; absent means no authored fog. */
   readonly volumetricFog?: ExtractedVolumetricFog;
+  /** Resource-owner CloudLayer facts selected once at the extract boundary. */
+  readonly cloudLayer?: import('./cloud/extract').ExtractedCloudLayer;
   readonly renderables: RenderableSnapshot[];
   /**
    * Single dispatch list sorted by queue value (ascending, stable sort).
@@ -2459,6 +2462,13 @@ export function resolveMaterialSnapshot(
     baseColor,
     metallic: metallicPv,
     roughness: roughnessPv,
+    ...(resolved.surface?.model === undefined ? {} : { surfaceModel: resolved.surface.model }),
+    deferredPass: allPasses.some(
+      (pass) =>
+        String(
+          (pass.renderState?.tags as Record<string, unknown> | undefined)?.LightMode ?? pass.name,
+        ) === 'Deferred',
+    ),
     ...(specularColorPv !== undefined && {
       specularColor: [
         specularColorPv[0] ?? 1,
@@ -2981,13 +2991,14 @@ export interface PreparedExtractContext {
         request?: {
           readonly vertexColorAvailable?: boolean;
           readonly deformation?: 'rigid' | 'skin';
+          readonly variantSet?: string;
           readonly pass?: 'forward' | 'shadow' | 'depth';
           readonly address?: 'direct' | 'scene-index';
         },
       ) => MaterialShaderArtifact | undefined)
     | undefined;
-  /** Renderer-owned canonical source for explicit large instance collections. */
-  readonly instanceCollections: InstanceCollectionStore | undefined;
+  /** Renderer-private projection of World-authored instance matrices. */
+  readonly instanceCollections: InstanceProjectionStore | undefined;
 }
 
 const ALL_VISIBLE: VisibilitySnapshot = {
@@ -3004,13 +3015,20 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
   const cameraQuery = world
     .query({
       read: [Camera],
-      optional: [MotionBlur, DynamicResolution, ScreenSpaceReflection, DepthOfField],
+      optional: [
+        MotionBlur,
+        DynamicResolution,
+        ScreenSpaceReflection,
+        DepthOfField,
+        BarrelDistortion,
+      ],
       with: [Transform, GlobalTransform],
     })
     .unwrap();
   for (const row of cameraQuery) {
     const cam = row.get(Camera);
     const motionBlur = row.get(MotionBlur);
+    const barrelDistortion = row.get(BarrelDistortion);
     const motionBlurResult = resolveMotionBlurParams(motionBlur);
     if (!motionBlurResult.ok) throw motionBlurResult.error;
     const motionBlurParams = motionBlurResult.value;
@@ -3051,6 +3069,8 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
     const antialias = antialiasFromF32(cam.antialias);
     const dynamicResolutionResult = validateDynamicResolutionCamera(dynamicResolution, antialias);
     if (!dynamicResolutionResult.ok) throw dynamicResolutionResult.error;
+    const barrelDistortionResult = validateBarrelDistortionParameters(barrelDistortion);
+    if (!barrelDistortionResult.ok) throw barrelDistortionResult.error;
     cameras.push({
       entityKey: entity as number,
       ...(target === undefined ? {} : { target }),
@@ -3105,6 +3125,7 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
               targetFps: motionBlurParams.targetFps,
             },
           }),
+      ...(barrelDistortion === undefined ? {} : { barrelDistortion: barrelDistortionResult.value }),
       ...(screenSpaceReflection === undefined
         ? {}
         : {
@@ -3257,11 +3278,12 @@ export function prepareExtractContext(
       request?: {
         readonly vertexColorAvailable?: boolean;
         readonly deformation?: 'rigid' | 'skin';
+        readonly variantSet?: string;
         readonly pass?: 'forward' | 'shadow' | 'depth';
         readonly address?: 'direct' | 'scene-index';
       },
     ) => MaterialShaderArtifact | undefined;
-    readonly instanceCollections?: InstanceCollectionStore;
+    readonly instanceCollections?: InstanceProjectionStore;
   } = {},
 ): PreparedExtractContext {
   const renderables = options.renderables ?? 'full';
@@ -3364,6 +3386,7 @@ export function extractVolumeSnapshot(
   const worldTimeSeconds = Number.isFinite(elapsed) ? Math.max(0, elapsed) : 0;
   const query = world.query({ read: [VolumetricFog] }).unwrap();
   const authorings: VolumetricFogAuthoring[] = [];
+  const members: ExtractedVolumetricFog[] = [];
   let selectedLight:
     | {
         readonly entity: EntityHandle;
@@ -3372,15 +3395,9 @@ export function extractVolumeSnapshot(
         readonly spotLightEntity?: EntityHandle;
       }
     | undefined;
-  let first:
-    | {
-        readonly densityHandle: Handle<'TextureAsset', 'shared'>;
-        readonly densityAsset: TextureAsset;
-        readonly guid: string;
-      }
-    | undefined;
 
   for (const row of query) {
+    selectedLight = undefined;
     const source = row.get(VolumetricFog);
     if (source.light === null) continue;
     const selected = resolveSelectedVolumetricLight(world, source.light);
@@ -3457,9 +3474,30 @@ export function extractVolumeSnapshot(
       emission: [source.emission[0] ?? 0, source.emission[1] ?? 0, source.emission[2] ?? 0],
       anisotropy: source.anisotropy,
       maxDistance: source.maxDistance,
+      sampling: source.sampling === 1 ? 'density' : 'noise',
     };
     authorings.push(authoring);
-    first ??= { densityHandle, densityAsset, guid };
+    members.push({
+      status: 'available',
+      worldTimeSeconds,
+      densityHandle,
+      densityAsset,
+      guid,
+      generation: 1,
+      digest: textureDigest(densityAsset),
+      ...(selectedLight === undefined
+        ? {}
+        : {
+            lightEntity: selectedLight.entity,
+            lightKind: selectedLight.kind,
+            ...(selectedLight.pointLightEntity === undefined
+              ? {}
+              : { pointLightEntity: selectedLight.pointLightEntity }),
+            ...(selectedLight.spotLightEntity === undefined
+              ? {}
+              : { spotLightEntity: selectedLight.spotLightEntity }),
+          }),
+    });
   }
 
   if (authorings.length === 0) return undefined;
@@ -3469,56 +3507,18 @@ export function extractVolumeSnapshot(
       severity: Severity.Error,
       systemName: 'RenderSystem.extract (volumetric-fog)',
     });
-    return {
-      status: 'degraded',
-      worldTimeSeconds,
-      ...(first === undefined
-        ? {}
-        : {
-            densityHandle: first.densityHandle,
-            densityAsset: first.densityAsset,
-            guid: first.guid,
-            generation: 1,
-            digest: textureDigest(first.densityAsset),
-            ...(selectedLight === undefined
-              ? {}
-              : {
-                  lightEntity: selectedLight.entity,
-                  lightKind: selectedLight.kind,
-                  ...(selectedLight.pointLightEntity === undefined
-                    ? {}
-                    : { pointLightEntity: selectedLight.pointLightEntity }),
-                  ...(selectedLight.spotLightEntity === undefined
-                    ? {}
-                    : { spotLightEntity: selectedLight.spotLightEntity }),
-                }),
-          }),
-    };
+    return { ...members[0], status: 'degraded' };
   }
-  if (extracted.value.status === 'off' || first === undefined) return { status: 'off' };
-  const selectedLightFields =
-    selectedLight === undefined
-      ? {}
-      : {
-          lightEntity: selectedLight.entity,
-          lightKind: selectedLight.kind,
-          ...(selectedLight.pointLightEntity === undefined
-            ? {}
-            : { pointLightEntity: selectedLight.pointLightEntity }),
-          ...(selectedLight.spotLightEntity === undefined
-            ? {}
-            : { spotLightEntity: selectedLight.spotLightEntity }),
-        };
+  if (extracted.value.status === 'off') return { status: 'off' };
+  const validatedMembers = extracted.value.fogs.map((fog, index) => ({
+    ...members[index],
+    status: 'available' as const,
+    fog,
+  }));
   return {
     status: 'available',
-    worldTimeSeconds,
-    fog: extracted.value.fog,
-    densityHandle: first.densityHandle,
-    densityAsset: first.densityAsset,
-    guid: first.guid,
-    generation: 1,
-    digest: textureDigest(first.densityAsset),
-    ...selectedLightFields,
+    ...validatedMembers[0],
+    additional: validatedMembers.slice(1),
   };
 }
 

package/src/render-system-presentation.ts

@@ -0,0 +1,56 @@
+import type { RenderResourceScope } from './publication/resource-scope';
+import type { RenderSystemInternals } from './record/render-context';
+import type { FramePresentation } from './render-contract';
+import type { DispatchEntry, RenderableSnapshot } from './render-system-extract';
+import { observeMaterialResidency } from './render-system-residency';
+
+export interface FramePresentationProjection {
+  readonly renderables: readonly RenderableSnapshot[];
+  readonly presentation: FramePresentation;
+}
+
+/**
+ * Derive the startup presentation candidate from the current display workset.
+ * Shadow-only retained rows are deliberately excluded, while material facts
+ * still come from the producer-owned residency projection.
+ */
+export function projectFramePresentation(input: {
+  readonly hasCamera: boolean;
+  readonly environmentReady: boolean;
+  readonly hasEnvironment: boolean;
+  readonly submissionRenderables: readonly RenderableSnapshot[];
+  readonly submissionDispatch: readonly DispatchEntry[];
+  readonly preparedWorlds: readonly RenderResourceScope[];
+  readonly internals: RenderSystemInternals;
+}): FramePresentationProjection {
+  const displayRenderableIndices = new Set<number>();
+  for (const entry of input.submissionDispatch) {
+    if (entry.renderableIndex === undefined) continue;
+    if (entry.tags.LightMode !== 'ShadowCaster')
+      displayRenderableIndices.add(entry.renderableIndex);
+  }
+  const renderables = input.submissionRenderables.filter(
+    (_, index) =>
+      displayRenderableIndices.has(index) &&
+      input.submissionRenderables[index]?.authorVisible !== false,
+  );
+
+  let presentation: FramePresentation = 'ready';
+  if (input.hasCamera && (!input.environmentReady || !input.hasEnvironment)) {
+    presentation = 'pending';
+  } else if (input.hasCamera) {
+    for (const renderable of renderables) {
+      const materialWorld = input.preparedWorlds[renderable.worldId];
+      for (const material of renderable.materials) {
+        if (
+          observeMaterialResidency(materialWorld, material, input.internals).readiness === 'pending'
+        ) {
+          presentation = 'pending';
+          break;
+        }
+      }
+      if (presentation === 'pending') break;
+    }
+  }
+  return { renderables, presentation };
+}