@forgeax/engine-render 0.1.20 → 0.1.21

package/src/render-system-extract.ts

@@ -154,6 +154,12 @@ import {
 } from '@forgeax/engine-types';
 import {
   Atmosphere,
+  antialiasFromF32,
+  bloomEnabledFromF32,
+  Camera,
+  CubeCamera,
+  cameraProjectionFromF32,
+  cubeCameraUpdateIntentFromF32,
   DirectionalLight,
   Fog,
   Instances,
@@ -161,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 {
@@ -195,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,
@@ -203,13 +227,20 @@ 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,
@@ -252,8 +283,9 @@ export interface PointLightSnapshot {
   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 +
@@ -290,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 {
@@ -304,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;
   /**
@@ -404,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
@@ -439,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
@@ -851,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
@@ -1060,6 +1093,12 @@ 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;
@@ -1080,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
@@ -1105,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
@@ -1147,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
@@ -1427,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,
@@ -1517,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 [
       {
@@ -1779,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',
@@ -1814,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 }),
@@ -2117,6 +2250,9 @@ export interface DirectionalCsmConfig {
   readonly cascadeBlend: number;
   readonly mapSize: number;
   readonly shadowDistance: number;
+  readonly shadowFilter: number;
+  readonly shadowAngularRadius: number;
+  readonly maxPenumbraTexels: number;
 }
 
 /**
@@ -2131,6 +2267,7 @@ export interface DirectionalCsmResult {
   readonly cascadeCount: number;
   readonly cascadeBlend: number;
   readonly shadowMapSize: number;
+  readonly directionalShadowQuality: DirectionalShadowQuality;
 }
 
 /**
@@ -2163,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);
@@ -2196,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
@@ -2259,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,
   };
 }
 
@@ -2300,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);
@@ -2335,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
@@ -2362,10 +2685,22 @@ 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;
 }
 
@@ -2697,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
@@ -2719,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;
     }
@@ -2738,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
@@ -2776,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.
@@ -2793,7 +3134,8 @@ export function extractFrames(
     shadowMapSize,
     depthBias,
     normalBias,
-    pcfKernelSize,
+    directionalShadowQuality,
+    directionalShadowError,
     pointShadow,
     directionalCsmConfig,
     directionalCsmDirection,
@@ -2804,6 +3146,7 @@ export function extractFrames(
   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).
@@ -2843,9 +3186,16 @@ 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
       ? {}
@@ -2857,6 +3207,7 @@ export function extractFrames(
     skybox,
     skyboxCount,
     fog,
+    ...(fogFailure === undefined ? {} : { fogFailure }),
     environment,
     environmentReady: resourceOwnerFrame !== undefined && environment !== undefined,
     frustumStats,
@@ -2952,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;
 
@@ -2971,7 +3323,11 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   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
@@ -2992,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) {
@@ -3022,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
@@ -3282,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;
 
@@ -3307,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) {
@@ -3317,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);
@@ -3331,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,
+      );
     }
   }
 
@@ -3346,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;
@@ -3356,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
@@ -3386,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);
@@ -3444,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.
@@ -4336,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
@@ -4435,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,
@@ -4653,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
@@ -4841,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;
@@ -4873,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 } : {}),
         };
@@ -4884,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
@@ -4978,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.
@@ -4992,6 +5445,9 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
 
   return {
     cameras,
+    auxiliaryCameras,
+    cubeCameras,
+    reflectionProbes,
     lights,
     environment,
     environmentReady: true,
@@ -5003,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,