@forgeax/engine-render 0.1.27 → 0.1.29

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

@@ -5,14 +5,12 @@ import {
 } from '@forgeax/engine-assets-runtime';
 import type { EntityHandle, World } from '@forgeax/engine-ecs';
 import {
-  InstanceTransformsStrideMismatchError,
   routeWorldError,
   SpawnLightInvalidBoundsError,
   SpriteInstancesCountMismatchError,
   SpriteInstancesMutuallyExclusiveWithInstancesError,
   SpriteInstancesRequiresSpriteShaderError,
 } from '@forgeax/engine-ecs/projection';
-import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
 import { box3, frustum, type Mat4, mat4, type Vec3, vec3 } from '@forgeax/engine-math';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
 import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-cook';
@@ -39,6 +37,7 @@ import {
   ASSET_ERROR_HINTS,
   AssetError,
   derive,
+  err,
   handleSlot,
   materialValuesToLinearRuntime,
   toShared,
@@ -81,16 +80,23 @@ import {
 import { selectEnvironment } from './environment/frame';
 import { MaterialSkinAttrMissingError, SkinMaterialMismatchError } from './errors/render';
 import type { EnvironmentCandidate, EnvironmentFrame } from './extract/environment';
-import { buildGpuDrivenDraws, resolvePreparedGpuDrivenDraw } from './extract/gpu-driven';
+import {
+  buildGpuDrivenDraws,
+  gpuDrivenShadowDrawKey,
+  gpuDrivenSourceDrawItemIndex,
+} from './extract/gpu-driven';
 import type { VisibilitySnapshot } from './extract/visibility';
 import type {
   RenderFeatureHiddenEntityReport,
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types';
 import { ensureGlyphMeshMaterialSlots } from './glyph-text-layout-system';
-import type { GpuDrivenGeometryReceipt } from './gpu-driven/prepared-draw';
-import type { InstanceProjectionStore } from './instances';
-import { deriveInstancesUnionBounds, fingerprintNumericArray } from './instances-derived-bounds';
+import {
+  InstanceCollectionError,
+  type InstanceCollectionId,
+  type InstanceCollectionStore,
+} from './instances';
+import { deriveInstancesUnionBounds } from './instances-derived-bounds';
 import {
   type MeshMaterialBindingDiagnostic,
   type MeshMaterialBindingSource,
@@ -101,6 +107,7 @@ import { expandPointsLinesBounds } from './points-lines/bounds';
 import type { PointsLinesRetainedSnapshot, PointsLinesStyle } from './points-lines/snapshot';
 import { COOKIE_SLICE_CAPACITY, IES_SLICE_CAPACITY } from './prepare/extended-lighting/resources';
 import { prepareCookieProjection } from './prepare/extended-lighting/spot-modifiers';
+import { worldEntityKey } from './record/frame-snapshot';
 import { STANDARD_OUTPUT_TRANSFORM_FEATURE_ID } from './render-contract';
 import type {
   CsmCameraData,
@@ -116,12 +123,15 @@ import type {
   MaterialSnapshot,
   MaterialSnapshotCache,
   MaterialSnapshotCachesByWorld,
+  MaterialTextureSourceCache,
+  MaterialTextureSourceStats,
   MorphSnapshot,
   PointLightSnapshot,
   PointShadowSnapshot,
   PreparedExtractContext,
   RectAreaDirectLightSnapshot,
   RenderableSnapshot,
+  ShadowCasterMembership,
   SkyboxSnapshot,
   SkylightSnapshot,
   SpotLightSnapshot,
@@ -134,6 +144,8 @@ import {
   BUILTIN_USER_REGION_TEXTURE_FIELDS,
   buildPointShadowMatrices,
   buildRectAreaWorldFrame,
+  collectAuthoredMaterialSamplerFields,
+  collectAuthoredMaterialTextureFields,
   collectCubeCameraSnapshots,
   collectMaterialTextureCoordinates,
   collectMaterialTextureSamplers,
@@ -150,8 +162,10 @@ import {
   materialNormalScale,
   materialParamSchemaForMaterial,
   materialProgramKeysForMaterial,
+  materialStandardTextureMask,
   materialTextureFields,
   materialTextureRef,
+  materialTextureSourceFields,
   pipelineRenderState,
   prepareExtractContext,
   pssmSplit,
@@ -163,12 +177,19 @@ import {
   Severity,
   selectCameraRoles,
   selectFogFrame,
+  shadowCasterCpuReason,
   sortDispatchByQueue,
   storeMaterialSnapshot,
   tonemapParams,
 } from './render-system-extract';
+import { buildShadowFrusta } from './scene/shadow-visibility';
 import { SHADOW_ATLAS_DEFAULT_LAYERS } from './shadow-atlas';
-import type { SkinPaletteSlice } from './systems/skin-palette-types';
+import type { SkinPaletteReceipt } from './systems/skin-palette-types';
+
+function skinPaletteIdentity(world: World, entity: number): string {
+  return `skin:${world.identity}:${entity}`;
+}
+
 export function extractFrames(
   worlds: readonly World[],
   owner: number | ExtractFramesOwner,
@@ -178,13 +199,19 @@ export function extractFrames(
   options: {
     readonly materialContext?: MaterialCookProgramContext;
     readonly cull?: 'normal' | 'none';
-    readonly renderables?: 'full' | 'none';
-    readonly renderableEntitiesByWorld?: readonly (ReadonlySet<number> | undefined)[];
+    readonly renderables?:
+      | 'full'
+      | 'none'
+      | {
+          readonly kind: 'partial';
+          readonly entitiesByWorld: readonly (ReadonlySet<number> | undefined)[];
+        };
     readonly retainHidden?: boolean;
     readonly getMaterialShaderArtifact?: (
       materialShaderId: string,
+      vertexColorAvailable?: boolean,
     ) => MaterialShaderArtifact | undefined;
-    readonly instanceCollections?: InstanceProjectionStore;
+    readonly instanceCollections?: InstanceCollectionStore;
   } = {},
 ): ExtractedFrame {
   // w4: normalize the owner argument. A bare number is the legacy single-owner
@@ -193,6 +220,12 @@ export function extractFrames(
   // single-owner behaviour (w1 contract combination 2).
   const cameraOwner = typeof owner === 'number' ? owner : owner.cameraOwner;
   const resourceOwner = typeof owner === 'number' ? owner : owner.resourceOwner;
+  const cameraEntityKey = typeof owner === 'number' ? undefined : owner.cameraEntityKey;
+  const renderableRequest = options.renderables ?? 'full';
+  const renderableMode = typeof renderableRequest === 'object' ? 'full' : renderableRequest;
+  const partialEntitiesByWorld =
+    typeof renderableRequest === 'object' ? renderableRequest.entitiesByWorld : undefined;
+  const retainHidden = options.retainHidden ?? typeof renderableRequest === 'object';
 
   // ── D-2: frame-level side effects live here ────────────────────────────
   //
@@ -201,7 +234,14 @@ export function extractFrames(
   // extract runs, so sequential per-world allocation yields non-overlapping
   // palette slices (AC-08).
   const skinPaletteAllocator = pipelineState?.skinPaletteAllocator ?? null;
-  if (skinPaletteAllocator !== null) {
+  // A partial request is still normalized to the producer's full renderable
+  // query, but it is not a full allocator reconciliation.  beginFrame/endFrame
+  // mark every persistent identity not visited by this selected subset as
+  // detached; doing that here would release untouched palettes.  Only the
+  // explicit full request is allowed to reconcile the identity set.
+  const reconcileSkinFrame = renderableRequest === 'full';
+  if (skinPaletteAllocator !== null && reconcileSkinFrame) {
+    skinPaletteAllocator.beginFrame();
     skinPaletteAllocator.resetForFrame();
   }
 
@@ -237,6 +277,13 @@ export function extractFrames(
     const world = worlds[wi];
     if (world === undefined || failedWorlds.has(world)) continue;
     try {
+      if (skinPaletteAllocator !== null && partialEntitiesByWorld !== undefined) {
+        for (const entityKey of partialEntitiesByWorld[wi] ?? []) {
+          if (!world.hasComponent(entityKey as EntityHandle, Skin)) {
+            skinPaletteAllocator.releasePersistentSlice(skinPaletteIdentity(world, entityKey));
+          }
+        }
+      }
       const isCameraOwner = wi === cameraOwner;
       const cameraOwnerFrame = framesByWorld.get(cameraOwner);
       const prepared = prepareExtractContext(world, {
@@ -258,11 +305,13 @@ export function extractFrames(
           ? {}
           : { materialContext: options.materialContext }),
         cull: options.cull === 'none' ? 'none' : isCameraOwner ? 'self' : 'external',
-        renderables: options.renderables ?? 'full',
-        ...(options.renderableEntitiesByWorld?.[wi] === undefined
+        renderables: renderableMode,
+        ...(isCameraOwner && cameraEntityKey !== undefined ? { cameraEntityKey } : {}),
+        ...(partialEntitiesByWorld?.[wi] === undefined
           ? {}
-          : { renderableEntities: options.renderableEntitiesByWorld[wi] }),
-        retainHidden: options.retainHidden ?? false,
+          : { renderableEntities: partialEntitiesByWorld[wi] }),
+        retainHidden,
+        worldId: wi,
         ...(options.getMaterialShaderArtifact === undefined
           ? {}
           : { getMaterialShaderArtifact: options.getMaterialShaderArtifact }),
@@ -287,6 +336,13 @@ export function extractFrames(
     }
   }
 
+  // Reconcile persistent palette identities from the extracted producer
+  // projection. Identities absent after a detach are fence-retired by the
+  // allocator; surviving identities keep their stable slices.
+  if (skinPaletteAllocator !== null && reconcileSkinFrame) {
+    skinPaletteAllocator.endFrame();
+  }
+
   // Restore the caller's world order after the camera-owner-first extraction.
   for (let wi = 0; wi < worlds.length; wi++) {
     const frame = framesByWorld.get(wi);
@@ -300,6 +356,9 @@ export function extractFrames(
   // AC-04: renderables — concat by worlds[] order, stamp worldId.
   const renderables: RenderableSnapshot[] = [];
   const dispatchEntries: DispatchEntry[] = [];
+  const shadowCasterEntityKeys = new Set<number>();
+  const shadowCasterDrawKeys = new Set<string>();
+  const shadowCasterMembership = new Map<string, ShadowCasterMembership>();
   const visibilitySnapshots: VisibilitySnapshot[] = [];
   const featureVisibilitySnapshots: RenderFeatureWorldVisibilitySnapshot[] = [];
   const hiddenEntityReports: RenderFeatureHiddenEntityReport[] = [];
@@ -330,6 +389,18 @@ export function extractFrames(
     for (const d of f.dispatch) {
       dispatchEntries.push({ ...d, renderableIndex: (d.renderableIndex ?? 0) + base });
     }
+    for (const key of f.shadowCasterEntityKeys) shadowCasterEntityKeys.add(key);
+    for (const key of f.shadowCasterDrawKeys) shadowCasterDrawKeys.add(key);
+    for (const membership of f.shadowCasterMembership ?? []) {
+      const rebased = { ...membership, renderableIndex: membership.renderableIndex + base };
+      const key = gpuDrivenShadowDrawKey(
+        rebased.worldEntity,
+        rebased.materialHandle,
+        rebased.drawItemIndex,
+        rebased.passIndex,
+      );
+      shadowCasterMembership.set(key, rebased);
+    }
   }
 
   // Stable sort dispatch by queue value.
@@ -359,11 +430,14 @@ export function extractFrames(
   // camera may live in different worlds (editor super-composite).
   let directionalCsmConfig: DirectionalCsmConfig | undefined;
   let directionalCsmDirection: Vec3 | undefined;
-  for (const f of succeededFrames) {
-    for (const p of f.lights.point) point.push(p);
-    for (const s of f.lights.spot) spot.push(s);
+  for (let fi = 0; fi < succeededFrames.length; fi += 1) {
+    const f = succeededFrames[fi];
+    const wId = succeededIndices[fi] ?? 0;
+    if (f === undefined) continue;
+    for (const p of f.lights.point) point.push({ ...p, worldId: wId });
+    for (const s of f.lights.spot) spot.push({ ...s, worldId: wId });
     for (const r of f.lights.rect) rect.push(r);
-    for (const ps of f.lights.pointShadow) pointShadow.push(ps);
+    for (const ps of f.lights.pointShadow) pointShadow.push({ ...ps, worldId: wId });
     if (directional === undefined && f.lights.directional !== undefined) {
       directional = f.lights.directional;
       // Carry CSM shadow fields from the first-hit directional's world.
@@ -393,9 +467,10 @@ export function extractFrames(
     if (succeededIndices[fi] === cameraOwner) cameraOwnerFrame = succeededFrames[fi];
     if (succeededIndices[fi] === resourceOwner) resourceOwnerFrame = succeededFrames[fi];
   }
-  const cameras = cameraOwnerFrame !== undefined ? [...cameraOwnerFrame.cameras] : [];
+  const cameras =
+    cameraOwnerFrame?.cameras.map((camera) => ({ ...camera, worldId: cameraOwner })) ?? [];
   const auxiliaryCameras =
-    cameraOwnerFrame !== undefined ? [...cameraOwnerFrame.auxiliaryCameras] : [];
+    cameraOwnerFrame?.auxiliaryCameras.map((camera) => ({ ...camera, worldId: cameraOwner })) ?? [];
   const cubeCameras = cameraOwnerFrame !== undefined ? [...cameraOwnerFrame.cubeCameras] : [];
 
   // bug-20260710-editor-cross-world-shadow: RECOMPUTE directional CSM matrices
@@ -460,6 +535,7 @@ export function extractFrames(
     directionalCsmConfig,
     directionalCsmDirection,
   };
+
   const volumetricFog = resourceOwnerFrame?.volumetricFog;
   const skylight = resourceOwnerFrame?.skylight;
   const skylightCount = resourceOwnerFrame?.skylightCount ?? 0;
@@ -468,7 +544,10 @@ export function extractFrames(
   const fog = resourceOwnerFrame?.fog;
   const fogFailure = resourceOwnerFrame?.fogFailure;
   const environment = resourceOwnerFrame?.environment;
-  const lightProbes = succeededFrames.flatMap((frame) => frame.lightProbes ?? []);
+  const lightProbes = succeededFrames.flatMap((frame, index) => {
+    const worldId = succeededIndices[index] ?? 0;
+    return (frame.lightProbes ?? []).map((probe) => ({ ...probe, worldId }));
+  });
   // User-authored PostProcessParams entities are singleton scene resources, so
   // they come from the resourceOwner world (holistic snapshot selection).
   const postProcessParams = new Map(resourceOwnerFrame?.postProcessParams);
@@ -507,35 +586,30 @@ export function extractFrames(
   const visibilityStats = {
     explicitlyHidden: succeededFrames.reduce((s, f) => s + f.visibilityStats.explicitlyHidden, 0),
   };
+  const materialTextureSources: MaterialTextureSourceStats = {
+    sourceFieldsVisited: 0,
+    numericSharedRefProbes: 0,
+    sourceCacheHits: 0,
+    sourceCacheMisses: 0,
+    producerRoutes: {},
+  };
+  for (const frame of succeededFrames) {
+    const stats = frame.materialTextureSources;
+    if (stats === undefined) continue;
+    materialTextureSources.sourceFieldsVisited += stats.sourceFieldsVisited;
+    materialTextureSources.numericSharedRefProbes += stats.numericSharedRefProbes;
+    materialTextureSources.sourceCacheHits += stats.sourceCacheHits;
+    materialTextureSources.sourceCacheMisses += stats.sourceCacheMisses;
+    for (const [route, count] of Object.entries(stats.producerRoutes)) {
+      materialTextureSources.producerRoutes[route] =
+        (materialTextureSources.producerRoutes[route] ?? 0) + count;
+    }
+  }
   const reflectionProbes = succeededFrames.flatMap((f, index) => {
     const worldId = succeededIndices[index] ?? 0;
     return (f.reflectionProbes ?? []).map((probe) => ({ ...probe, worldId }));
   });
 
-  if (options.renderables !== 'none' && options.renderableEntitiesByWorld === undefined) {
-    options.instanceCollections?.retain(
-      new Set(
-        renderables.flatMap((row) =>
-          row.instances?.collectionId === undefined ? [] : [row.instances.collectionId],
-        ),
-      ),
-    );
-    if (
-      skinPaletteAllocator !== null &&
-      typeof skinPaletteAllocator.retainSliceKeys === 'function'
-    ) {
-      skinPaletteAllocator.retainSliceKeys(
-        new Set(
-          renderables.flatMap((row) =>
-            row.skin === undefined
-              ? []
-              : [`${worlds[row.worldId]?.identity ?? row.worldId}:${row.entityKey}`],
-          ),
-        ),
-      );
-    }
-  }
-
   return {
     cameras,
     auxiliaryCameras,
@@ -547,6 +621,11 @@ export function extractFrames(
       : { volumetricFog: { ...volumetricFog, worldId: resourceOwner } }),
     renderables,
     dispatch: dispatchEntries,
+    shadowCasterEntityKeys,
+    shadowCasterDrawKeys,
+    ...(shadowCasterMembership.size === 0
+      ? {}
+      : { shadowCasterMembership: [...shadowCasterMembership.values()] }),
     skylight,
     skylightCount,
     lightProbes,
@@ -558,6 +637,7 @@ export function extractFrames(
     environmentReady: resourceOwnerFrame !== undefined && environment !== undefined,
     frustumStats,
     visibilityStats,
+    materialTextureSources,
     postProcessParams,
     visibilitySnapshots,
     featureVisibilitySnapshots,
@@ -656,6 +736,14 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   const fogFailure = fogState(world).failure;
   const visibility = context.visibility.hasAnyHiddenIntent ? context.visibility : undefined;
   const skinPaletteAllocator = pipelineState?.skinPaletteAllocator ?? null;
+  const materialTextureSourceStats: MaterialTextureSourceStats = {
+    sourceFieldsVisited: 0,
+    numericSharedRefProbes: 0,
+    sourceCacheHits: 0,
+    sourceCacheMisses: 0,
+    producerRoutes: {},
+  };
+  const materialTextureSourceCache: MaterialTextureSourceCache = new Map();
 
   const directionalLightQuery = world.query({ read: [DirectionalLight] }).unwrap();
 
@@ -673,7 +761,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   const worldInternal = createWorldInternalView(world);
   let volumetricFog = extractVolumeSnapshot(world, assets, worldInternal);
 
-  const cameraRoles = selectCameraRoles(world);
+  const cameraRoles = selectCameraRoles(world, context.cameraEntityKey);
   const cameras = [...cameraRoles.display];
   const auxiliaryCameras = cameraRoles.auxiliary;
   const cubeCameras = collectCubeCameraSnapshots(world);
@@ -784,6 +872,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     pointSnapshots.push({
       kind: 'point',
       entity: entityId,
+      worldId: context.worldId,
       position,
       color: vec3.create(
         (p.color[0] ?? 1) * intensity,
@@ -979,6 +1068,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     spotSnapshots.push({
       kind: 'spot',
       entity: row.entity,
+      worldId: context.worldId,
       // D-6: position reflects world transform; direction stays sourced
       // from SpotLight.direction (NOT rotated by the parent).
       position,
@@ -1274,10 +1364,13 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
       }
       pointShadowSnapshots.push({
         entity: row.entity,
+        worldId: context.worldId,
         position: lightPos,
         mapSize,
         nearPlane,
         farPlane,
+        depthBias: ps.depthBias,
+        normalBias: ps.normalBias,
         shadowAtlasLayer: layer,
         shadowMatrices: packed,
       });
@@ -1329,6 +1422,12 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     directionalCsmDirection,
   };
 
+  // A caster may be outside the display camera while still contributing to a
+  // light's shadow map. Keep the light-space visibility projection alongside
+  // camera culling so the direct extraction path and persistent composition
+  // retain the same shadow-only rule.
+  const shadowFrusta = cullMode === 'none' ? [] : buildShadowFrusta(lights);
+
   // feat-20260520-skylight-ibl-cubemap M4 / t26+t27: query Skylight entities.
   // First archetype hit wins (mirrors DirectionalLight pattern); multi-Skylight
   // warn in record stage (t27) uses skylightCount.
@@ -1384,6 +1483,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     const transform = row.get(GlobalTransform);
     lightProbes.push({
       identity: String(row.entity),
+      worldId: context.worldId,
       position: [transform.world[12] ?? 0, transform.world[13] ?? 0, transform.world[14] ?? 0],
       radius: probe.radius,
       irradiance: new Float32Array(probe.irradiance),
@@ -1459,22 +1559,27 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           directionalDirection[1] ?? 0,
           directionalDirection[2] ?? 0,
         );
+  const sunIntensity = directional?.intensity ?? 0;
+  const sunColor =
+    sunIntensity > 0 && directional !== undefined
+      ? ([
+          (directional.color[0] ?? 0) / sunIntensity,
+          (directional.color[1] ?? 0) / sunIntensity,
+          (directional.color[2] ?? 0) / sunIntensity,
+        ] as [number, number, number])
+      : ([0, 0, 0] as [number, number, number]);
   const sun =
-    directional === undefined || directionalLength <= 1e-6
+    directional === undefined || directional.entity === undefined || directionalLength <= 1e-6
       ? []
       : [
           {
-            entityKey: 0,
+            entityKey: directional.entity,
             direction: [
               -(directionalDirection?.[0] ?? 0) / directionalLength,
               -(directionalDirection?.[1] ?? 0) / directionalLength,
               -(directionalDirection?.[2] ?? 0) / directionalLength,
             ] as [number, number, number],
-            color: [
-              directional.color[0] ?? 0,
-              directional.color[1] ?? 0,
-              directional.color[2] ?? 0,
-            ] as [number, number, number],
+            color: sunColor,
             intensity: directional.intensity,
           },
         ];
@@ -1561,18 +1666,26 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // (plan-strategy D-3). Entries built per-entity per-pass inside the
   // archetype walk, then sorted by queue at the end.
   let dispatch: DispatchEntry[] = [];
+  const shadowMembershipEntries: ShadowCasterMembership[] = [];
   // Keep the derived material snapshot and its resolved passes local to this
   // extraction. Shared handles are immutable inputs for the frame, while
   // dispatch entries still need to be rebuilt for each entity.
   const materialSnapshotCache: MaterialSnapshotCache = new Map();
+  // A collection can be associated with more than one entity. Snapshot its
+  // renderer-owned bytes once per extracted frame so culling and every
+  // submission lane consume the same detached revision without repeat copies.
+  const instanceSnapshotCache = new Map<
+    InstanceCollectionId,
+    ReturnType<InstanceCollectionStore['snapshot']>
+  >();
   const skinnedMaterialSnapshotCache: MaterialSnapshotCache = new Map();
   // tweak-20260611 M1: MeshRenderer renderable archetype walk routes
   // through one World-owned Query. K-2 sniffing scheme B
   // (`row.get(X) !== undefined` edge sniff) replaces the prior
   // `arch.components.some` row-internal back-door. K-3 invariant: the
   // variable-length array reads (`MeshRenderer.materials`, SpriteInstances
-  // arrays) still flow through `_getArrayView`; explicit Instances bytes also come
-  // from World, before projection into renderer-owned snapshots.
+  // arrays) still flow through `_getArrayView`; explicit Instances bytes come
+  // from the renderer-owned collection store.
   //
   // archVersion remains the content fingerprint for SpriteInstances' managed
   // arrays; explicit Instances use the collection revision below and never
@@ -1643,7 +1756,8 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     // are not materialised merely to answer a boolean question.
     const hasTransform = row.has(Transform);
     const meshFilter = row.get(MeshFilter);
-    const hasInstances = row.has(Instances);
+    const instancesData = row.get(Instances);
+    const hasInstances = instancesData !== undefined;
     const skin = row.get(Skin);
     const morphWeightsView = worldInternal._getArrayView(row.entity, MorphWeights, 'weights');
     const hasMeshFilter = meshFilter !== undefined;
@@ -1760,9 +1874,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         () => 'renderer-override',
       );
       let materialBindingDiagnostics: MeshMaterialBindingDiagnostic[] = [];
-      let gpuDrivenSubmeshes: readonly MeshAsset['submeshes'][number][] = [];
-      let gpuDrivenIndexed = false;
-      let gpuDrivenGeometry: GpuDrivenGeometryReceipt | undefined;
+      let gpuDrivenMesh: MeshAsset | undefined;
 
       // Resolve instance overrides against mesh-owned slot defaults once.
       const fAssetHandleVal = fAssetHandle;
@@ -1777,19 +1889,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         if (meshRes.ok && meshRes.value.kind === 'mesh') {
           const meshAsset = meshRes.value as MeshAsset;
           const guid = (meshRes.value as { guid?: string }).guid ?? '<no-guid>';
-          gpuDrivenSubmeshes = meshAsset.submeshes;
-          gpuDrivenIndexed = meshAsset.indices !== undefined;
-          const layoutProjection = deriveVertexLayoutProjection(meshAsset.attributes);
-          gpuDrivenGeometry = {
-            identity: `${guid}:${layoutProjection.digest}`,
-            vertexInputs: layoutProjection.attributes.map((attribute) => ({
-              semantic: attribute.key,
-              location: attribute.shaderLocation,
-              format: attribute.format,
-            })),
-            topology: meshAsset.submeshes[0]?.topology ?? 'triangle-list',
-            indexed: gpuDrivenIndexed,
-          };
+          gpuDrivenMesh = meshAsset;
           // extractFrames is also a public read path and can run before the
           // Renderer.draw pre-render stage. GlyphText proves the derived mesh
           // owns exactly one Default slot; arbitrary meshes still fail closed
@@ -2241,6 +2341,16 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                     ? assets.materialShaderTextureFieldNames(firstPassShader)
                     : undefined,
               ) ?? BUILTIN_USER_REGION_TEXTURE_FIELDS;
+            const authoredTextureFields = collectAuthoredMaterialTextureFields(
+              resolved.values,
+              firstPassShader,
+              materialParamSchema.length > 0 ? materialParamSchema : undefined,
+              assets,
+            );
+            const authoredSamplerFields = collectAuthoredMaterialSamplerFields(
+              resolved.values,
+              authoredTextureFields,
+            );
             const textureHandles = new Map<string, Handle<'TextureAsset', 'shared'>>();
             const videoTextureFields = new Map<string, Handle<'VideoAsset', 'shared'>>();
             for (const field of userRegionFields) {
@@ -2274,7 +2384,15 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               pv.occlusionTexture,
             );
             const textureCoordinates = collectMaterialTextureCoordinates(pv);
-            const textureSources = collectMaterialTextureSources(pv, world);
+            const textureSources = collectMaterialTextureSources(
+              pv,
+              world,
+              materialTextureSourceFields(
+                materialParamSchema.length > 0 ? materialParamSchema : undefined,
+              ),
+              materialTextureSourceStats,
+              materialTextureSourceCache,
+            );
             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
@@ -2370,8 +2488,15 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               renderState: pipelineRenderState(allPasses[0]?.renderState),
               paramSnapshot: paramSnap,
               ...(materialParamSchema.length > 0 && { materialParamSchema }),
+              standardTextureMask: materialStandardTextureMask(
+                resolved.parameters,
+                firstPassShader,
+                pv,
+              ),
               ...(textureCoordinates.size > 0 && { textureCoordinates }),
+              ...(authoredTextureFields === undefined ? {} : { authoredTextureFields }),
               ...(samplerHandles.size > 0 && { samplerHandles }),
+              ...(authoredSamplerFields === undefined ? {} : { authoredSamplerFields }),
               ...(textureHandles.size > 0 && { textureHandles }),
               ...(textureSources.size > 0 && { textureSources }),
               ...(videoTextureFields.size > 0 && { videoTextureFields }),
@@ -2497,7 +2622,13 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         // T-21 placeholder ({0,0} discriminator-only sentinel) with full
         // resolve / validate / write chain (D-9 reset already fired at
         // extractFrame entry; per-entity allocate + writeJointPalette here).
-        let skinSlice: SkinPaletteSlice | undefined;
+        let skinSlice: SkinPaletteReceipt | undefined;
+        const skinIdentity = hasSkin ? skinPaletteIdentity(world, entity) : undefined;
+        const releaseSkinIdentity = (): void => {
+          if (skinIdentity !== undefined) {
+            skinPaletteAllocator?.releasePersistentSlice(skinIdentity);
+          }
+        };
         if (hasSkin) {
           const skeletonHandleRaw = skinSkeletonView;
           if (
@@ -2512,7 +2643,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                 severity: Severity.Error,
                 systemName: 'RenderSystem.extract (skin-instances-coexist)',
               });
-
+              releaseSkinIdentity();
               continue;
             }
             // (a) Resolve skeleton asset; on failure -> skeleton-resolve-failed.
@@ -2523,13 +2654,17 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                 severity: Severity.Error,
                 systemName: 'RenderSystem.extract (skeleton-resolve-failed)',
               });
+              releaseSkinIdentity();
               continue;
             }
             const skeleton = skeletonRes.value;
             // (b) Reuse the Skin row already read for its skeleton handle;
             // the old path repeated a second whole-row world.get here.
             const skinJoints = skin?.joints;
-            if (skinJoints === undefined) continue;
+            if (skinJoints === undefined) {
+              releaseSkinIdentity();
+              continue;
+            }
             const jointsLength = skinJoints.length;
             if (jointsLength !== skeleton.jointCount) {
               worldInternal._routeError(
@@ -2539,6 +2674,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                   systemName: 'RenderSystem.extract (joint-count-mismatch)',
                 },
               );
+              releaseSkinIdentity();
               continue;
             }
             // (c) Resolve only each joint's GlobalTransform.world column. The
@@ -2569,6 +2705,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                 severity: Severity.Error,
                 systemName: 'RenderSystem.extract (joint-entity-dangling)',
               });
+              releaseSkinIdentity();
               continue;
             }
             // (d) Slice the IBM flat Float32Array into per-joint Float32Arrays.
@@ -2578,29 +2715,25 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             for (let jIdx = 0; jIdx < skeleton.jointCount; jIdx++) {
               ibms[jIdx] = ibmFlat.subarray(jIdx * 16, jIdx * 16 + 16);
             }
-            // (e) Allocate slice + write palette via the allocator (D-9 reset
-            // already fired at extractFrame entry). When the pipelineState
-            // surface is absent (test fixtures that pass undefined) the
-            // hasSkin segment is skipped silently — bind-pose equivalent.
+            // (e) Reuse the persistent producer-owned slice for this stable
+            // world/entity identity. Missing producer bounds remain explicit:
+            // the receipt carries no invented bind-pose AABB and the shadow
+            // admission lane can route the caster to CPU.
             if (skinPaletteAllocator !== null) {
-              // Keep the narrow extraction seam compatible with older test or
-              // host-owned allocator doubles while the real renderer uses the
-              // stable-key path. The fallback is frame-local and therefore
-              // cannot affect production allocators that implement the new
-              // method.
-              const slice =
-                typeof skinPaletteAllocator.allocateSliceFor === 'function'
-                  ? skinPaletteAllocator.allocateSliceFor(
-                      `${world.identity}:${entity}`,
-                      skeleton.jointCount,
-                    )
-                  : skinPaletteAllocator.allocateSlice(skeleton.jointCount);
-              skinPaletteAllocator.writeJointPalette(slice, ibms, jointWorlds);
-              skinSlice = {
-                jointCount: slice.jointCount,
-                byteOffset: slice.byteOffset,
-                buffer: slice.buffer,
-              };
+              const identity = skinPaletteIdentity(world, entity);
+              const generation = (skeletonHandleRaw >>> 0) ^ skeleton.jointCount;
+              const bounds = hasFiniteOrderedLocalAabb(skeleton.bounds)
+                ? new Float32Array(skeleton.bounds)
+                : undefined;
+              skinPaletteAllocator.observePersistentJoints(identity, ibms, jointWorlds);
+              const receipt = skinPaletteAllocator.allocatePersistentSlice({
+                identity,
+                generation: generation >>> 0,
+                jointCount: skeleton.jointCount,
+                ...(bounds === undefined ? {} : { bounds }),
+              });
+              skinPaletteAllocator.writePersistentJointPalette(receipt, ibms, jointWorlds);
+              skinSlice = receipt;
             }
           }
         }
@@ -2609,9 +2742,12 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         // projection. Do not publish a renderable or its staged dispatch when
         // palette extraction was unavailable; the record stage must never
         // reinterpret a skinned vertex stream through an ordinary mesh group.
-        if (materialSnap.materialShaderId === 'forgeax::pbr-skin' && skinSlice === undefined) {
-          pendingDispatch.length = 0;
-          continue;
+        if (skinSlice === undefined && hasSkin) {
+          releaseSkinIdentity();
+          if (materialSnap.materialShaderId === 'forgeax::pbr-skin') {
+            pendingDispatch.length = 0;
+            continue;
+          }
         }
 
         // feat-20260601 D-3: read the resolved world mat4 (propagateTransforms
@@ -2622,7 +2758,10 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         // tweak-20260611 M1 / K-3: `_getArrayView` call survives untouched;
         // only the `entity` source switched to `bundle.Entity.self[i]`.
         const worldView = worldInternal._getArrayView(entity, GlobalTransform, 'world');
-        if (worldView === undefined) continue;
+        if (worldView === undefined) {
+          releaseSkinIdentity();
+          continue;
+        }
         const worldMat = new Float32Array(worldView);
         const transformSnap: TransformSnapshot = { world: worldMat };
         // feat-20260608 M5 amend / w11-a: per-submesh `materials[]` array
@@ -2654,6 +2793,8 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                         ...context.materialContext,
                         geometry: hasSkin ? 'skinned' : context.materialContext.geometry,
                       },
+                  materialTextureSourceStats,
+                  materialTextureSourceCache,
                 ),
             );
           }
@@ -2778,7 +2919,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             lods = meshAsset.lods;
             lodHysteresis = meshAsset.lodHysteresis;
             morph = morphSnapshotFor(meshAsset, morphWeightsView);
-            const meshAabb = meshAsset.aabb;
+            const meshAabb = skinSlice?.bounds ?? meshAsset.aabb;
             // Morph targets can expand the authored bounds. Keep the
             // specialized lane conservative until a target-aware bounds
             // projection is available; a false-positive draw is preferable
@@ -2805,7 +2946,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           pointsLinesComponent === undefined
             ? undefined
             : ({
-                worldId: 0,
+                worldId: context.worldId,
                 entityKey: entity,
                 component: pointsLinesComponent,
                 meshHandle: assetHandleRaw,
@@ -2828,30 +2969,48 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         // make the cull and draw disagree within one frame).
         let instancesSnap: InstancesSnapshot | undefined;
         if (hasInstances) {
-          const transforms =
-            worldInternal._getArrayView(entity, Instances, 'transforms') ?? new Float32Array();
-          if (transforms.length % 16 !== 0) {
-            worldInternal._routeError(
-              new InstanceTransformsStrideMismatchError(transforms.length),
-              {
-                severity: Severity.Error,
-                systemName: 'RenderSystem.extract (Instances stride)',
-              },
-            );
+          const collectionId = instancesData?.collectionId as InstanceCollectionId | undefined;
+          let collectionResult =
+            collectionId !== undefined ? instanceSnapshotCache.get(collectionId) : undefined;
+          if (collectionResult === undefined) {
+            collectionResult =
+              collectionId !== undefined && collectionId > 0 && instanceCollections !== undefined
+                ? instanceCollections.snapshot(collectionId)
+                : err(
+                    new InstanceCollectionError(
+                      'instance-collection-invalid',
+                      'Instances.collectionId references a live renderer-owned collection',
+                      'create the collection through renderer.instances before attaching Instances',
+                      {
+                        operation: 'inspect',
+                        expected: 'a positive collectionId with a live renderer owner',
+                        actual: Number(collectionId ?? 0),
+                        ...(collectionId === undefined ? {} : { collectionId }),
+                      },
+                    ),
+                  );
+            if (collectionId !== undefined)
+              instanceSnapshotCache.set(collectionId, collectionResult);
+          }
+          if (collectionResult === undefined) continue;
+          if (!collectionResult.ok) {
+            worldInternal._routeError(collectionResult.error, {
+              severity: Severity.Error,
+              systemName: 'RenderSystem.extract (Instances collection)',
+            });
             continue;
           }
-          const projected = instanceCollections?.project(world, entity, transforms);
           instancesSnap = {
-            transforms: projected?.transforms ?? new Float32Array(transforms),
-            instanceCount: transforms.length / 16,
+            transforms: collectionResult.value.transforms,
+            instanceCount: collectionResult.value.count,
+            collectionId: collectionResult.value.collectionId,
+            revision: collectionResult.value.revision,
+            capacity: collectionResult.value.capacity,
+            dirtyRanges: collectionResult.value.dirtyRanges,
             cacheKey: entity,
-            archVersion: projected === undefined ? fingerprintNumericArray(transforms) : 0,
-            ...(projected === undefined
-              ? {}
-              : {
-                  collectionId: projected.collectionId,
-                  revision: projected.revision,
-                }),
+            // Explicit collection revisions supersede ECS archetype content
+            // hashes; retain zero as the legacy sprite-only field value.
+            archVersion: 0,
           };
         }
 
@@ -2865,7 +3024,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           materials: materialsArr,
           materialBindingSources,
           materialBindingDiagnostics,
-          worldId: 0,
+          worldId: context.worldId,
           entityKey: entity,
           ...(authorVisible ? {} : { authorVisible: false }),
           ...(skinSlice !== undefined ? { skin: skinSlice } : {}),
@@ -2878,34 +3037,27 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           ...(pointsLines !== undefined ? { pointsLines } : {}),
         };
         const gpuDrivenDraws = buildGpuDrivenDraws({
-          submeshes: gpuDrivenSubmeshes,
-          indexed: gpuDrivenIndexed,
+          mesh: gpuDrivenMesh,
           materials: materialsArr,
           fallbackMaterial: materialSnap,
-          ...(gpuDrivenGeometry === undefined || getMaterialShaderArtifact === undefined
+          baseSnapshot: baseRenderable,
+          ...(getMaterialShaderArtifact === undefined ? {} : { getMaterialShaderArtifact }),
+          ...(lods === undefined
             ? {}
             : {
-                prepare(draw, drawMaterial) {
-                  const materialShaderId = drawMaterial.materialShaderId;
-                  if (materialShaderId === undefined) return undefined;
-                  const artifact = getMaterialShaderArtifact(materialShaderId);
-                  if (artifact?.receipt === undefined) return undefined;
-                  const geometry: GpuDrivenGeometryReceipt = {
-                    ...gpuDrivenGeometry,
-                    topology: draw.topology,
-                    indexed: draw.kind === 'indexed',
-                  };
-                  const result = resolvePreparedGpuDrivenDraw({
-                    snapshot: { ...baseRenderable, material: drawMaterial },
-                    artifact,
-                    geometry,
-                    generation: artifact.receipt.generation,
-                    draw,
-                  });
-                  return result.ok ? result.value : undefined;
-                },
+                lodMeshes: lods.map((lod) => {
+                  const lower = assets?.lookup<Asset>(lod.mesh);
+                  return lower?.kind === 'mesh' ? lower : undefined;
+                }),
               }),
         });
+        for (const draw of gpuDrivenDraws) {
+          if (draw.preparationError === undefined) continue;
+          worldInternal._routeError(draw.preparationError, {
+            severity: Severity.Error,
+            systemName: `RenderSystem.extract (gpu-driven-preparation:${draw.preparationError.code})`,
+          });
+        }
         const renderable =
           morph === undefined && gpuDrivenDraws.length > 0
             ? { ...baseRenderable, gpuDrivenDraws }
@@ -2975,13 +3127,81 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             }
             if (!visible) {
               frustumCulled += 1;
-              continue;
+              const shadowVisible =
+                shadowFrusta.length > 0 &&
+                pendingDispatch.some((entry) => entry.tags.LightMode === 'ShadowCaster') &&
+                shadowFrusta.some((lightPlanes) =>
+                  frustum.intersectsBox(lightPlanes, worldAabb as box3.Box3Like),
+                );
+              if (!shadowVisible) continue;
+              // Shadow-only renderables stay in the detached snapshot for the
+              // depth passes, but must not leak their forward/transparent
+              // dispatch entries into the main camera submission.
+              for (let i = pendingDispatch.length - 1; i >= 0; i -= 1) {
+                if (pendingDispatch[i]?.tags.LightMode !== 'ShadowCaster') {
+                  pendingDispatch.splice(i, 1);
+                }
+              }
             }
           }
         }
 
+        const localShadowMembershipEntries: ShadowCasterMembership[] = [];
+        if (gpuDrivenMesh !== undefined) {
+          const worldEntity = worldEntityKey(context.worldId, entity);
+          for (const [drawItemIndex, submesh] of gpuDrivenMesh.submeshes.entries()) {
+            if (submesh.topology !== 'triangle-list' && submesh.topology !== 'triangle-strip') {
+              continue;
+            }
+            const material = materialsArr[submesh.materialSlot] ?? materialSnap;
+            const materialHandle = material.materialHandle ?? -1;
+            const shadowEntries = pendingDispatch.filter(
+              (entry) =>
+                entry.tags.LightMode === 'ShadowCaster' && entry.materialHandle === materialHandle,
+            );
+            const draw = renderable.gpuDrivenDraws?.find(
+              (candidate, compactIndex) =>
+                gpuDrivenSourceDrawItemIndex(candidate, compactIndex) === drawItemIndex,
+            );
+            const cpuReason = shadowCasterCpuReason(
+              material,
+              draw,
+              shadowEntries,
+              morph,
+              skinSlice,
+            );
+            for (const entry of shadowEntries) {
+              const membership: ShadowCasterMembership = {
+                worldEntity,
+                renderableIndex: renderables.length,
+                drawItemIndex,
+                materialHandle,
+                passIndex: entry.passIndex,
+                ...(entry.materialShaderId === undefined
+                  ? {}
+                  : { materialShaderId: entry.materialShaderId }),
+                ...(entry.renderState === undefined ? {} : { renderState: entry.renderState }),
+                ...(cpuReason === undefined ? {} : { cpuReason }),
+              };
+              shadowMembershipEntries.push(membership);
+              localShadowMembershipEntries.push(membership);
+            }
+          }
+        }
+        const shadowCasterPasses = localShadowMembershipEntries.map((membership) => ({
+          drawItemIndex: membership.drawItemIndex,
+          materialHandle: membership.materialHandle,
+          passIndex: membership.passIndex,
+          ...(membership.materialShaderId === undefined
+            ? {}
+            : { materialShaderId: membership.materialShaderId }),
+          ...(membership.renderState === undefined ? {} : { renderState: membership.renderState }),
+          ...(membership.cpuReason === undefined ? {} : { cpuReason: membership.cpuReason }),
+        }));
+        const renderableWithShadowPasses =
+          shadowCasterPasses.length === 0 ? renderable : { ...renderable, shadowCasterPasses };
         flushPendingDispatch(pendingDispatch);
-        renderables.push(renderable);
+        renderables.push(renderableWithShadowPasses);
       }
 
       // feat-20260520-2d-sprite-layer-mvp M-3 / w22 + w25: finalise the
@@ -2998,6 +3218,28 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // M3 / w26: sort dispatch entries by queue (ascending, stable sort)
   // per plan-strategy D-3.
   dispatch = sortDispatchByQueue(dispatch);
+  const shadowCasterEntityKeys = new Set<number>();
+  const shadowCasterDrawKeys = new Set<string>();
+  const shadowCasterMembership = new Map<string, ShadowCasterMembership>();
+  for (const entry of dispatch) {
+    if (entry.tags.LightMode !== 'ShadowCaster') continue;
+    const renderable = renderables[entry.renderableIndex];
+    if (renderable !== undefined) {
+      const worldEntity = worldEntityKey(renderable.worldId, renderable.entityKey);
+      shadowCasterEntityKeys.add(worldEntity);
+    }
+  }
+  for (const membership of shadowMembershipEntries) {
+    const key = gpuDrivenShadowDrawKey(
+      membership.worldEntity,
+      membership.materialHandle,
+      membership.drawItemIndex,
+      membership.passIndex,
+    );
+    shadowCasterDrawKeys.add(key);
+    shadowCasterMembership.set(key, membership);
+    shadowCasterEntityKeys.add(membership.worldEntity);
+  }
 
   // D-1: collect PostProcessParams entities into Map<shaderId, Uint8Array>.
   // Last-one-wins when multiple entities bear the same shader id (mirrors
@@ -3041,6 +3283,11 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     ...(volumetricFog === undefined ? {} : { volumetricFog }),
     renderables,
     dispatch,
+    shadowCasterEntityKeys,
+    shadowCasterDrawKeys,
+    ...(shadowCasterMembership.size === 0
+      ? {}
+      : { shadowCasterMembership: [...shadowCasterMembership.values()] }),
     skylight,
     skylightCount,
     lightProbes,
@@ -3050,6 +3297,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     ...(fogFailure === undefined ? {} : { fogFailure }),
     frustumStats: { culled: frustumCulled, total: frustumTotal },
     visibilityStats: { explicitlyHidden: explicitlyHidden.size },
+    materialTextureSources: materialTextureSourceStats,
     postProcessParams,
     visibilitySnapshots: [context.visibility],
     featureVisibilitySnapshots: [{ world, snapshot: context.visibility }],
@@ -3057,17 +3305,18 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   };
 }
 
+/** Immutable author-independent default; extraction retains its producer identity. */
+const DEFAULT_MATERIAL_SNAPSHOT: MaterialSnapshot = Object.freeze({
+  baseColor: vec3.create(0.5, 0.5, 0.5),
+  metallic: 0,
+  roughness: 1,
+  materialHandle: 0,
+});
+
 export function defaultMaterialSnapshot(materialHandle = 0): MaterialSnapshot {
-  // Mid-grey unlit fallback (D-Q7 case B + extract-stage missing-spec),
-  // matching the pre-w6 visual outcome where the record stage's force-cast
-  // read of `firstMaterial.baseColorTexture` returned undefined and the
-  // unlit fallback shader was selected.
-  return {
-    baseColor: vec3.create(0.5, 0.5, 0.5),
-    metallic: 0,
-    roughness: 1,
-    materialHandle,
-  };
+  return materialHandle === 0
+    ? DEFAULT_MATERIAL_SNAPSHOT
+    : { ...DEFAULT_MATERIAL_SNAPSHOT, materialHandle };
 }
 
 function identityProjection(): Float32Array {