@forgeax/engine-render 0.1.27 → 0.1.29

package/src/render-system-extract.ts

@@ -76,9 +76,18 @@ import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-c
 //                               `MeshFilter.assetHandle` dangling path
 //                               (charter proposition 5; AC-11).
 //
-// World owns explicit Instances transforms. Extraction makes a detached
-// per-renderer projection; GPU residents acknowledge complete snapshots only
-// after successful uploads. Reading a snapshot never changes author state.
+// Renderer-owned Large Instances:
+//   `Instances { collectionId }` is an ECS association to the renderer's
+//   `InstanceCollectionStore`, not an ECS transform-array column. The extract
+//   tail resolves the identity against that store and snapshots canonical
+//   transforms together with collection revision, capacity, dirty ranges,
+//   and residency facts. Invalid or stale associations route the existing
+//   typed `InstanceCollectionError` through the World error boundary; the
+//   record stage owns GPU residency and upload decisions.
+//
+// `SpriteInstances` remains the separate ECS-owned array-view path. Its
+// snapshot is intentionally independent from renderer-owned Large Instances,
+// so the extract stage does not duplicate collection storage or GPU policy.
 
 import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import {
@@ -94,9 +103,11 @@ import { AssetGuid, type AssetGuid as AssetGuidBytes } from '@forgeax/engine-pac
 import { RhiError } from '@forgeax/engine-rhi';
 import { GlobalTransform, Transform } from '@forgeax/engine-scene';
 import {
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
   DEFAULT_STANDARD_SURFACE_MODULE,
   type MaterialShaderArtifact,
   STANDARD_PIPELINE_PARAM_SCHEMA,
+  standardTextureMask,
 } from '@forgeax/engine-shader';
 import type {
   Asset,
@@ -110,7 +121,6 @@ import type {
   MaterialTextureValue,
   MeshLodLevel,
   ParamSchemaEntry,
-  PrimitiveTopology,
   TextureAsset,
 } from '@forgeax/engine-types';
 import {
@@ -119,17 +129,21 @@ import {
   materialValuesToLinearRuntime,
   toShared,
 } from '@forgeax/engine-types';
+import { buildCubeCameraFaceViews } from './capture/cube-views';
 import {
   antialiasFromF32,
   bloomEnabledFromF32,
+  CAMERA_EXPOSURE_MODE_MANUAL,
   Camera,
   CubeCamera,
+  cameraExposureFromColumns,
   cameraProjectionFromF32,
   cubeCameraUpdateIntentFromF32,
   Fog,
   MotionBlur,
   ReflectionProbe,
   reflectionProbeUpdateIntentFromF32,
+  ScreenSpaceReflection,
   tonemapFromF32,
   tonemapToU32,
 } from './components';
@@ -147,12 +161,13 @@ import type {
   FogFrame,
   FogSelectionFailure,
 } from './extract/environment';
+import type { GpuDrivenDrawSnapshot } from './extract/gpu-driven';
 import { resolveVisibility, type VisibilitySnapshot } from './extract/visibility';
 import type {
   RenderFeatureHiddenEntityReport,
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types';
-import type { InstanceCollectionId, InstanceProjectionStore } from './instances';
+import type { InstanceCollectionId, InstanceCollectionStore } from './instances';
 import type {
   MeshMaterialBindingDiagnostic,
   MeshMaterialBindingSource,
@@ -165,7 +180,7 @@ import { defaultMaterialSnapshot } from './render-system-extract-tail';
 import { getActiveCamera, selectActiveCameraIndex } from './systems/active-camera';
 import { selectPasses } from './systems/pass-selector';
 import type { SkinPaletteAllocator } from './systems/skin-palette-allocator';
-import type { SkinPaletteSlice } from './systems/skin-palette-types';
+import type { SkinPaletteReceipt } from './systems/skin-palette-types';
 import type { RenderTarget, RenderTargetTextureSource } from './targets/contracts';
 import { resolveRenderTargetMaterialSource } from './targets/material-source';
 import { resolveSelectedVolumetricLight } from './volume/capability';
@@ -204,6 +219,8 @@ export interface DirectionalLightSnapshot {
 export interface PointLightSnapshot {
   readonly kind: 'point';
   readonly entity?: EntityHandle | number;
+  /** World identity stamped by the composited extract owner. */
+  readonly worldId?: number;
   readonly position: Vec3;
   readonly color: Vec3;
   readonly intensity: number;
@@ -257,12 +274,16 @@ export interface PointLightSnapshot {
 export interface PointShadowSnapshot {
   /** Spawning entity index (joins PointLight + PointLightShadow + Transform). */
   readonly entity: number;
+  /** World identity stamped by the composited extract owner. */
+  readonly worldId?: number;
   /** World-space light position (sourced from companion Transform). */
   readonly position: Vec3;
   /** PointLightShadow.mapSize (per-face cube square dimension; 512 default). */
   readonly mapSize: number;
   readonly nearPlane: number;
   readonly farPlane: number;
+  readonly depthBias: number;
+  readonly normalBias: number;
   /**
    * Atlas layer assigned by extract in spawn order while capacity remains.
    * Sentinel -1 is used for a request that cannot be admitted and is
@@ -298,6 +319,8 @@ export interface SpotLightSnapshot {
   readonly kind: 'spot';
   /** Entity identity is branded in extracted frames; numeric fixtures remain compatible. */
   readonly entity?: EntityHandle | number;
+  /** World identity stamped by the composited extract owner. */
+  readonly worldId?: number;
   readonly position: Vec3;
   readonly direction: Vec3;
   readonly color: Vec3;
@@ -586,6 +609,8 @@ export interface SkylightSnapshot {
 /** Local diffuse probe facts; specular remains owned by Skylight/ReflectionProbe. */
 export interface LightProbeSnapshot {
   readonly identity: string;
+  /** World identity stamped by the composited extract owner. */
+  readonly worldId?: number;
   readonly position: readonly [number, number, number];
   readonly radius: number;
   readonly irradiance: Float32Array;
@@ -646,6 +671,8 @@ export interface ExtractedVolumetricFog {
 }
 
 export interface RenderableSnapshot {
+  /** Authored hierarchical visibility; retained hidden rows remain addressable. */
+  readonly authorVisible?: boolean;
   readonly assetHandle: number;
   readonly transform: TransformSnapshot;
   /** Producer-authored lower-detail references projected from MeshAsset. */
@@ -683,8 +710,6 @@ export interface RenderableSnapshot {
   readonly materialBindingSources: readonly MeshMaterialBindingSource[];
   /** Active structured override diagnostics for this renderable. */
   readonly materialBindingDiagnostics?: readonly MeshMaterialBindingDiagnostic[];
-  /** Effective authored visibility retained by the persistent scene owner. */
-  readonly authorVisible?: boolean;
   /**
    * feat-20260708-composited-multi-world-rendering M1 / D-1: the worldId
    * of the world this renderable was extracted from. Defaults to 0 in
@@ -749,9 +774,14 @@ export interface RenderableSnapshot {
    * draw to `forgeax::pbr-skin` pipeline + set the palette dynamic offset.
    * Absent (`undefined`) means the entity is not skinned.
    */
-  readonly skin?: SkinPaletteSlice;
-  /** Joint entity identities used by the persistent skin dependency index. */
+  readonly skin?: SkinPaletteReceipt;
+  /** Joint identities consumed by the retained scene dependency index. */
   readonly skinJointEntities?: readonly number[];
+  /** Source pass ownership retained with the scene record across view changes. */
+  readonly shadowCasterPasses?: readonly Omit<
+    ShadowCasterMembership,
+    'worldEntity' | 'renderableIndex'
+  >[];
   /**
    * ECS-owned morph weights. Presence selects the Standard Pipeline CPU
    * specialized deformation lane; the asset remains the source of target
@@ -782,7 +812,7 @@ export interface RenderableTemporalSnapshot {
   readonly reactiveReasons: readonly RenderableReactiveReason[];
   readonly previousTransform: TransformSnapshot;
   readonly previousInstances: InstancesSnapshot | undefined;
-  readonly previousSkin: SkinPaletteSlice | undefined;
+  readonly previousSkin: SkinPaletteReceipt | undefined;
   readonly previousMorphWeights: Float32Array | undefined;
 }
 
@@ -791,26 +821,7 @@ export interface MorphSnapshot {
   readonly targetCount: number;
 }
 
-export interface GpuDrivenDrawSnapshot {
-  readonly kind: 'indexed' | 'non-indexed';
-  readonly first: number;
-  readonly count: number;
-  readonly baseVertex: number;
-  readonly materialSlot: number;
-  readonly topology: PrimitiveTopology;
-  readonly pipelineClass: string;
-  readonly materialResourceClass: string;
-  /** Producer-owned prepared ABI facts used by the Standard PBR GPU lane. */
-  readonly prepared?: import('./gpu-driven/prepared-draw').PreparedGpuDrivenDraw;
-  /** Optional projected height supplied by direct GPU-view evidence/tests. */
-  readonly projectedHeight?: number;
-  /** Root plus lower-detail index/vertex ranges, in LOD order. */
-  readonly lodRanges?: readonly {
-    readonly first: number;
-    readonly count: number;
-    readonly baseVertex: number;
-  }[];
-}
+export type { GpuDrivenDrawSnapshot } from './extract/gpu-driven';
 
 export interface InstancesSnapshot {
   /** Renderer-owned collection identity. */
@@ -821,6 +832,13 @@ export interface InstancesSnapshot {
   readonly instanceCount: number;
   /** Collection revision captured by this detached frame snapshot. */
   readonly revision?: number;
+  /** Logical collection capacity at snapshot time. */
+  readonly capacity?: number;
+  /** Coalesced matrix ordinals dirtied since the previous authoring update. */
+  readonly dirtyRanges?: readonly {
+    readonly start: number;
+    readonly end: number;
+  }[];
   /** Stable per-entity GPU buffer cache key (the packed Entity u32). */
   readonly cacheKey: number;
   /**
@@ -935,6 +953,8 @@ export interface MaterialSnapshot {
   readonly paramSnapshot?: Readonly<Record<string, number | number[] | string>> | undefined;
   /** Effective MaterialAsset parameter contract used to lay out this snapshot. */
   readonly materialParamSchema?: readonly ParamSchemaEntry[] | undefined;
+  /** Authored texture presence, separate from the shared GPU layout schema. */
+  readonly standardTextureMask?: number | undefined;
   /** Authored per-slot UV set and KHR texture transform metadata. */
   readonly textureCoordinates?: ReadonlyMap<string, MaterialTextureCoordinates> | undefined;
   /**
@@ -954,6 +974,8 @@ export interface MaterialSnapshot {
    * them in a lightmap injection region.
    */
   readonly textureHandles?: ReadonlyMap<string, Handle<'TextureAsset', 'shared'>> | undefined;
+  /** Explicitly authored texture fields that must resolve before GPU admission. */
+  readonly authoredTextureFields?: ReadonlySet<string> | undefined;
   /** Renderer-local target sources; never projected as TextureAsset handles. */
   readonly textureSources?: ReadonlyMap<string, RenderTargetTextureSource> | undefined;
   /**
@@ -974,6 +996,8 @@ export interface MaterialSnapshot {
   readonly videoTextureFields?: ReadonlyMap<string, Handle<'VideoAsset', 'shared'>> | undefined;
   /** Authored sampler handles keyed by their matching texture parameter. */
   readonly samplerHandles?: ReadonlyMap<string, Handle<'SamplerAsset', 'shared'>> | undefined;
+  /** Explicitly authored sampler fields that must resolve before GPU admission. */
+  readonly authoredSamplerFields?: ReadonlySet<string> | undefined;
   readonly baseColorTexture?: Handle<'TextureAsset', 'shared'> | undefined;
   /**
    * PBR metallic-roughness texture handle (present for PBR/sprite/skin
@@ -1188,6 +1212,11 @@ export interface ExtractedFrame {
    * three-bucket model per plan-strategy D-3.
    */
   readonly dispatch: DispatchEntry[];
+  readonly shadowCasterEntityKeys: ReadonlySet<number>;
+  /** ShadowCaster ownership keyed by concrete draw item and pass. */
+  readonly shadowCasterDrawKeys: ReadonlySet<string>;
+  /** Structured ShadowCaster ownership facts retained for exact residual routing. */
+  readonly shadowCasterMembership?: readonly ShadowCasterMembership[];
   readonly skylight: SkylightSnapshot | undefined;
   readonly skylightCount: number;
   /** World-local diffuse probe candidates; never a direct-light slot. */
@@ -1207,6 +1236,8 @@ export interface ExtractedFrame {
   readonly frustumStats: { readonly culled: number; readonly total: number };
   /** Candidate entities rejected by author visibility before resource parsing. */
   readonly visibilityStats: { readonly explicitlyHidden: number };
+  /** Detached material-source probe accounting for this extraction. */
+  readonly materialTextureSources?: MaterialTextureSourceStats;
   /**
    * Per-frame post-process params snapshot collected from PostProcessParams
    * entities (D-1: data-driven params channel). Maps shader id to the
@@ -1223,6 +1254,30 @@ export interface ExtractedFrame {
   readonly hiddenEntityReports: readonly RenderFeatureHiddenEntityReport[];
 }
 
+/** Extracted ownership fact for one concrete ShadowCaster pass. */
+export interface ShadowCasterMembership {
+  readonly worldEntity: number;
+  readonly renderableIndex: number;
+  readonly drawItemIndex: number;
+  readonly materialHandle: number;
+  readonly passIndex: number;
+  readonly materialShaderId?: string;
+  readonly renderState?: MaterialRenderState;
+  readonly cpuReason?: ShadowCasterCpuReason;
+}
+
+/** Producer evidence for a concrete ShadowCaster pass that remains on CPU. */
+export type ShadowCasterCpuReason =
+  | 'transparent'
+  | 'morph'
+  | 'unsupported-shader'
+  | 'unsupported-render-state'
+  | 'missing-skin-bounds'
+  | 'missing-gpu-draw'
+  | 'unprepared'
+  | 'prepared-contract'
+  | 'multi-pass';
+
 export type CameraTargetUpdate = 'once' | 'on-demand' | 'continuous';
 
 export interface CameraTargetCandidate {
@@ -1376,6 +1431,52 @@ export function materialTextureFields(
   return fields;
 }
 
+function declaredMaterialTextureFields(
+  shaderId: string | undefined,
+  paramSchema: readonly ParamSchemaEntry[] | undefined,
+  assets: AssetRegistry,
+): ReadonlySet<string> | undefined {
+  return materialTextureFields(
+    shaderId,
+    paramSchema !== undefined
+      ? derive(paramSchema).textureFieldNames
+      : shaderId !== undefined
+        ? assets.materialShaderTextureFieldNames(shaderId)
+        : undefined,
+  );
+}
+
+/** Preserve authored-vs-default intent for the GPU resource readiness gate. */
+export function collectAuthoredMaterialTextureFields(
+  values: Readonly<Record<string, unknown>>,
+  shaderId: string | undefined,
+  paramSchema: readonly ParamSchemaEntry[] | undefined,
+  assets: AssetRegistry,
+): ReadonlySet<string> | undefined {
+  const fields = declaredMaterialTextureFields(shaderId, paramSchema, assets);
+  if (fields === undefined) return undefined;
+  const authored = new Set<string>();
+  for (const field of fields) {
+    if (Object.hasOwn(values, field)) authored.add(field);
+  }
+  return authored.size === 0 ? undefined : authored;
+}
+
+/** Preserve explicit sampler intent; omitted samplers use the default sampler. */
+export function collectAuthoredMaterialSamplerFields(
+  values: Readonly<Record<string, unknown>>,
+  textureFields: ReadonlySet<string> | undefined,
+): ReadonlySet<string> | undefined {
+  const authored = new Set<string>();
+  for (const field of textureFields ?? []) {
+    if (materialTextureValue(values[field])?.sampler !== undefined) authored.add(field);
+  }
+  if (Object.hasOwn(values, 'sampler') && values.sampler !== undefined) {
+    authored.add('baseColorTexture');
+  }
+  return authored.size === 0 ? undefined : authored;
+}
+
 /**
  * The authored material surface uses the module IDs declared by built-in WGSL
  * sources. Runtime pipeline caches still use the existing engine registration
@@ -1507,6 +1608,82 @@ export function pipelineRenderState(
   };
 }
 
+export function shadowCasterCpuReason(
+  material: MaterialSnapshot,
+  draw: GpuDrivenDrawSnapshot | undefined,
+  shadowEntries: readonly DispatchEntry[],
+  morph: MorphSnapshot | undefined,
+  skin: SkinPaletteReceipt | undefined,
+): ShadowCasterCpuReason | undefined {
+  if (shadowEntries.length !== 1) return 'multi-pass';
+  if (material.transparent === true || material.renderState?.blend !== undefined) {
+    return 'transparent';
+  }
+  if (morph !== undefined) return 'morph';
+  const isStandardPbr =
+    material.materialShaderId === 'forgeax::default-standard-pbr' ||
+    material.materialShaderId === 'forgeax::pbr-skin' ||
+    material.materialShaderId === 'forgeax::default-standard-pbr-skin';
+  if (!isStandardPbr) return 'unsupported-shader';
+  const shadowEntry = shadowEntries[0];
+  if (
+    shadowEntry !== undefined &&
+    shadowEntry.materialShaderId !== undefined &&
+    shadowEntry.materialShaderId !== 'forgeax::default-shadow-caster'
+  ) {
+    return 'unsupported-shader';
+  }
+  if (shadowEntry?.renderState !== undefined) return 'unsupported-render-state';
+  if (draw === undefined) return 'missing-gpu-draw';
+  if (draw.prepared === undefined) return 'unprepared';
+  const isSkinnedPbr =
+    material.materialShaderId === 'forgeax::pbr-skin' ||
+    material.materialShaderId === 'forgeax::default-standard-pbr-skin';
+  const preparedMaterial = draw.prepared.identity.material;
+  const preparedDeformation = draw.prepared.identity.deformation;
+  const materialContractMatches =
+    (material.materialShaderId === 'forgeax::default-standard-pbr' &&
+      preparedMaterial === 'forgeax::default-standard-pbr') ||
+    (isSkinnedPbr &&
+      (preparedMaterial === 'forgeax::pbr-skin' ||
+        preparedMaterial === 'forgeax::default-standard-pbr-skin'));
+  const deformationContractMatches =
+    (skin === undefined && preparedDeformation === 'rigid') ||
+    (skin !== undefined && preparedDeformation === 'skin');
+  if (!materialContractMatches || !deformationContractMatches) return 'prepared-contract';
+  if (isSkinnedPbr && !hasFiniteOrderedSkinBounds(skin?.bounds)) {
+    return 'missing-skin-bounds';
+  }
+  return undefined;
+}
+
+function hasFiniteOrderedSkinBounds(bounds: Float32Array | undefined): bounds is Float32Array {
+  if (bounds === undefined || bounds.length !== 6) return false;
+  const minX = bounds[0];
+  const minY = bounds[1];
+  const minZ = bounds[2];
+  const maxX = bounds[3];
+  const maxY = bounds[4];
+  const maxZ = bounds[5];
+  return (
+    minX !== undefined &&
+    minY !== undefined &&
+    minZ !== undefined &&
+    maxX !== undefined &&
+    maxY !== undefined &&
+    maxZ !== undefined &&
+    Number.isFinite(minX) &&
+    Number.isFinite(minY) &&
+    Number.isFinite(minZ) &&
+    Number.isFinite(maxX) &&
+    Number.isFinite(maxY) &&
+    Number.isFinite(maxZ) &&
+    minX <= maxX &&
+    minY <= maxY &&
+    minZ <= maxZ
+  );
+}
+
 /**
  * tweak-20260627-model-loading-smoke-build-perf M4: per-World intern cache for
  * the loadByGuid texture/sampler resolution path. A MaterialAsset's
@@ -1663,20 +1840,82 @@ export function collectMaterialTextureCoordinates(
   return out;
 }
 
+/**
+ * Return the schema-owned fields that may carry a texture source handle.
+ * Numeric material values are otherwise scalar parameters (roughness,
+ * metallic, custom steps, ...), so probing them through SharedRefStore is
+ * both wasted work and an accidental dependency on slot-number collisions.
+ */
+export function materialTextureSourceFields(
+  schema: readonly ParamSchemaEntry[] | undefined,
+): ReadonlySet<string> | undefined {
+  if (schema === undefined) return undefined;
+  const fields = new Set<string>();
+  for (const entry of schema) {
+    if (entry.type.startsWith('texture')) fields.add(entry.name);
+  }
+  return fields;
+}
+
+export interface MaterialTextureSourceStats {
+  sourceFieldsVisited: number;
+  numericSharedRefProbes: number;
+  sourceCacheHits: number;
+  sourceCacheMisses: number;
+  producerRoutes: Record<string, number>;
+}
+
+/**
+ * Extract-local cache for numeric shared references. `null` is a deliberate
+ * negative entry: a handle that is not a render-target source must not be
+ * resolved repeatedly for every material field in the same frame.
+ */
+export type MaterialTextureSourceCache = Map<number, RenderTargetTextureSource | null>;
+
 export function collectMaterialTextureSources(
   values: Readonly<Record<string, unknown>>,
   world: World,
+  textureFields?: ReadonlySet<string>,
+  stats?: MaterialTextureSourceStats,
+  cache?: MaterialTextureSourceCache,
 ): Map<string, RenderTargetTextureSource> {
   const out = new Map<string, RenderTargetTextureSource>();
   for (const [field, value] of Object.entries(values)) {
-    const reference = materialTextureRef(value);
+    const structured = materialTextureValue(value);
+    const schemaKnown = textureFields !== undefined;
+    const schemaAdmitted = textureFields?.has(field) === true;
+    // With a known schema, only producer-admitted texture fields may carry a
+    // source handle. Without a schema, retain the historical numeric parse so
+    // an older producer can still publish a direct shared-ref value; its
+    // structured form is accepted on the same conservative path.
+    if (schemaKnown && !schemaAdmitted) continue;
+    const reference = structured?.texture ?? value;
+    if (stats !== undefined) stats.sourceFieldsVisited += 1;
     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);
+    if (stats !== undefined) stats.numericSharedRefProbes += 1;
+    let source: RenderTargetTextureSource | undefined;
+    if (cache?.has(reference) === true) {
+      if (stats !== undefined) stats.sourceCacheHits += 1;
+      source = cache.get(reference) ?? undefined;
+    } else {
+      if (stats !== undefined) stats.sourceCacheMisses += 1;
+      const resolved = world.sharedRefs.resolve<
+        'RenderTargetTextureSource',
+        RenderTargetTextureSource
+      >(toShared<'RenderTargetTextureSource'>(reference));
+      if (!resolved.ok) {
+        cache?.set(reference, null);
+      } else {
+        const binding = resolveRenderTargetMaterialSource(resolved.value);
+        cache?.set(reference, binding === undefined ? null : resolved.value);
+        source = binding === undefined ? undefined : resolved.value;
+      }
+    }
+    if (source === undefined) continue;
+    if (stats !== undefined) {
+      stats.producerRoutes.renderTarget = (stats.producerRoutes.renderTarget ?? 0) + 1;
+    }
+    out.set(field, source);
   }
   return out;
 }
@@ -1764,6 +2003,27 @@ export function isEngineInjectedTextureField(
   return isStandardPbrMaterialShader(shaderId) && ENGINE_INJECTED_TEXTURE_FIELDS.has(fieldName);
 }
 
+export function materialStandardTextureMask(
+  parameters: readonly MaterialParameter[] | undefined,
+  shaderId: string | undefined,
+  values: Readonly<Record<string, unknown>>,
+): number | undefined {
+  return isCanonicalStandardPbrMaterialShader(shaderId)
+    ? standardTextureMask(
+        // Canonical materials may provide values without redeclaring the root
+        // schema. Pruning must agree with the texture binder in that route too.
+        DEFAULT_STANDARD_PBR_PARAM_SCHEMA.filter(
+          (entry) =>
+            entry.type === 'texture2d' &&
+            (values[entry.name] !== undefined ||
+              parameters?.some(
+                (parameter) => parameter.name === entry.name && parameter.default !== undefined,
+              )),
+        ),
+      )
+    : undefined;
+}
+
 /**
  * Project one material's authoring parameters into the runtime ABI.
  *
@@ -1953,6 +2213,8 @@ export function resolveMaterialSnapshot(
   materialSnapshotCache?: MaterialSnapshotCache,
   persistentMaterialSnapshotCache?: MaterialSnapshotCache,
   materialContext?: MaterialCookProgramContext,
+  materialTextureSourceStats?: MaterialTextureSourceStats,
+  materialTextureSourceCache?: MaterialTextureSourceCache,
 ): MaterialSnapshot {
   if (handleRaw === 0) return defaultMaterialSnapshot(handleRaw);
   const cached = materialSnapshotCache?.get(handleRaw);
@@ -2054,7 +2316,13 @@ export function resolveMaterialSnapshot(
   const samplerHandles = collectMaterialTextureSamplers(pv, (value) =>
     resolveTexLike(materialTextureRef(value), 'SamplerAsset'),
   );
-  const textureSources = collectMaterialTextureSources(pv, world);
+  const textureSources = collectMaterialTextureSources(
+    pv,
+    world,
+    materialTextureSourceFields(materialParamSchema.length > 0 ? materialParamSchema : undefined),
+    materialTextureSourceStats,
+    materialTextureSourceCache,
+  );
   const emissiveTextureHandle = resolveTexLike(
     materialTextureRef(pv.emissiveTexture),
     'TextureAsset',
@@ -2087,6 +2355,7 @@ export function resolveMaterialSnapshot(
     renderState: pipelineRenderState(allPasses[0]?.renderState),
     paramSnapshot: paramSnap,
     ...(materialParamSchema.length > 0 && { materialParamSchema }),
+    standardTextureMask: materialStandardTextureMask(resolved.parameters, firstPassShader, pv),
     ...(textureCoordinates.size > 0 && { textureCoordinates }),
     ...(textureHandles.size > 0 && { textureHandles }),
     ...(textureSources.size > 0 && { textureSources }),
@@ -2289,41 +2558,15 @@ export function pssmSplit(
 // requirements §5.3): 6-face view-proj matrix table for one omnidirectional
 // shadow caster.
 //
-// Face order matches WebGPU cube layer convention (also LearnOpenGL 5.3.2):
-//   0 (+X) | look=(+1, 0, 0) | up=(0, -1, 0)
-//   1 (-X) | look=(-1, 0, 0) | up=(0, -1, 0)
-//   2 (+Y) | look=(0, +1, 0) | up=(0,  0, +1)
-//   3 (-Y) | look=(0, -1, 0) | up=(0,  0, -1)
-//   4 (+Z) | look=(0, 0, +1) | up=(0, -1, 0)
-//   5 (-Z) | look=(0, 0, -1) | up=(0, -1, 0)
-//
-// Projection: WebGPU [0, 1] NDC perspective (mat4.perspective short name).
-// fov=90deg, aspect=1, near/far from PointLightShadow component.
-const POINT_SHADOW_FACE_LOOK: readonly Vec3[] = [
-  vec3.create(1, 0, 0),
-  vec3.create(-1, 0, 0),
-  vec3.create(0, 1, 0),
-  vec3.create(0, -1, 0),
-  vec3.create(0, 0, 1),
-  vec3.create(0, 0, -1),
-];
-const POINT_SHADOW_FACE_UP: readonly Vec3[] = [
-  vec3.create(0, -1, 0),
-  vec3.create(0, -1, 0),
-  vec3.create(0, 0, 1),
-  vec3.create(0, 0, -1),
-  vec3.create(0, -1, 0),
-  vec3.create(0, -1, 0),
-];
-
 /**
  * Build 6 face view-proj matrices for an omnidirectional shadow caster
  * (point-light cube map). Returns 6 mat4 (column-major 16-float each) in face
- * order [+X, -X, +Y, -Y, +Z, -Z] matching WebGPU cube layer convention.
+ * order [+X, -X, +Y, -Y, +Z, -Z] matching the WebGPU cube-camera layer
+ * convention.
  *
- * Each matrix is `proj * view` where:
- *   - `view = lookAt(lightPos, lightPos + faceLook[i], faceUp[i])`
- *   - `proj = perspective(PI/2, 1, near, far)` (WebGPU [0, 1] NDC short name)
+ * Derive face directions from the shared CubeCamera owner, then reflect clip X
+ * to match WebGPU cubemap texel orientation. The point-shadow raster lane
+ * mirrors authored front-face winding when it uses these reflected matrices.
  *
  * The returned `Mat4[]` length is always exactly 6. Caller can flatten into a
  * 96-float (6 mat4) Float32Array for UBO upload (T-M1-7).
@@ -2333,29 +2576,10 @@ const POINT_SHADOW_FACE_UP: readonly Vec3[] = [
  * @param far  far plane distance  (PointLightShadow.farPlane)
  */
 export function buildPointShadowMatrices(lightPos: Vec3, near: number, far: number): Mat4[] {
-  const fovY = Math.PI / 2; // 90 deg
-  const aspect = 1;
-  const proj = mat4.create();
-  mat4.perspective(proj, fovY, aspect, near, far);
-
-  const out: Mat4[] = [];
-  for (let i = 0; i < 6; i++) {
-    // biome-ignore lint/style/noNonNullAssertion: i in [0..6) and arrays are length-6 const
-    const look = POINT_SHADOW_FACE_LOOK[i]!;
-    // biome-ignore lint/style/noNonNullAssertion: i in [0..6) and arrays are length-6 const
-    const up = POINT_SHADOW_FACE_UP[i]!;
-    const target = vec3.create(
-      (lightPos[0] ?? 0) + (look[0] ?? 0),
-      (lightPos[1] ?? 0) + (look[1] ?? 0),
-      (lightPos[2] ?? 0) + (look[2] ?? 0),
-    );
-    const view = mat4.create();
-    mat4.lookAt(view, lightPos, target, up);
-    const vp = mat4.create();
-    mat4.multiply(vp, proj, view);
-    out.push(vp);
-  }
-  return out;
+  return buildCubeCameraFaceViews({ position: lightPos, near, far }).map(({ viewProjection }) => {
+    for (const offset of [0, 4, 8, 12]) viewProjection[offset] = -(viewProjection[offset] ?? 0);
+    return viewProjection;
+  });
 }
 
 /**
@@ -2581,6 +2805,8 @@ export function computeDirectionalCsm(
 export interface ExtractFramesOwner {
   readonly cameraOwner: number;
   readonly resourceOwner: number;
+  /** Explicit display-camera entity selected by the frame owner. */
+  readonly cameraEntityKey?: number;
 }
 
 export interface PreparedExtractContext {
@@ -2593,18 +2819,23 @@ export interface PreparedExtractContext {
   readonly resourceOwnerFog: FogFrame | null | undefined;
   readonly cull: 'self' | 'none' | 'external';
   readonly cullCameras: readonly CameraSnapshot[] | undefined;
+  /** Explicit display-camera entity for this world's camera-owner extract. */
+  readonly cameraEntityKey?: number;
   readonly renderables: 'full' | 'none';
-  /** Restrict renderable extraction to these entities while still reading frame resources. */
   readonly renderableEntities: ReadonlySet<number> | undefined;
-  /** Keep authored-hidden renderables in the persistent source projection. */
   readonly retainHidden: boolean;
+  /** World identity used to form cross-world producer ownership keys. */
+  readonly worldId: number;
   readonly visibility: VisibilitySnapshot;
   /** Producer-owned artifact lookup; extraction only, never record-time asset reads. */
   readonly getMaterialShaderArtifact:
-    | ((materialShaderId: string) => MaterialShaderArtifact | undefined)
+    | ((
+        materialShaderId: string,
+        vertexColorAvailable?: boolean,
+      ) => MaterialShaderArtifact | undefined)
     | undefined;
   /** Renderer-owned canonical source for explicit large instance collections. */
-  readonly instanceCollections: InstanceProjectionStore | undefined;
+  readonly instanceCollections: InstanceCollectionStore | undefined;
 }
 
 const ALL_VISIBLE: VisibilitySnapshot = {
@@ -2619,16 +2850,37 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
   const worldInternal = createWorldInternalView(world);
   const cameras: CameraSnapshot[] = [];
   const cameraQuery = world
-    .query({ read: [Camera], optional: [MotionBlur], with: [Transform, GlobalTransform] })
+    .query({
+      read: [Camera],
+      optional: [MotionBlur, ScreenSpaceReflection],
+      with: [Transform, GlobalTransform],
+    })
     .unwrap();
   for (const row of cameraQuery) {
     const cam = row.get(Camera);
     const motionBlur = row.get(MotionBlur);
+    const screenSpaceReflection = row.get(ScreenSpaceReflection);
     const entity = row.entity;
     const view = worldInternal._getArrayView(entity, GlobalTransform, 'world');
     if (view === undefined) continue;
     const worldMat = new Float32Array(view);
     const target = resolveCameraTarget(world, cam.target);
+    const hasNonDefaultOutput =
+      cam.exposureMode !== CAMERA_EXPOSURE_MODE_MANUAL ||
+      cam.exposure !== 1 ||
+      cam.temperature !== 6504 ||
+      cam.tint !== 0 ||
+      cam.colorLut !== 0 ||
+      cam.colorLutStrength !== 0;
+    const output = hasNonDefaultOutput
+      ? {
+          exposure: cameraExposureFromColumns(cam),
+          temperature: cam.temperature,
+          tint: cam.tint,
+          colorLut: cam.colorLut,
+          colorLutStrength: cam.colorLutStrength,
+        }
+      : undefined;
     cameras.push({
       entityKey: entity as number,
       ...(target === undefined ? {} : { target }),
@@ -2647,6 +2899,7 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
       tonemap: tonemapFromF32(cam.tonemap),
       exposure: cam.exposure,
       whitePoint: cam.whitePoint,
+      ...(output === undefined ? {} : { output }),
       antialias: antialiasFromF32(cam.antialias),
       bloom: bloomEnabledFromF32(cam.bloom),
       bloomThreshold: cam.bloomThreshold,
@@ -2667,6 +2920,15 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
               sampleCount: motionBlur.sampleCount,
             },
           }),
+      ...(screenSpaceReflection === undefined
+        ? {}
+        : {
+            screenSpaceReflection: {
+              maxDistance: screenSpaceReflection.maxDistance,
+              thickness: screenSpaceReflection.thickness,
+              maxRoughness: screenSpaceReflection.maxRoughness,
+            },
+          }),
     });
   }
   return cameras;
@@ -2733,16 +2995,23 @@ interface CameraRoleSelection {
   readonly auxiliary: readonly CameraSnapshot[];
 }
 
-export function selectCameraRoles(world: World): CameraRoleSelection {
+export function selectCameraRoles(world: World, requestedEntityKey?: number): CameraRoleSelection {
   const cameras = collectCameraSnapshots(world);
   const displayEntities = cameras
     .filter((camera) => camera.target === undefined)
     .map((camera) => camera.entityKey ?? 0);
+  const hasExplicitSelection = requestedEntityKey !== undefined;
   const activeCameraIndex = selectActiveCameraIndex(
     displayEntities,
-    getActiveCamera(world)?.entity,
+    hasExplicitSelection ? requestedEntityKey : getActiveCamera(world)?.entity,
   );
-  const displayEntityKey = displayEntities[activeCameraIndex] ?? displayEntities[0];
+  // An explicit FrameCamera selection is authoritative. If it does not name a
+  // display camera, retain the existing no-camera error path instead of
+  // silently selecting the first camera. ActiveCamera keeps its established
+  // first-hit fallback when no explicit frame selection is supplied.
+  const displayEntityKey = hasExplicitSelection
+    ? displayEntities[activeCameraIndex]
+    : (displayEntities[activeCameraIndex] ?? displayEntities[0]);
   const display =
     displayEntityKey === undefined
       ? []
@@ -2792,13 +3061,16 @@ export function prepareExtractContext(
     readonly resourceOwnerFog?: FogFrame | null;
     readonly cull?: 'self' | 'none' | 'external';
     readonly cullCameras?: readonly CameraSnapshot[];
+    readonly cameraEntityKey?: number;
     readonly renderables?: 'full' | 'none';
     readonly renderableEntities?: ReadonlySet<number>;
     readonly retainHidden?: boolean;
+    readonly worldId?: number;
     readonly getMaterialShaderArtifact?: (
       materialShaderId: string,
+      vertexColorAvailable?: boolean,
     ) => MaterialShaderArtifact | undefined;
-    readonly instanceCollections?: InstanceProjectionStore;
+    readonly instanceCollections?: InstanceCollectionStore;
   } = {},
 ): PreparedExtractContext {
   const renderables = options.renderables ?? 'full';
@@ -2810,7 +3082,9 @@ export function prepareExtractContext(
     resourceOwnerFog: options.resourceOwnerFog,
     cull: options.cull ?? 'self',
     cullCameras: options.cullCameras,
+    ...(options.cameraEntityKey === undefined ? {} : { cameraEntityKey: options.cameraEntityKey }),
     renderables,
+    worldId: options.worldId ?? 0,
     renderableEntities: options.renderableEntities,
     retainHidden: options.retainHidden ?? false,
     visibility: renderables === 'none' ? ALL_VISIBLE : resolveVisibility(world),