@forgeax/engine-render 0.1.19 → 0.1.21

package/src/render-system-extract.ts

@@ -142,6 +142,7 @@ import type {
   ParamSchemaEntry,
   PrimitiveTopology,
   SkeletonAsset,
+  TextureAsset,
 } from '@forgeax/engine-types';
 import {
   ASSET_ERROR_HINTS,
@@ -153,6 +154,12 @@ import {
 } from '@forgeax/engine-types';
 import {
   Atmosphere,
+  antialiasFromF32,
+  bloomEnabledFromF32,
+  Camera,
+  CubeCamera,
+  cameraProjectionFromF32,
+  cubeCameraUpdateIntentFromF32,
   DirectionalLight,
   Fog,
   Instances,
@@ -160,33 +167,50 @@ import {
   Lines,
   MeshFilter,
   MeshRenderer,
+  MotionBlur,
   PointLight,
   PointLightShadow,
   Points,
   PostProcessParams,
   pointShapeFromU32,
+  ReflectionProbe,
+  reflectionProbeUpdateIntentFromF32,
   SkyboxBackground,
   Skylight,
   SortKey,
   SpotLight,
   SpriteInstances,
   SpriteRegionOverride,
+  tonemapFromF32,
   tonemapToU32,
 } from './components';
+import {
+  type DirectionalShadowQuality,
+  directionalShadowQualityFromF32,
+} from './components/directional-shadow-filter';
 import { GlyphText } from './components/glyph-text';
-import { computeInvRangeSquared, degToCos } from './components/light-helpers';
+import {
+  computeInvRangeSquared,
+  degToCos,
+  type LightValidationError,
+  validateDirectionalLightData,
+} from './components/light-helpers';
 import { selectEnvironment } from './environment/frame';
 import {
   MaterialSkinAttrMissingError,
   ShadowInvalidConfigError,
   SkinMaterialMismatchError,
 } from './errors/render';
-import { extractCameraSnapshots } from './extract/camera';
+import {
+  type DirectionalShadowCascadeFit,
+  projectDirectionalShadow,
+} from './extract/directional-shadow-projection';
 import type {
   EnvironmentCandidate,
   EnvironmentFrame,
   FogCandidate,
   FogFrame,
+  FogSelectionFailure,
 } from './extract/environment';
 import { resolveVisibility, type VisibilitySnapshot } from './extract/visibility';
 import type {
@@ -194,6 +218,7 @@ import type {
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types';
 import { ensureGlyphMeshMaterialSlots } from './glyph-text-layout-system';
+import { deriveInstancesUnionBounds } from './instances-derived-bounds';
 import {
   type MeshMaterialBindingDiagnostic,
   type MeshMaterialBindingSource,
@@ -202,13 +227,29 @@ import {
 import { isStandardPbrMaterialShader } from './pbr-pipeline';
 import { expandPointsLinesBounds } from './points-lines/bounds';
 import type { PointsLinesRetainedSnapshot, PointsLinesStyle } from './points-lines/snapshot';
-import { type CameraSnapshot, STANDARD_OUTPUT_TRANSFORM_FEATURE_ID } from './render-contract';
+import type { ReflectionProbeFact } from './reflection/projection';
+import {
+  type CameraSnapshot,
+  type CubeCameraSnapshot,
+  STANDARD_OUTPUT_TRANSFORM_FEATURE_ID,
+} from './render-contract';
+import { SHADOW_ATLAS_DEFAULT_LAYERS } from './shadow-atlas';
+import { getActiveCamera, selectActiveCameraIndex } from './systems/active-camera';
 import { selectPasses } from './systems/pass-selector';
 
-export { extractCameraSnapshots } from './extract/camera';
-
 import type { SkinPaletteAllocator } from './systems/skin-palette-allocator';
 import type { SkinPaletteSlice } from './systems/skin-palette-types';
+import type { RenderTarget, RenderTargetTextureSource } from './targets/contracts';
+import { resolveRenderTargetMaterialSource } from './targets/material-source';
+import { resolveSelectedVolumetricLight } from './volume/capability';
+import {
+  type ValidatedVolumetricFog,
+  type VolumeDensityBinding,
+  VolumetricFog,
+  type VolumetricFogAuthoring,
+} from './volume/component';
+import { extractVolumetricFog } from './volume/extract';
+import type { VolumeProjectorTuple } from './volume/temporal';
 
 /**
  * DirectionalLightSnapshot — sun-like infinite light variant of the
@@ -221,6 +262,7 @@ import type { SkinPaletteSlice } from './systems/skin-palette-types';
  */
 export interface DirectionalLightSnapshot {
   readonly kind: 'directional';
+  readonly entity?: EntityHandle;
   readonly direction: Vec3;
   readonly color: Vec3;
   readonly intensity: number;
@@ -234,14 +276,16 @@ export interface DirectionalLightSnapshot {
  */
 export interface PointLightSnapshot {
   readonly kind: 'point';
+  readonly entity?: EntityHandle | number;
   readonly position: Vec3;
   readonly color: Vec3;
   readonly intensity: number;
   readonly invRangeSquared: number;
   /**
    * feat-20260612-point-light-shadows-urp-hdrp M1 / T-M1-8 + M4 / T-M4-4:
-   * cube_array atlas layer index for this light's shadow map (0..3 for shadow
-   * casters; sentinel `-1` for non-shadow lights). Default `-1` per
+   * cube_array atlas layer index for this light's shadow map (0..capacity-1
+   * for admitted shadow casters; sentinel `-1` for non-admitted lights).
+   * Default `-1` per
    * plan-strategy §D-2 — record stage / shader skips shadow sampling when the
    * lane equals the sentinel. Joined with `pointShadow[]` by entity at the
    * end of extract; HDRP record stage threads `shadowAtlasLayer + shadowNear +
@@ -278,8 +322,9 @@ export interface PointLightSnapshot {
  *
  * `mapSize` / `nearPlane` / `farPlane` ride here so record stage can size the
  * cube atlas faces and feed shader the proj constants without re-querying ECS.
- * `shadowAtlasLayer` is assigned by extract in spawn order (0 .. cap-1) so the
- * downstream LightSlot / packPointLight packers carry the layer index in
+ * `shadowAtlasLayer` is assigned by extract in spawn order up to the renderer
+ * atlas capacity; over-budget requests retain the sentinel `-1` so the
+ * downstream LightSlot / packPointLight packers carry no invalid layer in
  * pointPadW (T-M1-8 will rename to shadowAtlasLayer).
  */
 export interface PointShadowSnapshot {
@@ -292,9 +337,9 @@ export interface PointShadowSnapshot {
   readonly nearPlane: number;
   readonly farPlane: number;
   /**
-   * Atlas layer assigned by extract in spawn order (0..cap-1, where cap=4
-   * matches PointLightShadow cardinality). Sentinel -1 is reserved by the
-   * shader-side LightSlot for no-shadow lights (T-M1-8).
+   * Atlas layer assigned by extract in spawn order while capacity remains.
+   * Sentinel -1 is used for a request that cannot be admitted and is
+   * reserved by the shader-side LightSlot for no-shadow lights (T-M1-8).
    */
   readonly shadowAtlasLayer: number;
   /**
@@ -317,10 +362,15 @@ export interface PointShadowSnapshot {
  * is false, dir degenerates, or the light is clipped). shadowAtlasTile
  * (i32 sentinel -1) is the allocated tile index 0..3 or -1 for unassigned
  * (plan-strategy D-4). mapSize / nearPlane / farPlane are the source
- * component shadow parameters carried through to the record stage.
+ * component shadow parameters carried through to the record stage. The
+ * author-facing `shadowIntensity` remains in [0,1] and is copied unchanged;
+ * shader consumers apply it only to shadow visibility, never to candela
+ * radiance.
  */
 export interface SpotLightSnapshot {
   readonly kind: 'spot';
+  /** Entity identity is branded in extracted frames; numeric fixtures remain compatible. */
+  readonly entity?: EntityHandle | number;
   readonly position: Vec3;
   readonly direction: Vec3;
   readonly color: Vec3;
@@ -335,6 +385,17 @@ export interface SpotLightSnapshot {
   readonly nearPlane: number;
   readonly farPlane: number;
   readonly shadowAtlasTile: number;
+  /** Fraction of sampled shadow visibility to retain; 1 = fully opaque shadow. */
+  readonly shadowIntensity?: number;
+  readonly depthBias?: number;
+  readonly normalBias?: number;
+  readonly pcfKernelSize?: number;
+  /** Authoritative TextureAsset projector resolved from the SpotLight handle. */
+  readonly projectorHandle?: Handle<'TextureAsset', 'shared'>;
+  readonly projectorAsset?: TextureAsset;
+  readonly projectorGuid?: string;
+  readonly projectorGeneration?: number;
+  readonly projectorRevision?: number;
 }
 
 /**
@@ -376,6 +437,7 @@ export interface ExtractedLights {
    * unused slots are 0.0f. Undefined when castShadow=false or no directional
    * light.
    */
+  /** Four vec4 lanes: split, worldUnitsPerTexel, lightDepthWorldSpan, reserved. */
   readonly splitPlanes: Float32Array | undefined;
   /**
    * feat-20260613-csm-cascaded-shadow-maps M2 / w9: effective cascade count
@@ -411,13 +473,10 @@ export interface ExtractedLights {
    * undefined otherwise.
    */
   readonly normalBias: number | undefined;
-  /**
-   * feat-20260621-merge-directionallightshadow-into-directionallight M2:
-   * pcfKernelSize from the merged DirectionalLight (PCF kernel width, odd>=1).
-   * Populated when castShadow=true on the first-hit directional light;
-   * undefined otherwise.
-   */
-  readonly pcfKernelSize: number | undefined;
+  /** Accepted closed Directional filter projected from the first query result. */
+  readonly directionalShadowQuality: DirectionalShadowQuality | undefined;
+  /** Structured author-config failure; the candidate is withheld from record. */
+  readonly directionalShadowError: LightValidationError | undefined;
   /**
    * feat-20260612-point-light-shadows-urp-hdrp M1 / T-M1-7:
    * shadow-casting point lights (PointLight + PointLightShadow + Transform
@@ -505,6 +564,37 @@ export interface SkyboxSnapshot {
   readonly entityHandle: number;
 }
 
+/**
+ * Resource-owner projection for the single ECS VolumetricFog singleton.
+ *
+ * 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.
+ */
+export interface ExtractedVolumetricFog {
+  readonly status: 'off' | 'available' | 'degraded';
+  readonly fog?: ValidatedVolumetricFog;
+  readonly densityHandle?: Handle<'TextureAsset', 'shared'>;
+  readonly densityAsset?: TextureAsset;
+  readonly guid?: string;
+  readonly generation?: number;
+  readonly digest?: string;
+  readonly worldId?: number;
+  /** Required same-World light selected by the authoring component. */
+  readonly lightEntity?: EntityHandle;
+  readonly lightKind?: 'directional' | 'point' | 'spot';
+  /** Optional Point+Spot pair identities consumed by the volume integrator. */
+  readonly pointLightEntity?: EntityHandle;
+  readonly spotLightEntity?: EntityHandle;
+  /** Accepted projector tuple shared by surface and volume when authored. */
+  readonly projector?: VolumeProjectorTuple;
+  /** The resolved projector payload shared with the surface light snapshot. */
+  readonly projectorHandle?: Handle<'TextureAsset', 'shared'>;
+  readonly projectorAsset?: TextureAsset;
+}
+
 export interface RenderableSnapshot {
   readonly assetHandle: number;
   readonly transform: TransformSnapshot;
@@ -792,6 +882,8 @@ export interface MaterialSnapshot {
    * them in a lightmap injection region.
    */
   readonly textureHandles?: ReadonlyMap<string, Handle<'TextureAsset', 'shared'>> | undefined;
+  /** Renderer-local target sources; never projected as TextureAsset handles. */
+  readonly textureSources?: ReadonlyMap<string, RenderTargetTextureSource> | undefined;
   /**
    * User-region texture field names whose paramValue resolved to a VideoAsset
    * (kind `'video'`) rather than a static TextureAsset
@@ -1001,11 +1093,19 @@ function appendMaterialDispatchEntries(
 
 export interface ExtractedFrame {
   readonly cameras: CameraSnapshot[];
+  /** Auxiliary target cameras selected after the display camera is fixed. */
+  readonly auxiliaryCameras: readonly CameraSnapshot[];
+  /** Cube capture intents extracted beside the display camera in one pass. */
+  readonly cubeCameras: readonly CubeCameraSnapshot[];
+  /** Reflection probe facts projected from the same World extraction. */
+  readonly reflectionProbes?: readonly ReflectionProbeFact[];
   readonly lights: ExtractedLights;
   /** Resource-owner environment facts selected once at the extract boundary. */
   readonly environment: EnvironmentFrame | undefined;
   /** False when the resource-owner world failed environment/fog selection. */
   readonly environmentReady: boolean;
+  /** One resource-owner volume projection; absent means no authored fog. */
+  readonly volumetricFog?: ExtractedVolumetricFog;
   readonly renderables: RenderableSnapshot[];
   /**
    * Single dispatch list sorted by queue value (ascending, stable sort).
@@ -1019,6 +1119,8 @@ export interface ExtractedFrame {
   readonly skyboxCount: number;
   /** Resource-owner Fog facts selected once at the frame boundary. */
   readonly fog: FogFrame | undefined;
+  /** Last invalid Fog update retained alongside the current valid/LKG frame. */
+  readonly fogFailure?: FogSelectionFailure;
   /**
    * feat-20260528-frustum-culling M3 / w11: frustum culling statistics
    * collected during the extract phase. `total` is the count of entities
@@ -1044,6 +1146,65 @@ export interface ExtractedFrame {
   readonly hiddenEntityReports: readonly RenderFeatureHiddenEntityReport[];
 }
 
+export type CameraTargetUpdate = 'once' | 'on-demand' | 'continuous';
+
+export interface CameraTargetCandidate {
+  readonly worldId: number;
+  readonly entityKey: number;
+  readonly target?: RenderTarget;
+  readonly requestVersion: number;
+  readonly update: CameraTargetUpdate;
+}
+
+export interface CameraTargetRejection {
+  readonly entityKey: number;
+  readonly reason: 'budget' | 'display-target' | 'duplicate-target';
+}
+
+export interface CameraTargetSelection {
+  readonly display: CameraTargetCandidate | undefined;
+  readonly auxiliary: readonly CameraTargetCandidate[];
+  readonly rejected: readonly CameraTargetRejection[];
+}
+
+export function selectCameraTargetViews(
+  candidates: readonly CameraTargetCandidate[],
+  options: { readonly displayEntityKey?: number; readonly budget: number },
+): CameraTargetSelection {
+  const display = candidates.find(
+    (candidate) =>
+      candidate.entityKey === options.displayEntityKey && candidate.target === undefined,
+  );
+  const rejected: CameraTargetRejection[] = [];
+  const ordered = candidates
+    .filter((candidate) => candidate.target !== undefined)
+    .sort((left, right) => left.worldId - right.worldId || left.entityKey - right.entityKey);
+  const auxiliary: CameraTargetCandidate[] = [];
+  const seenTargets = new Set<RenderTarget>();
+  for (const candidate of ordered) {
+    const duplicate = candidate.target !== undefined && seenTargets.has(candidate.target);
+    if (candidate.target !== undefined) seenTargets.add(candidate.target);
+    if (candidate.entityKey === options.displayEntityKey) {
+      rejected.push({ entityKey: candidate.entityKey, reason: 'display-target' });
+      continue;
+    }
+    if (candidate.target === undefined || duplicate) {
+      rejected.push({ entityKey: candidate.entityKey, reason: 'duplicate-target' });
+      continue;
+    }
+    if (auxiliary.length >= Math.max(0, options.budget)) {
+      rejected.push({ entityKey: candidate.entityKey, reason: 'budget' });
+      continue;
+    }
+    auxiliary.push(candidate);
+  }
+  return {
+    display,
+    auxiliary: Object.freeze(auxiliary),
+    rejected: Object.freeze(rejected),
+  };
+}
+
 /**
  * Internal world surface used by extract for archetype-graph traversal and
  * error routing. The packed `Entity` handle for a row is read directly from
@@ -1086,6 +1247,14 @@ function createWorldInternalView(world: World): WorldInternalView {
   };
 }
 
+function resolveCameraTarget(world: World, raw: number | undefined): RenderTarget | undefined {
+  if (raw === undefined || raw <= 0) return undefined;
+  const resolved = world.sharedRefs.resolve<'RenderTarget', RenderTarget>(
+    toShared<'RenderTarget'>(Math.round(raw)),
+  );
+  return resolved.ok ? resolved.value : undefined;
+}
+
 /**
  * The user-region texture fields the built-in standard-PBR material declares.
  * Used as the fallback texture-field set when the shader id is not registered
@@ -1366,6 +1535,24 @@ function collectMaterialTextureCoordinates(
   return out;
 }
 
+function collectMaterialTextureSources(
+  values: Readonly<Record<string, unknown>>,
+  world: World,
+): Map<string, RenderTargetTextureSource> {
+  const out = new Map<string, RenderTargetTextureSource>();
+  for (const [field, value] of Object.entries(values)) {
+    const reference = materialTextureRef(value);
+    if (typeof reference !== 'number') continue;
+    const resolved = world.sharedRefs.resolve<
+      'RenderTargetTextureSource',
+      RenderTargetTextureSource
+    >(toShared<'RenderTargetTextureSource'>(reference));
+    if (!resolved.ok || resolveRenderTargetMaterialSource(resolved.value) === undefined) continue;
+    out.set(field, resolved.value);
+  }
+  return out;
+}
+
 function collectMaterialTextureSamplers(
   values: Readonly<Record<string, unknown>>,
   resolveSampler: (value: unknown) => Handle<'SamplerAsset', 'shared'> | undefined,
@@ -1456,9 +1643,14 @@ function materialParametersToParamSchema(
   return parameters.flatMap((parameter): ParamSchemaEntry[] => {
     // Boolean material values are runtime-only and have no UBO representation.
     if (parameter.type === 'bool') return [];
-    if (parameter.type === 'texture') {
+    if (parameter.type === 'texture' || parameter.type === 'texture_cube') {
       if (engineInjectedTextureFields?.has(parameter.name) === true) return [];
-      return [{ name: parameter.name, type: 'texture2d' }];
+      return [
+        {
+          name: parameter.name,
+          type: parameter.type === 'texture_cube' ? 'texture_cube' : 'texture2d',
+        },
+      ];
     }
     return [
       {
@@ -1718,6 +1910,7 @@ export function resolveMaterialSnapshot(
   const samplerHandles = collectMaterialTextureSamplers(pv, (value) =>
     resolveTexLike(materialTextureRef(value), 'SamplerAsset'),
   );
+  const textureSources = collectMaterialTextureSources(pv, world);
   const emissiveTextureHandle = resolveTexLike(
     materialTextureRef(pv.emissiveTexture),
     'TextureAsset',
@@ -1753,6 +1946,7 @@ export function resolveMaterialSnapshot(
     ...(materialParamSchema.length > 0 && { materialParamSchema }),
     ...(textureCoordinates.size > 0 && { textureCoordinates }),
     ...(textureHandles.size > 0 && { textureHandles }),
+    ...(textureSources.size > 0 && { textureSources }),
     ...(videoTextureFields.size > 0 && { videoTextureFields }),
     ...(samplerHandles.size > 0 && { samplerHandles }),
     ...(baseColorTextureHandle !== undefined && { baseColorTexture: baseColorTextureHandle }),
@@ -2056,6 +2250,9 @@ export interface DirectionalCsmConfig {
   readonly cascadeBlend: number;
   readonly mapSize: number;
   readonly shadowDistance: number;
+  readonly shadowFilter: number;
+  readonly shadowAngularRadius: number;
+  readonly maxPenumbraTexels: number;
 }
 
 /**
@@ -2070,6 +2267,7 @@ export interface DirectionalCsmResult {
   readonly cascadeCount: number;
   readonly cascadeBlend: number;
   readonly shadowMapSize: number;
+  readonly directionalShadowQuality: DirectionalShadowQuality;
 }
 
 /**
@@ -2102,9 +2300,6 @@ export function computeDirectionalCsm(
 
   // PSSM split planes: [camera near, shadowDistance], not the camera far.
   const splits = pssmSplit(sNear, sFar, cascadeCount, config.splitLambda);
-  const paddedSplits = new Float32Array(4);
-  for (let i = 0; i < splits.length; i++) paddedSplits[i] = splits[i] ?? 0;
-
   // Light view matrix: camera at origin, looking along the light direction.
   const lightDirN = vec3.normalize(vec3.create(), direction);
   const lightTarget = vec3.create(lightDirN[0] ?? 0, lightDirN[1] ?? 0, lightDirN[2] ?? 0);
@@ -2135,6 +2330,7 @@ export function computeDirectionalCsm(
   mat4.multiply(cameraVP, camProj, camView);
 
   const resultLightViewProjs: Float32Array[] = [];
+  const cascadeFits: DirectionalShadowCascadeFit[] = [];
 
   // bug-20260619 RC-2 (AC-05): toward-light Z reach. Extend the near (toward-
   // light) bound of EVERY cascade to the toward-light extreme of the WHOLE
@@ -2198,16 +2394,34 @@ export function computeDirectionalCsm(
     // lightViewProj = orthoProj * lightView — pure clip-space [-1,1]. Atlas
     // tile placement is handled by the per-cascade viewport + fragment-side UV
     // math (evalDirectional), so shadow_caster.gl_Position stays clip-space.
-    void cIdx;
+    cascadeFits.push({
+      split: splits[cIdx] ?? sFar,
+      minX,
+      maxX,
+      minY,
+      maxY,
+      minZ,
+      maxZ,
+    });
     resultLightViewProjs.push(new Float32Array(mat4.multiply(mat4.create(), orthoProj, lightView)));
   }
 
+  const projection = projectDirectionalShadow(
+    cascadeFits,
+    config.mapSize,
+    config.shadowFilter ?? 2,
+    config.shadowAngularRadius ?? 0.00465,
+    config.maxPenumbraTexels ?? 32,
+  );
+  if (projection === undefined) return null;
+
   return {
     lightViewProj: resultLightViewProjs,
-    splitPlanes: paddedSplits,
+    splitPlanes: projection.splitPlanes,
     cascadeCount,
     cascadeBlend: config.cascadeBlend,
     shadowMapSize: config.mapSize,
+    directionalShadowQuality: projection.directionalShadowQuality,
   };
 }
 
@@ -2239,6 +2453,161 @@ export interface PreparedExtractContext {
   readonly visibility: VisibilitySnapshot;
 }
 
+function collectCameraSnapshots(world: World): CameraSnapshot[] {
+  const worldInternal = createWorldInternalView(world);
+  const cameras: CameraSnapshot[] = [];
+  const cameraQuery = world
+    .query({ read: [Camera], optional: [MotionBlur], with: [Transform] })
+    .unwrap();
+  for (const row of cameraQuery) {
+    const cam = row.get(Camera);
+    const motionBlur = row.get(MotionBlur);
+    const entity = row.entity;
+    const view = worldInternal._getArrayView(entity, Transform, 'world');
+    if (view === undefined) continue;
+    const worldMat = new Float32Array(view);
+    const target = resolveCameraTarget(world, cam.target);
+    cameras.push({
+      entityKey: entity as number,
+      ...(target === undefined ? {} : { target }),
+      historyVersion: cam.historyVersion,
+      position: mat4.getTranslation(vec3.create(), worldMat),
+      world: worldMat,
+      fov: cam.fov,
+      aspect: cam.aspect,
+      near: cam.near,
+      far: cam.far,
+      projection: cameraProjectionFromF32(cam.projection),
+      orthoLeft: cam.left,
+      orthoRight: cam.right,
+      orthoBottom: cam.bottom,
+      orthoTop: cam.top,
+      tonemap: tonemapFromF32(cam.tonemap),
+      exposure: cam.exposure,
+      whitePoint: cam.whitePoint,
+      antialias: antialiasFromF32(cam.antialias),
+      bloom: bloomEnabledFromF32(cam.bloom),
+      bloomThreshold: cam.bloomThreshold,
+      bloomIntensity: cam.bloomIntensity,
+      bloomBlurRadius: cam.bloomBlurRadius,
+      clearColor: [
+        cam.clearColor[0] ?? 0,
+        cam.clearColor[1] ?? 0,
+        cam.clearColor[2] ?? 0,
+        cam.clearColor[3] ?? 1,
+      ],
+      ...(motionBlur === undefined
+        ? {}
+        : {
+            motionBlur: {
+              shutterAngle: motionBlur.shutterAngle,
+              maxRadiusPixels: motionBlur.maxRadiusPixels,
+              sampleCount: motionBlur.sampleCount,
+            },
+          }),
+    });
+  }
+  return cameras;
+}
+
+function collectCubeCameraSnapshots(world: World): CubeCameraSnapshot[] {
+  const worldInternal = createWorldInternalView(world);
+  const snapshots: CubeCameraSnapshot[] = [];
+  const query = world.query({ read: [CubeCamera], with: [Transform] }).unwrap();
+  for (const row of query) {
+    const camera = row.get(CubeCamera);
+    const target = resolveCameraTarget(world, camera.target);
+    if (target === undefined) continue;
+    const view = worldInternal._getArrayView(row.entity, Transform, 'world');
+    if (view === undefined) continue;
+    snapshots.push({
+      entityKey: row.entity as number,
+      target,
+      position: [view[12] ?? 0, view[13] ?? 0, view[14] ?? 0],
+      near: camera.near,
+      far: camera.far,
+      updateIntent: cubeCameraUpdateIntentFromF32(camera.updateIntent),
+      requestVersion: camera.requestVersion,
+      faceBudget: camera.faceBudget,
+    });
+  }
+  return snapshots;
+}
+
+function collectReflectionProbeFacts(world: World): ReflectionProbeFact[] {
+  const worldInternal = createWorldInternalView(world);
+  const facts: ReflectionProbeFact[] = [];
+  const query = world.query({ read: [ReflectionProbe], with: [Transform] }).unwrap();
+  for (const row of query) {
+    const probe = row.get(ReflectionProbe);
+    const view = worldInternal._getArrayView(row.entity, Transform, 'world');
+    if (view === undefined) {
+      continue;
+    }
+    facts.push({
+      worldId: 0,
+      entityKey: row.entity as number,
+      center: [view[12] ?? 0, view[13] ?? 0, view[14] ?? 0],
+      halfExtents: [
+        probe.halfExtents[0] ?? 0,
+        probe.halfExtents[1] ?? 0,
+        probe.halfExtents[2] ?? 0,
+      ],
+      priority: probe.priority,
+      intensity: probe.intensity,
+      resolution: probe.resolution,
+      revision: probe.invalidationVersion,
+      updateIntent: reflectionProbeUpdateIntentFromF32(probe.updateIntent),
+      invalidationVersion: probe.invalidationVersion,
+    });
+  }
+  return facts;
+}
+
+interface CameraRoleSelection {
+  readonly display: readonly CameraSnapshot[];
+  readonly auxiliary: readonly CameraSnapshot[];
+}
+
+function selectCameraRoles(world: World): CameraRoleSelection {
+  const cameras = collectCameraSnapshots(world);
+  const displayEntities = cameras
+    .filter((camera) => camera.target === undefined)
+    .map((camera) => camera.entityKey ?? 0);
+  const activeCameraIndex = selectActiveCameraIndex(
+    displayEntities,
+    getActiveCamera(world)?.entity,
+  );
+  const displayEntityKey = displayEntities[activeCameraIndex] ?? displayEntities[0];
+  const display =
+    displayEntityKey === undefined
+      ? []
+      : cameras.filter((camera) => camera.entityKey === displayEntityKey);
+  const candidates: CameraTargetCandidate[] = cameras.map((camera) => ({
+    worldId: 0,
+    entityKey: camera.entityKey ?? 0,
+    ...(camera.target === undefined ? {} : { target: camera.target }),
+    requestVersion: 0,
+    update: 'continuous',
+  }));
+  const selected = selectCameraTargetViews(candidates, {
+    ...(displayEntityKey === undefined ? {} : { displayEntityKey }),
+    budget: 1,
+  });
+  const auxiliary = selected.auxiliary.flatMap((candidate) =>
+    cameras.filter((camera) => camera.entityKey === candidate.entityKey),
+  );
+  return { display, auxiliary };
+}
+
+export function extractCameraSnapshots(world: World): CameraSnapshot[] {
+  return [...selectCameraRoles(world).display];
+}
+
+export function extractCameraTargetSnapshots(world: World): readonly CameraSnapshot[] {
+  return selectCameraRoles(world).auxiliary;
+}
+
 function tonemapParams(camera: CameraSnapshot): Uint8Array {
   const bytes = new ArrayBuffer(16);
   const floats = new Float32Array(bytes);
@@ -2274,6 +2643,21 @@ export function prepareExtractContext(
 }
 
 const fogQueries = new WeakMap<World, Query<readonly [typeof Fog]>>();
+const fogLkgStates = new WeakMap<
+  World,
+  { lkg: FogFrame | undefined; failure: FogSelectionFailure | undefined }
+>();
+
+function fogState(world: World): {
+  lkg: FogFrame | undefined;
+  failure: FogSelectionFailure | undefined;
+} {
+  const existing = fogLkgStates.get(world);
+  if (existing !== undefined) return existing;
+  const created = { lkg: undefined, failure: undefined };
+  fogLkgStates.set(world, created);
+  return created;
+}
 
 function selectFogFrame(world: World): FogFrame | undefined {
   // Query compilation is owned once per World; Query refreshes its matched
@@ -2301,13 +2685,197 @@ function selectFogFrame(world: World): FogFrame | undefined {
     suns: [],
     lane: 'direct',
   });
-  if (fogSelection.ok) return fogSelection.value.fog;
+  const state = fogState(world);
+  if (fogSelection.ok) {
+    state.lkg = fogSelection.value.fog;
+    state.failure = undefined;
+    return fogSelection.value.fog;
+  }
+  state.failure = {
+    code: fogSelection.error.code,
+    expected: fogSelection.error.expected,
+    hint: fogSelection.error.hint,
+    detail: Object.freeze({ ...fogSelection.error.detail }),
+  };
   routeWorldError(world, fogSelection.error, {
     systemName: 'RenderSystem.extract (fog-selection)',
   });
+  if (state.lkg !== undefined) return state.lkg;
   throw fogSelection.error;
 }
 
+function textureDigest(texture: TextureAsset): string {
+  // The render inspection needs a stable identity token, not a second byte
+  // store.  FNV-1a is deterministic, synchronous, and deliberately labelled
+  // as a non-cryptographic digest so it cannot be mistaken for Catalog proof.
+  let hash = 2166136261;
+  for (const byte of texture.data) hash = Math.imul(hash ^ byte, 16777619) >>> 0;
+  return `fnv1a:${hash.toString(16).padStart(8, '0')}`;
+}
+
+function extractVolumeSnapshot(
+  world: World,
+  assets: AssetRegistry | null | undefined,
+  worldInternal: WorldInternalView,
+): ExtractedVolumetricFog | undefined {
+  const query = world.query({ read: [VolumetricFog] }).unwrap();
+  const authorings: VolumetricFogAuthoring[] = [];
+  let selectedLight:
+    | {
+        readonly entity: EntityHandle;
+        readonly kind: 'directional' | 'point' | 'spot';
+        readonly pointLightEntity?: EntityHandle;
+        readonly spotLightEntity?: EntityHandle;
+      }
+    | undefined;
+  let first:
+    | {
+        readonly densityHandle: Handle<'TextureAsset', 'shared'>;
+        readonly densityAsset: TextureAsset;
+        readonly guid: string;
+      }
+    | undefined;
+
+  for (const row of query) {
+    const source = row.get(VolumetricFog);
+    if (source.light === null) continue;
+    const selected = resolveSelectedVolumetricLight(world, source.light);
+    if (selected.status === 'available') {
+      const pairSpot = source.spotLight === null ? undefined : source.spotLight;
+      selectedLight ??= {
+        entity: selected.entity,
+        kind: selected.kind,
+        ...(selected.kind === 'point' ? { pointLightEntity: selected.entity } : {}),
+        ...(pairSpot === undefined ? {} : { spotLightEntity: pairSpot }),
+      };
+    }
+    const densityHandle = toShared<'TextureAsset'>(Math.round(Number(source.density)));
+    const resolved = resolveAssetHandle<TextureAsset>(world, densityHandle);
+    if (!resolved.ok || resolved.value.kind !== 'texture') {
+      worldInternal._routeError(
+        resolved.ok
+          ? new RhiError({
+              code: 'asset-not-registered',
+              expected: 'VolumetricFog.density resolves to a TextureAsset',
+              hint: 'load a TextureAsset before assigning it to VolumetricFog.density',
+              detail: { assetHandle: Number(densityHandle) },
+            })
+          : resolved.error,
+        { severity: Severity.Error, systemName: 'RenderSystem.extract (volumetric-density)' },
+      );
+      return { status: 'degraded' };
+    }
+    const densityAsset = resolved.value;
+    const guid = assets?.guidOf(densityAsset) ?? `handle:${Number(densityHandle)}`;
+    const shape = densityAsset.shape;
+    const density: VolumeDensityBinding =
+      shape.viewDimension === '3d'
+        ? {
+            guid,
+            generation: 1,
+            shape: {
+              viewDimension: '3d',
+              extent: {
+                width: shape.extent.width,
+                height: shape.extent.height,
+                depth: shape.extent.depth,
+              },
+            },
+            format: densityAsset.format,
+            colorSpace: densityAsset.colorSpace,
+          }
+        : {
+            guid,
+            generation: 1,
+            shape: {
+              viewDimension: shape.viewDimension,
+              extent:
+                shape.viewDimension === '2d-array'
+                  ? {
+                      width: shape.extent.width,
+                      height: shape.extent.height,
+                      layers: shape.extent.layers,
+                    }
+                  : { width: shape.extent.width, height: shape.extent.height },
+            },
+            format: densityAsset.format,
+            colorSpace: densityAsset.colorSpace,
+          };
+    const authoring: VolumetricFogAuthoring = {
+      light: source.light,
+      density,
+      bounds: {
+        min: [source.boundsMin[0] ?? 0, source.boundsMin[1] ?? 0, source.boundsMin[2] ?? 0],
+        max: [source.boundsMax[0] ?? 0, source.boundsMax[1] ?? 0, source.boundsMax[2] ?? 0],
+      },
+      extinction: [source.extinction[0] ?? 0, source.extinction[1] ?? 0, source.extinction[2] ?? 0],
+      albedo: [source.albedo[0] ?? 0, source.albedo[1] ?? 0, source.albedo[2] ?? 0],
+      emission: [source.emission[0] ?? 0, source.emission[1] ?? 0, source.emission[2] ?? 0],
+      anisotropy: source.anisotropy,
+      maxDistance: source.maxDistance,
+    };
+    authorings.push(authoring);
+    first ??= { densityHandle, densityAsset, guid };
+  }
+
+  if (authorings.length === 0) return undefined;
+  const extracted = extractVolumetricFog(authorings);
+  if (!extracted.ok) {
+    worldInternal._routeError(extracted.error, {
+      severity: Severity.Error,
+      systemName: 'RenderSystem.extract (volumetric-fog)',
+    });
+    return {
+      status: 'degraded',
+      ...(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 }),
+                }),
+          }),
+    };
+  }
+  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 }),
+        };
+  return {
+    status: 'available',
+    fog: extracted.value.fog,
+    densityHandle: first.densityHandle,
+    densityAsset: first.densityAsset,
+    guid: first.guid,
+    generation: 1,
+    digest: textureDigest(first.densityAsset),
+    ...selectedLightFields,
+  };
+}
+
 export function extractFrames(
   worlds: readonly World[],
   owner: number | ExtractFramesOwner,
@@ -2464,7 +3032,8 @@ export function extractFrames(
   let shadowMapSize: number | undefined;
   let depthBias: number | undefined;
   let normalBias: number | undefined;
-  let pcfKernelSize: number | undefined;
+  let directionalShadowQuality: DirectionalShadowQuality | undefined;
+  let directionalShadowError: LightValidationError | undefined;
   const pointShadow: PointShadowSnapshot[] = [];
   // bug-20260710-editor-cross-world-shadow: carry the raw CSM config +
   // direction of the first-hit directional so the merge layer can recompute
@@ -2486,7 +3055,8 @@ export function extractFrames(
       shadowMapSize = f.lights.shadowMapSize;
       depthBias = f.lights.depthBias;
       normalBias = f.lights.normalBias;
-      pcfKernelSize = f.lights.pcfKernelSize;
+      directionalShadowQuality = f.lights.directionalShadowQuality;
+      directionalShadowError = f.lights.directionalShadowError;
       directionalCsmConfig = f.lights.directionalCsmConfig;
       directionalCsmDirection = f.lights.directionalCsmDirection;
     }
@@ -2505,6 +3075,9 @@ export function extractFrames(
     if (succeededIndices[fi] === resourceOwner) resourceOwnerFrame = succeededFrames[fi];
   }
   const cameras = cameraOwnerFrame !== undefined ? [...cameraOwnerFrame.cameras] : [];
+  const auxiliaryCameras =
+    cameraOwnerFrame !== undefined ? [...cameraOwnerFrame.auxiliaryCameras] : [];
+  const cubeCameras = cameraOwnerFrame !== undefined ? [...cameraOwnerFrame.cubeCameras] : [];
 
   // bug-20260710-editor-cross-world-shadow: RECOMPUTE directional CSM matrices
   // against the surfaced camera. In a single-world app the per-world extract
@@ -2543,6 +3116,7 @@ export function extractFrames(
       cascadeCount = csm.cascadeCount;
       cascadeBlend = csm.cascadeBlend;
       shadowMapSize = csm.shadowMapSize;
+      directionalShadowQuality = csm.directionalShadowQuality;
     }
     // csm === null (no surfaced camera at all): keep the per-world carry —
     // there is no better data, and a cameraless frame renders nothing anyway.
@@ -2560,16 +3134,19 @@ export function extractFrames(
     shadowMapSize,
     depthBias,
     normalBias,
-    pcfKernelSize,
+    directionalShadowQuality,
+    directionalShadowError,
     pointShadow,
     directionalCsmConfig,
     directionalCsmDirection,
   };
+  const volumetricFog = resourceOwnerFrame?.volumetricFog;
   const skylight = resourceOwnerFrame?.skylight;
   const skylightCount = resourceOwnerFrame?.skylightCount ?? 0;
   const skybox = resourceOwnerFrame?.skybox;
   const skyboxCount = resourceOwnerFrame?.skyboxCount ?? 0;
   const fog = resourceOwnerFrame?.fog;
+  const fogFailure = resourceOwnerFrame?.fogFailure;
   const environment = resourceOwnerFrame?.environment;
   // User-authored PostProcessParams entities are singleton scene resources, so
   // they come from the resourceOwner world (holistic snapshot selection).
@@ -2609,10 +3186,20 @@ export function extractFrames(
   const visibilityStats = {
     explicitlyHidden: succeededFrames.reduce((s, f) => s + f.visibilityStats.explicitlyHidden, 0),
   };
+  const reflectionProbes = succeededFrames.flatMap((f, index) => {
+    const worldId = succeededIndices[index] ?? 0;
+    return (f.reflectionProbes ?? []).map((probe) => ({ ...probe, worldId }));
+  });
 
   return {
     cameras,
+    auxiliaryCameras,
+    cubeCameras,
+    reflectionProbes,
     lights,
+    ...(volumetricFog === undefined
+      ? {}
+      : { volumetricFog: { ...volumetricFog, worldId: resourceOwner } }),
     renderables,
     dispatch: dispatchEntries,
     skylight,
@@ -2620,6 +3207,7 @@ export function extractFrames(
     skybox,
     skyboxCount,
     fog,
+    ...(fogFailure === undefined ? {} : { fogFailure }),
     environment,
     environmentReady: resourceOwnerFrame !== undefined && environment !== undefined,
     frustumStats,
@@ -2715,6 +3303,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // established at the frame boundary; record never revisits World state.
   const fog =
     resourceOwnerFog === undefined ? selectFogFrame(world) : (resourceOwnerFog ?? undefined);
+  const fogFailure = fogState(world).failure;
   const visibility = context.visibility.hasAnyHiddenIntent ? context.visibility : undefined;
   const skinPaletteAllocator = pipelineState?.skinPaletteAllocator ?? null;
 
@@ -2732,8 +3321,13 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // `row.get(X) !== undefined`); K-3 invariant preserved (`_getArrayView`
   // calls survive untouched, only the entity source changes).
   const worldInternal = createWorldInternalView(world);
+  let volumetricFog = extractVolumeSnapshot(world, assets, worldInternal);
 
-  const cameras = extractCameraSnapshots(world);
+  const cameraRoles = selectCameraRoles(world);
+  const cameras = [...cameraRoles.display];
+  const auxiliaryCameras = cameraRoles.auxiliary;
+  const cubeCameras = collectCubeCameraSnapshots(world);
+  const reflectionProbes = collectReflectionProbeFacts(world);
 
   // Three-query union (M2 / w16 / AC-03): directional has no Transform
   // dependency (sun-like infinite-source semantics); point + spot pull
@@ -2754,7 +3348,9 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         depthBias: number;
         normalBias: number;
         shadowDistance: number;
-        pcfKernelSize: number;
+        shadowFilter: number;
+        shadowAngularRadius: number;
+        maxPenumbraTexels: number;
       }
     | undefined;
   for (const row of directionalLightQuery) {
@@ -2763,6 +3359,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     const intensity = l.intensity;
     const snapshot: DirectionalLightSnapshot = {
       kind: 'directional',
+      entity: row.entity,
       direction: vec3.create(l.direction[0] ?? 0, l.direction[1] ?? -1, l.direction[2] ?? 0),
       color: vec3.create(
         (l.color[0] ?? 1) * intensity,
@@ -2783,11 +3380,29 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         depthBias: l.depthBias,
         normalBias: l.normalBias,
         shadowDistance: l.shadowDistance,
-        pcfKernelSize: l.pcfKernelSize,
+        shadowFilter: l.shadowFilter,
+        shadowAngularRadius: l.shadowAngularRadius,
+        maxPenumbraTexels: l.maxPenumbraTexels,
       };
     }
   }
 
+  let directionalShadowError: LightValidationError | undefined;
+  if (directional !== undefined && firstHitShadowFields !== undefined) {
+    const validation = validateDirectionalLightData({
+      direction: directional.direction,
+      castShadow: firstHitCastShadow,
+      ...firstHitShadowFields,
+    });
+    if (!validation.ok) {
+      directionalShadowError = validation.error;
+      worldInternal._routeError(directionalShadowError, {
+        severity: Severity.Error,
+        systemName: 'RenderSystem.extract (directional-shadow)',
+      });
+    }
+  }
+
   const pointSnapshots: PointLightSnapshot[] = [];
   // feat-20260612-point-light-shadows-urp-hdrp M4 / T-M4-4: track entity per
   // pointSnapshots index so the post-extract pointShadow join can stamp
@@ -2818,6 +3433,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
       worldMat !== undefined ? mat4.getTranslation(vec3.create(), worldMat) : vec3.create(0, 0, 0);
     pointSnapshots.push({
       kind: 'point',
+      entity: entityId,
       position,
       color: vec3.create(
         (p.color[0] ?? 1) * intensity,
@@ -2889,11 +3505,20 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     const sMapSize = s.mapSize;
     const sNearPlane = s.nearPlane;
     const sFarPlane = s.farPlane;
+    const shadowIntensity = s.shadowIntensity;
+    // `shared<T>` columns are u32-backed and zero-filled when the optional
+    // field is absent. Treat only a positive handle as an authored projector;
+    // checking nullish values alone would turn the zero sentinel into a
+    // phantom projector matrix and an avoidable asset-not-found diagnostic.
+    const hasProjector = Number(s.projector) > 0;
 
     let lightViewProj: Float32Array | undefined;
     let shadowAtlasTile = -1;
 
-    if (castShadow && hasValidDirection) {
+    // A projector needs the same perspective transform even when its SpotLight
+    // has no shadow atlas tile. The matrix remains a derived light fact; the
+    // shadow tile stays -1 so shadow visibility is still independently gated.
+    if ((castShadow || hasProjector) && hasValidDirection) {
       const target = vec3.create(
         (position[0] ?? 0) + (dirN[0] ?? 0),
         (position[1] ?? 0) + (dirN[1] ?? 0),
@@ -2912,14 +3537,40 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
       mat4.multiply(lightViewProj as Mat4, proj, view);
 
       // D-4: allocate tile 0..3; 5th+ = -1 sentinel.
-      if (spotTileNext < 4) {
+      if (castShadow && spotTileNext < 4) {
         shadowAtlasTile = spotTileNext;
         spotTileNext += 1;
       }
     }
 
+    let projectorHandle: Handle<'TextureAsset', 'shared'> | undefined;
+    let projectorAsset: TextureAsset | undefined;
+    let projectorGuid: string | undefined;
+    if (hasProjector) {
+      const candidate = toShared<'TextureAsset'>(Math.round(Number(s.projector)));
+      const resolvedProjector = resolveAssetHandle<TextureAsset>(world, candidate);
+      if (!resolvedProjector.ok || resolvedProjector.value.kind !== 'texture') {
+        worldInternal._routeError(
+          resolvedProjector.ok
+            ? new RhiError({
+                code: 'asset-not-registered',
+                expected: 'SpotLight.projector resolves to a TextureAsset',
+                hint: 'load the authored projector TextureAsset before assigning SpotLight.projector',
+                detail: { assetHandle: Number(candidate) },
+              })
+            : resolvedProjector.error,
+          { severity: Severity.Error, systemName: 'RenderSystem.extract (spot-projector)' },
+        );
+      } else {
+        projectorHandle = candidate;
+        projectorAsset = resolvedProjector.value;
+        projectorGuid = assets?.guidOf(projectorAsset) ?? `handle:${Number(candidate)}`;
+      }
+    }
+
     spotSnapshots.push({
       kind: 'spot',
+      entity: row.entity,
       // D-6: position reflects world transform; direction stays sourced
       // from SpotLight.direction (NOT rotated by the parent).
       position,
@@ -2940,9 +3591,59 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
       nearPlane: sNearPlane,
       farPlane: sFarPlane,
       shadowAtlasTile,
+      shadowIntensity,
+      depthBias: s.depthBias,
+      normalBias: s.normalBias,
+      pcfKernelSize: s.pcfKernelSize,
+      ...(projectorHandle === undefined ||
+      projectorAsset === undefined ||
+      projectorGuid === undefined
+        ? {}
+        : {
+            projectorHandle,
+            projectorAsset,
+            projectorGuid,
+            projectorGeneration: 1,
+            projectorRevision: 1,
+          }),
     });
   }
 
+  // The SpotLight is the sole projector owner. Once all light snapshots have
+  // been extracted, publish its accepted TextureAsset tuple on the volume
+  // snapshot so surface and volume consume the same identity and revision.
+  let volumeSpot: SpotLightSnapshot | undefined;
+  const extractedFog = volumetricFog;
+  if (extractedFog !== undefined) {
+    if (extractedFog.spotLightEntity !== undefined) {
+      volumeSpot = spotSnapshots.find((light) => light.entity === extractedFog.spotLightEntity);
+    } else if (extractedFog.lightKind === 'spot') {
+      volumeSpot = spotSnapshots.find((light) => light.entity === extractedFog.lightEntity);
+    }
+  }
+  if (
+    volumetricFog !== undefined &&
+    volumetricFog.status === 'available' &&
+    volumeSpot?.projectorAsset !== undefined &&
+    volumeSpot.projectorHandle !== undefined
+  ) {
+    const projectorHandle = volumeSpot.projectorHandle;
+    const projectorAsset = volumeSpot.projectorAsset;
+    volumetricFog = {
+      ...volumetricFog,
+      projector: {
+        guid: volumeSpot.projectorGuid ?? `handle:${Number(volumeSpot.projectorHandle)}`,
+        generation: volumeSpot.projectorGeneration ?? 1,
+        view: '2d',
+        sampler: 'linear-clamp-to-edge',
+        projection: 'spot-projection',
+        revision: volumeSpot.projectorRevision ?? 1,
+      },
+      projectorHandle,
+      projectorAsset,
+    };
+  }
+
   // bug-20260710-editor-cross-world-shadow: CSM matrices are computed by the
   // shared pure {@link computeDirectionalCsm}, called here per-world with THIS
   // world's own `cameras[0]`. In a single-world app the light and camera share
@@ -2957,6 +3658,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   let cascadeCount: number | undefined;
   let cascadeBlend: number | undefined;
   let shadowMapSize: number | undefined;
+  let directionalShadowQuality: DirectionalShadowQuality | undefined;
   let directionalCsmConfig: DirectionalCsmConfig | undefined;
   let directionalCsmDirection: Vec3 | undefined;
 
@@ -2982,7 +3684,11 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // feat-20260621 M2: CSM computation gated on castShadow from the
   // merged DirectionalLight. castShadow defaults to true (first-hit-wins
   // semantics, D-6 no cardinality cap).
-  if (directional !== undefined && firstHitCastShadow !== false) {
+  if (
+    directional !== undefined &&
+    firstHitCastShadow !== false &&
+    directionalShadowError === undefined
+  ) {
     const dirSnapshot = directional;
     const sf = firstHitShadowFields;
     if (sf !== undefined) {
@@ -2992,6 +3698,9 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         cascadeBlend: sf.cascadeBlend,
         mapSize: sf.mapSize,
         shadowDistance: sf.shadowDistance,
+        shadowFilter: sf.shadowFilter,
+        shadowAngularRadius: sf.shadowAngularRadius,
+        maxPenumbraTexels: sf.maxPenumbraTexels,
       };
       directionalCsmDirection = dirSnapshot.direction;
       const csm = computeDirectionalCsm(dirSnapshot.direction, directionalCsmConfig, cameraData);
@@ -3006,13 +3715,19 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
       if (csm !== null) {
         lightViewProj = csm.lightViewProj;
         splitPlanes = csm.splitPlanes;
+        directionalShadowQuality = csm.directionalShadowQuality;
       } else {
         const sNear = cameraData?.near ?? 0.1;
         const splits = pssmSplit(sNear, sf.shadowDistance, cascadeCount, sf.splitLambda);
-        const padded = new Float32Array(4);
-        for (let i = 0; i < splits.length; i++) padded[i] = splits[i] ?? 0;
+        const padded = new Float32Array(16);
+        for (let i = 0; i < splits.length; i++) padded[i * 4] = splits[i] ?? 0;
         splitPlanes = padded;
       }
+      directionalShadowQuality = directionalShadowQualityFromF32(
+        sf.shadowFilter,
+        sf.shadowAngularRadius,
+        sf.maxPenumbraTexels,
+      );
     }
   }
 
@@ -3021,7 +3736,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // the View UBO tail keeps a stable layout regardless of the runtime
   // cascadeCount. Host-side correctness invariant: only the first
   // cascadeCount slots are ever read by the WGSL kernel.
-  const paddedSplitPlanes = new Float32Array(4);
+  const paddedSplitPlanes = new Float32Array(16);
   if (splitPlanes !== undefined) {
     for (let i = 0; i < splitPlanes.length; i++) {
       paddedSplitPlanes[i] = splitPlanes[i] ?? 0;
@@ -3031,9 +3746,9 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // feat-20260612-point-light-shadows-urp-hdrp M1 / T-M1-7 (plan-strategy §D-3,
   // requirements §5.3): query (PointLight + PointLightShadow + Transform)
   // archetype join. For each shadow caster, build 6 face VP matrices and pack
-  // into Float32Array(96). Atlas layer assigned in spawn order (0..3); the
-  // sentinel -1 is shader-side and applies to non-shadow PointLights only.
-  // Cap of 4 is enforced by ECS cardinality on PointLightShadow.
+  // into Float32Array(96). Atlas layer is assigned in spawn order while the
+  // renderer-owned atlas has capacity; the sentinel -1 is shader-side and
+  // applies to non-admitted PointLightShadow requests as well.
   const pointShadowSnapshots: PointShadowSnapshot[] = [];
   {
     const pointShadowQuery = world
@@ -3061,7 +3776,13 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
       const mapSize = ps.mapSize;
       const nearPlane = ps.nearPlane;
       const farPlane = ps.farPlane;
-      const layer = pointShadowSnapshots.length; // 0, 1, 2, 3 in spawn order
+      // The renderer, not ECS, owns the atlas budget. Preserve every request
+      // for inspection, but emit the shader sentinel for entries that cannot
+      // acquire a layer so record never calls faceView outside the atlas.
+      const layer =
+        pointShadowSnapshots.length < SHADOW_ATLAS_DEFAULT_LAYERS
+          ? pointShadowSnapshots.length
+          : -1;
 
       const matrices = buildPointShadowMatrices(lightPos, nearPlane, farPlane);
       const packed = new Float32Array(96);
@@ -3119,7 +3840,8 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     shadowMapSize,
     depthBias: firstHitCastShadow !== false ? firstHitShadowFields?.depthBias : undefined,
     normalBias: firstHitCastShadow !== false ? firstHitShadowFields?.normalBias : undefined,
-    pcfKernelSize: firstHitCastShadow !== false ? firstHitShadowFields?.pcfKernelSize : undefined,
+    directionalShadowQuality,
+    directionalShadowError,
     pointShadow: pointShadowSnapshots,
     // bug-20260710-editor-cross-world-shadow: raw CSM config + light direction
     // so the merge layer can recompute matrices against the surfaced camera.
@@ -4011,6 +4733,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               pv.occlusionTexture,
             );
             const textureCoordinates = collectMaterialTextureCoordinates(pv);
+            const textureSources = collectMaterialTextureSources(pv, world);
             const emissivePv = pv.emissive as readonly number[] | undefined;
             // feat-20260625 M2 / w6: first-pass transparency flag folds into
             // MaterialSnapshot.transparent so the record stage can drive the
@@ -4110,6 +4833,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               ...(textureCoordinates.size > 0 && { textureCoordinates }),
               ...(samplerHandles.size > 0 && { samplerHandles }),
               ...(textureHandles.size > 0 && { textureHandles }),
+              ...(textureSources.size > 0 && { textureSources }),
               ...(videoTextureFields.size > 0 && { videoTextureFields }),
               ...(baseColorTextureHandle !== undefined && {
                 baseColorTexture: baseColorTextureHandle,
@@ -4328,6 +5052,15 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           }
         }
 
+        // A pbr-skin PSO requires the complete three-binding group(2) skin
+        // 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 (materialSnap.materialShaderId === 'forgeax::pbr-skin' && skinSlice === undefined) {
+          pendingDispatch.length = 0;
+          continue;
+        }
+
         // feat-20260601 D-3: read the resolved world mat4 (propagateTransforms
         // output) straight from the Transform.world column array view. The
         // record stage copies these 16 floats into the mesh SSBO with zero
@@ -4516,6 +5249,44 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                 projection: identityProjection(),
               } satisfies PointsLinesRetainedSnapshot);
 
+        // Instances are snapshotted before the CPU visibility decision so the
+        // culling owner can derive the union of every instance's transformed
+        // mesh bounds. The same detached snapshot is then carried to record;
+        // do not re-read the ECS array after culling (a structural write must
+        // not make the cull and draw disagree within one frame).
+        let instancesSnap: InstancesSnapshot | undefined;
+        if (hasInstances) {
+          const transforms = worldInternal._getArrayView(entity, Instances, 'transforms');
+          if (transforms === undefined) {
+            // A present component with an unavailable array is an empty
+            // instance contribution, not an absent component. Preserve the
+            // zero-draw contract so the record stage cannot synthesize one
+            // identity instance from an incomplete row.
+            instancesSnap = {
+              transforms: new Float32Array(),
+              instanceCount: 0,
+              cacheKey: entity,
+              archVersion,
+            };
+          } else {
+            const actualLength = transforms.length;
+            if (actualLength % 16 !== 0) {
+              worldInternal._routeError(new InstanceTransformsStrideMismatchError(actualLength), {
+                severity: Severity.Error,
+                systemName: 'RenderSystem.extract (Instances stride)',
+              });
+              continue;
+            }
+            const snapshotCopy = new Float32Array(transforms);
+            instancesSnap = {
+              transforms: snapshotCopy,
+              instanceCount: actualLength / 16,
+              cacheKey: entity,
+              archVersion,
+            };
+          }
+        }
+
         let nonIndexedFirst = 0;
         const gpuDrivenDraws = gpuDrivenSubmeshes.flatMap((submesh) => {
           const drawMaterial = materialsArr[submesh.materialSlot] ?? materialSnap;
@@ -4548,6 +5319,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           entityKey: entity,
           ...(skinSlice !== undefined ? { skin: skinSlice } : {}),
           ...(morph !== undefined ? { morph } : {}),
+          ...(instancesSnap !== undefined ? { instances: instancesSnap } : {}),
           ...(spriteInstancesSnap !== undefined ? { spriteInstances: spriteInstancesSnap } : {}),
           ...(pointsLines !== undefined ? { pointsLines } : {}),
         };
@@ -4559,66 +5331,70 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         // producer-owned finite local-space AABBs. Culling is unconditional
         // engine behavior; there is no per-entity opt-out.
         if (localAabb !== undefined) {
-          // feat-20260601 D-3: cull AABB uses the resolved world mat4
-          // directly (no compose) -- same source the record stage feeds
-          // the mesh SSBO, so cull stays same-source with render (AC-05).
-          const worldAabb = box3.create();
-          box3.transformBox3(worldAabb, cullingLocalAabb, transformSnap.world);
-
-          // Test against all cameras. Entity is visible if one camera
-          // frustum intersects the world-space AABB (or planes are empty
-          // from degenerate projection).
-          frustumTotal += 1;
-          let visible = frustumPlanes.length === 0;
-          for (let ci = 0; ci < frustumPlanes.length; ci++) {
-            const planes = frustumPlanes[ci] as Float32Array;
-            if (planes.length === 0) {
-              visible = true;
-              break;
-            }
-            if (frustum.intersectsBox(planes as frustum.Frustum, worldAabb as box3.Box3Like)) {
-              visible = true;
-              break;
-            }
-          }
-          if (!visible) {
-            frustumCulled += 1;
-            continue;
-          }
-        }
-
-        if (hasInstances) {
-          const transforms = worldInternal._getArrayView(entity, Instances, 'transforms');
-          if (transforms === undefined) {
-            flushPendingDispatch(pendingDispatch);
-            renderables.push(baseRenderable);
+          // An empty or malformed Instances payload has no meaningful bounds.
+          // Keep it conservative (the draw path later emits zero instances)
+          // instead of manufacturing the entity's identity bounds. For a
+          // valid payload, derive one world-space union for CPU culling while
+          // leaving the mesh-local AABB untouched for GPU per-instance cull.
+          const derivedInstancesBounds =
+            instancesSnap === undefined || instancesSnap.instanceCount === 0
+              ? undefined
+              : deriveInstancesUnionBounds({
+                  meshAabb: cullingLocalAabb,
+                  entityWorld: transformSnap.world,
+                  transforms: instancesSnap.transforms,
+                });
+          if (instancesSnap?.instanceCount === 0) {
+            // No instance can contribute a visible bound. The retained
+            // snapshot still records instanceCount=0 for the record stage.
+          } else if (
+            hasInstances &&
+            (instancesSnap === undefined || derivedInstancesBounds === undefined)
+          ) {
+            // Missing/malformed derived facts are a conservative no-cull
+            // result. The stride validator above already rejects malformed
+            // lengths; this branch covers non-finite producer matrices/AABB.
           } else {
-            const actualLength = transforms.length;
-            if (actualLength % 16 !== 0) {
-              worldInternal._routeError(new InstanceTransformsStrideMismatchError(actualLength), {
-                severity: Severity.Error,
-                systemName: 'RenderSystem.extract (Instances stride)',
-              });
+            // feat-20260601 D-3: cull AABB uses the resolved world mat4
+            // directly (no compose) -- same source the record stage feeds
+            // the mesh SSBO, so cull stays same-source with render (AC-05).
+            const worldAabb = box3.create();
+            if (derivedInstancesBounds !== undefined) {
+              worldAabb[0] = derivedInstancesBounds[0] ?? 0;
+              worldAabb[1] = derivedInstancesBounds[1] ?? 0;
+              worldAabb[2] = derivedInstancesBounds[2] ?? 0;
+              worldAabb[3] = derivedInstancesBounds[3] ?? 0;
+              worldAabb[4] = derivedInstancesBounds[4] ?? 0;
+              worldAabb[5] = derivedInstancesBounds[5] ?? 0;
+            } else {
+              box3.transformBox3(worldAabb, cullingLocalAabb, transformSnap.world);
+            }
 
+            // Test against all cameras. Entity is visible if one camera
+            // frustum intersects the world-space AABB (or planes are empty
+            // from degenerate projection).
+            frustumTotal += 1;
+            let visible = frustumPlanes.length === 0;
+            for (let ci = 0; ci < frustumPlanes.length; ci++) {
+              const planes = frustumPlanes[ci] as Float32Array;
+              if (planes.length === 0) {
+                visible = true;
+                break;
+              }
+              if (frustum.intersectsBox(planes as frustum.Frustum, worldAabb as box3.Box3Like)) {
+                visible = true;
+                break;
+              }
+            }
+            if (!visible) {
+              frustumCulled += 1;
               continue;
             }
-            const snapshotCopy = new Float32Array(transforms);
-            const instanceCount = Math.max(1, Math.floor(actualLength / 16));
-            flushPendingDispatch(pendingDispatch);
-            renderables.push({
-              ...baseRenderable,
-              instances: {
-                transforms: snapshotCopy,
-                instanceCount,
-                cacheKey: entity,
-                archVersion,
-              },
-            });
           }
-        } else {
-          flushPendingDispatch(pendingDispatch);
-          renderables.push(baseRenderable);
         }
+
+        flushPendingDispatch(pendingDispatch);
+        renderables.push(baseRenderable);
       }
 
       // feat-20260520-2d-sprite-layer-mvp M-3 / w22 + w25: finalise the
@@ -4653,10 +5429,12 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // whitePoint / tonemap` onto the SAME unified params channel custom
   // post-processes use — `Camera.exposure` stays the AI-user-facing SSOT (D-5),
   // the engine itself acts as the provider for the Standard tonemap shader
-  // id. The 16B layout is byte-identical to the prior recordTonemapPass packing
-  // (render-system-record.ts pre-w14): Float32 [exposure, whitePoint, _, pad]
-  // with the mode u32 occupying the third 4-byte slot via tonemapToU32 (SSOT in
-  // camera.ts). Run AFTER the user-entity collection above so the engine's
+  // id. The 16B layout keeps the prior recordTonemapPass packing
+  // (render-system-record.ts pre-w14): Float32 [exposure, whitePoint, _,
+  // ditherEnabled], with the mode u32 occupying the third 4-byte slot via
+  // tonemapToU32 (SSOT in camera.ts). The final Output Transform makes a
+  // per-pass copy and writes ditherEnabled at byte offset 12; the extracted
+  // camera snapshot remains the SSOT. Run AFTER the user-entity collection above so the engine's
   // built-in provider is authoritative for its own reserved key (a user entity
   // can never shadow the Standard tonemap identity. The single active camera mirrors
   // recordFrame's `activeCameras[0]` selection.
@@ -4667,9 +5445,13 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
 
   return {
     cameras,
+    auxiliaryCameras,
+    cubeCameras,
+    reflectionProbes,
     lights,
     environment,
     environmentReady: true,
+    ...(volumetricFog === undefined ? {} : { volumetricFog }),
     renderables,
     dispatch,
     skylight,
@@ -4677,6 +5459,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     skybox,
     skyboxCount,
     fog,
+    ...(fogFailure === undefined ? {} : { fogFailure }),
     frustumStats: { culled: frustumCulled, total: frustumTotal },
     visibilityStats: { explicitlyHidden: explicitlyHidden.size },
     postProcessParams,