@forgeax/engine-render 0.1.23 → 0.1.24

package/src/render-system-extract.ts

@@ -103,32 +103,18 @@ import {
   walkMaterialPassesOverSharedRefs,
 } from '@forgeax/engine-assets-runtime';
 import type { Component, ComponentSchema, EntityHandle, Query, World } from '@forgeax/engine-ecs';
-import {
-  InstanceTransformsStrideMismatchError,
-  readRenderArrayView,
-  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 { readRenderArrayView, routeWorldError } from '@forgeax/engine-ecs/projection';
+import { type Mat4, mat4, type Vec3, vec3 } from '@forgeax/engine-math';
 import { AssetGuid, type AssetGuid as AssetGuidBytes } from '@forgeax/engine-pack/guid';
 import { RhiError } from '@forgeax/engine-rhi';
-import { GlobalTransform, MorphWeights, Transform } from '@forgeax/engine-scene';
-import type { MaterialShaderArtifact } from '@forgeax/engine-shader';
+import { GlobalTransform, Transform } from '@forgeax/engine-scene';
 import {
-  JointCountMismatchError,
-  JointEntityDanglingError,
-  SkeletonResolveFailedError,
-  Skin,
-  SkinInstancesCoexistForbiddenError,
-} from '@forgeax/engine-skinning';
+  type MaterialShaderArtifact,
+  STANDARD_PIPELINE_PARAM_SCHEMA,
+} from '@forgeax/engine-shader';
 import type {
   Asset,
   Handle,
-  IesProfileAsset,
   MaterialAsset,
   MaterialColorParameterSchema,
   MaterialParameter,
@@ -136,115 +122,61 @@ import type {
   MaterialRenderState,
   MaterialTextureCoordinates,
   MaterialTextureValue,
-  MeshAsset,
   MeshLodLevel,
   ParamSchemaEntry,
   PrimitiveTopology,
-  SkeletonAsset,
   TextureAsset,
 } from '@forgeax/engine-types';
 import {
-  ASSET_ERROR_HINTS,
-  AssetError,
   derive,
-  handleSlot,
   materialGuidText,
   materialValuesToLinearRuntime,
   toShared,
 } from '@forgeax/engine-types';
 import {
-  Atmosphere,
   antialiasFromF32,
   bloomEnabledFromF32,
   Camera,
   CubeCamera,
   cameraProjectionFromF32,
   cubeCameraUpdateIntentFromF32,
-  DirectionalLight,
   Fog,
-  Instances,
-  Layer,
-  LightProbe,
-  Lines,
-  MeshFilter,
-  MeshRenderer,
   MotionBlur,
-  PointLight,
-  PointLightShadow,
-  Points,
-  PostProcessParams,
-  pointShapeFromU32,
-  RectAreaLight,
   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,
-  type LightValidationError,
-  validateDirectionalLightData,
-  validateLightProbeData,
-  validateRectAreaLightData,
-} from './components/light-helpers';
+import type { DirectionalShadowQuality } from './components/directional-shadow-filter';
+import type { LightValidationError } from './components/light-helpers';
 import { selectEnvironment } from './environment/frame';
-import {
-  MaterialSkinAttrMissingError,
-  ShadowInvalidConfigError,
-  SkinMaterialMismatchError,
-} from './errors/render';
+import { ShadowInvalidConfigError } from './errors/render';
 import {
   type DirectionalShadowCascadeFit,
   projectDirectionalShadow,
 } from './extract/directional-shadow-projection';
 import type {
-  EnvironmentCandidate,
   EnvironmentFrame,
   FogCandidate,
   FogFrame,
   FogSelectionFailure,
 } from './extract/environment';
-import { buildGpuDrivenDraws, resolvePreparedGpuDrivenDraw } from './extract/gpu-driven';
 import { resolveVisibility, 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 { deriveInstancesUnionBounds } from './instances-derived-bounds';
-import {
-  type MeshMaterialBindingDiagnostic,
-  type MeshMaterialBindingSource,
-  resolveMeshMaterialBindings,
+import type {
+  MeshMaterialBindingDiagnostic,
+  MeshMaterialBindingSource,
 } from './mesh-material-bindings';
-import { isStandardPbrMaterialShader } from './pbr-pipeline';
-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 { isCanonicalStandardPbrMaterialShader, isStandardPbrMaterialShader } from './pbr-pipeline';
+import type { PointsLinesRetainedSnapshot } from './points-lines/snapshot';
 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 type { CameraSnapshot, CubeCameraSnapshot } from './render-contract';
+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 { RenderTarget, RenderTargetTextureSource } from './targets/contracts';
@@ -530,8 +462,8 @@ export type LightSnapshot =
  * ExtractedLights — three-bucket output of the extractFrame three-query
  * union (M2 / w16 / AC-03). Plan-strategy section 3.1 EXT node:
  *   - `directional` — at most one (record-stage N>1 fail-fast lands in M3)
- *   - `point[]` / `spot[]` / `rect[]` — authored local-light snapshots; the
- *     record stage preserves this order in one bounded Cluster corpus
+ *   - `point[]` — first-slice cap of 4 enforced at record stage (M3)
+ *   - `spot[]`  — first-slice cap of 4 enforced at record stage (M3)
  * `directionalCount` exposes the raw count of DirectionalLight entities the
  * extract observed (so the record stage can fire `render-system-multi-light`
  * when N>1 without re-running the query). M3 / w19 will widen this with
@@ -974,10 +906,8 @@ export interface MaterialSnapshot {
   readonly baseColor: Vec3;
   readonly metallic: number;
   readonly roughness: number;
-  readonly clearcoat?: number | undefined;
-  readonly clearcoatRoughness?: number | undefined;
-  /** Authored Standard PBR specular tint in linear runtime color space. */
-  readonly specularTint?: readonly [number, number, number] | undefined;
+  /** Authored Standard PBR specular color in linear runtime color space. */
+  readonly specularColor?: readonly [number, number, number] | undefined;
   /**
    * Schema-driven material shader identifier (feat-20260523 M4-T05).
    * Populated when the material asset uses the schema-driven path
@@ -1108,7 +1038,7 @@ export interface MaterialSnapshot {
   readonly transparent?: boolean | undefined;
 }
 
-interface MaterialCacheChainIdentity {
+export interface MaterialCacheChainIdentity {
   readonly asset: MaterialAsset;
   readonly parentGuid: string | undefined;
 }
@@ -1127,6 +1057,20 @@ export interface MaterialSnapshotCacheEntry {
 export type MaterialSnapshotCache = Map<number, MaterialSnapshotCacheEntry>;
 export type MaterialSnapshotCachesByWorld = WeakMap<World, MaterialSnapshotCache>;
 
+export function gpuDrivenMaterialResourceClass(material: MaterialSnapshot): string {
+  const textures = [...(material.textureHandles?.entries() ?? [])]
+    .map(([name, handle]) => [name, Number(handle)] as const)
+    .sort(([left], [right]) => left.localeCompare(right));
+  const samplers = [...(material.samplerHandles?.entries() ?? [])]
+    .map(([name, handle]) => [name, Number(handle)] as const)
+    .sort(([left], [right]) => left.localeCompare(right));
+  return JSON.stringify({
+    textures,
+    samplers,
+    video: [...(material.videoTextureFields?.keys() ?? [])].sort(),
+  });
+}
+
 // === DispatchEntry — M3 / w26 single dispatch list (feat-20260526-material-asset-multipass-renderstate) ===
 //
 // Plan-strategy D-3: single dispatch list sorted by queue value,
@@ -1175,13 +1119,13 @@ export function sortDispatchByQueue<E extends { readonly queue: number }>(
   return entries.slice().sort((a, b) => a.queue - b.queue);
 }
 
-const DEFAULT_FORWARD_PASS: MaterialPass = {
+export const DEFAULT_FORWARD_PASS: MaterialPass = {
   name: 'forward',
   program: { module: 'forgeax::default-unlit', vertexEntry: 'vs_main', fragmentEntry: 'fs_main' },
   renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
 };
 
-function appendMaterialDispatchEntries(
+export function appendMaterialDispatchEntries(
   pendingDispatch: DispatchEntry[],
   passes: readonly MaterialPass[],
   entity: EntityHandle,
@@ -1359,7 +1303,7 @@ type ArrayFieldView = ArrayLike<number>;
  * receives a detached array snapshot and routes failures through the same
  * projection owner.
  */
-type WorldInternalView = {
+export type WorldInternalView = {
   _routeError(error: unknown, ctx: RenderErrorContext): void;
   _getArrayView<N extends string, S extends ComponentSchema>(
     entity: EntityHandle,
@@ -1368,9 +1312,9 @@ type WorldInternalView = {
   ): ArrayFieldView | undefined;
 };
 
-const Severity = Object.freeze({ Error: 'error', Warning: 'warning' } as const);
+export const Severity = Object.freeze({ Error: 'error', Warning: 'warning' } as const);
 
-function createWorldInternalView(world: World): WorldInternalView {
+export function createWorldInternalView(world: World): WorldInternalView {
   return {
     _routeError(error, ctx) {
       routeWorldError(world, error, { systemName: ctx.systemName });
@@ -1381,7 +1325,10 @@ function createWorldInternalView(world: World): WorldInternalView {
   };
 }
 
-function resolveCameraTarget(world: World, raw: number | undefined): RenderTarget | undefined {
+export 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)),
@@ -1395,11 +1342,11 @@ function resolveCameraTarget(world: World, raw: number | undefined): RenderTarge
  * (cross-worktree shader-late-register, plan R-4) so a built-in material still
  * resolves its user-region textures. Mirrors `derive(default-standard-pbr).textureFieldNames`.
  */
-const BUILTIN_USER_REGION_TEXTURE_FIELDS: readonly string[] = [
+export const BUILTIN_USER_REGION_TEXTURE_FIELDS: readonly string[] = [
   'baseColorTexture',
   'metallicRoughnessTexture',
   'normalTexture',
-  'specularTintTexture',
+  'specularColorTexture',
   'emissiveTexture',
   'occlusionTexture',
   'transmissionTexture',
@@ -1408,7 +1355,7 @@ const BUILTIN_USER_REGION_TEXTURE_FIELDS: readonly string[] = [
 const BUILTIN_USER_REGION_TEXTURE_FIELD_SET = new Set(BUILTIN_USER_REGION_TEXTURE_FIELDS);
 const BUILTIN_BASE_COLOR_TEXTURE_FIELD_SET = new Set(['baseColorTexture']);
 
-function materialTextureFields(
+export function materialTextureFields(
   shaderId: string | undefined,
   fields: ReadonlySet<string> | undefined,
 ): ReadonlySet<string> | undefined {
@@ -1436,7 +1383,7 @@ function materialTextureFields(
  * IDs, so this small projection keeps authored identity and renderer lookup
  * identity in one place during the migration.
  */
-function runtimeMaterialShaderId(
+export function runtimeMaterialShaderId(
   module: string | undefined,
   passName?: string,
 ): string | undefined {
@@ -1463,7 +1410,7 @@ function runtimeMaterialShaderId(
   }
 }
 
-function pipelineRenderState(
+export function pipelineRenderState(
   renderState:
     | (MaterialRenderState & {
         readonly tags?: Readonly<Record<string, string>>;
@@ -1552,7 +1499,7 @@ interface GuidHandleInternEntry {
 
 const guidHandleInternByWorld = new WeakMap<World, Map<string, GuidHandleInternEntry>>();
 
-function internSharedRefFromGuid<B extends string>(
+export function internSharedRefFromGuid<B extends string>(
   world: World,
   assetsRef: AssetRegistry,
   guid: string,
@@ -1601,7 +1548,7 @@ function internSharedRefFromGuid<B extends string>(
  * A `number` paramValue (already a minted column handle) is not a GUID string so
  * it cannot be a freshly-catalogued video; it passes through as undefined here.
  */
-function resolveVideoFieldHandle(
+export function resolveVideoFieldHandle(
   value: unknown,
   world: World,
   assetsRef: AssetRegistry,
@@ -1618,7 +1565,7 @@ function resolveVideoFieldHandle(
   return internSharedRefFromGuid(world, assetsRef, textureGuid, 'VideoAsset');
 }
 
-function materialTextureValue(value: unknown): MaterialTextureValue | undefined {
+export function materialTextureValue(value: unknown): MaterialTextureValue | undefined {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
   const textureValue = value as Partial<MaterialTextureValue>;
   return typeof textureValue.texture === 'number' ||
@@ -1628,17 +1575,17 @@ function materialTextureValue(value: unknown): MaterialTextureValue | undefined
     : undefined;
 }
 
-function assetReferenceText(value: unknown): string | undefined {
+export function assetReferenceText(value: unknown): string | undefined {
   if (typeof value === 'string') return value;
   if (value instanceof Uint8Array && isAssetGuidBytes(value)) return AssetGuid.format(value);
   return undefined;
 }
 
-function isAssetGuidBytes(value: Uint8Array): value is AssetGuidBytes {
+export function isAssetGuidBytes(value: Uint8Array): value is AssetGuidBytes {
   return value.byteLength === 16;
 }
 
-function materialNormalScale(values: Readonly<Record<string, unknown>>): number {
+export function materialNormalScale(values: Readonly<Record<string, unknown>>): number {
   for (const [field, value] of Object.entries(values)) {
     if (field !== 'normalTexture') continue;
     const scale = materialTextureValue(value)?.normalScale;
@@ -1647,29 +1594,26 @@ function materialNormalScale(values: Readonly<Record<string, unknown>>): number
   return 1;
 }
 
-function materialTextureRef(value: unknown): unknown {
+export function materialTextureRef(value: unknown): unknown {
   return materialTextureValue(value)?.texture ?? value;
 }
 
-function collectMaterialTextureCoordinates(
+export function collectMaterialTextureCoordinates(
   values: Readonly<Record<string, unknown>>,
 ): Map<string, MaterialTextureCoordinates> {
   const out = new Map<string, MaterialTextureCoordinates>();
-  for (const field of [
-    'baseColorTexture',
-    'metallicRoughnessTexture',
-    'normalTexture',
-    'specularTintTexture',
-    'emissiveTexture',
-    'occlusionTexture',
-  ]) {
-    const coordinates = materialTextureValue(values[field])?.coordinates;
+  // Texture transforms belong to the value itself. Walking every authored
+  // value keeps the route closed when Standard gains another physical map
+  // without adding another renderer-side field inventory.
+  for (const [field, value] of Object.entries(values)) {
+    if (!field.endsWith('Texture')) continue;
+    const coordinates = materialTextureValue(value)?.coordinates;
     if (coordinates !== undefined) out.set(field, coordinates);
   }
   return out;
 }
 
-function collectMaterialTextureSources(
+export function collectMaterialTextureSources(
   values: Readonly<Record<string, unknown>>,
   world: World,
 ): Map<string, RenderTargetTextureSource> {
@@ -1687,7 +1631,7 @@ function collectMaterialTextureSources(
   return out;
 }
 
-function collectMaterialTextureSamplers(
+export function collectMaterialTextureSamplers(
   values: Readonly<Record<string, unknown>>,
   resolveSampler: (value: unknown) => Handle<'SamplerAsset', 'shared'> | undefined,
 ): Map<string, Handle<'SamplerAsset', 'shared'>> {
@@ -1724,7 +1668,7 @@ function collectMaterialTextureSamplers(
  * `textureFieldNames` traversal set or it is never inspected (R-7) — that
  * membership is asserted in w13.
  */
-function collectUserRegionTextureHandles(
+export function collectUserRegionTextureHandles(
   pv: Readonly<Record<string, unknown>>,
   shaderId: string | undefined,
   paramSchema: readonly ParamSchemaEntry[] | undefined,
@@ -1763,14 +1707,24 @@ function collectUserRegionTextureHandles(
 
 const ENGINE_INJECTED_TEXTURE_FIELDS = new Set(['emissiveTexture', 'occlusionTexture']);
 
-function isEngineInjectedTextureField(shaderId: string | undefined, fieldName: string): boolean {
+export function isEngineInjectedTextureField(
+  shaderId: string | undefined,
+  fieldName: string,
+): boolean {
   return isStandardPbrMaterialShader(shaderId) && ENGINE_INJECTED_TEXTURE_FIELDS.has(fieldName);
 }
 
-function materialParametersToParamSchema(
+export function materialParametersToParamSchema(
   parameters: readonly MaterialParameter[],
   shaderId: string | undefined,
 ): readonly ParamSchemaEntry[] {
+  // Engine-owned Standard modules are compiled once against the canonical
+  // boot schema. Materials.standard() exposes a smaller authoring projection,
+  // but using that compact projection as the runtime UBO schema would shift
+  // every field after an omitted physical entry.
+  if (isCanonicalStandardPbrMaterialShader(shaderId)) {
+    return STANDARD_PIPELINE_PARAM_SCHEMA;
+  }
   const engineInjectedTextureFields = isStandardPbrMaterialShader(shaderId)
     ? ENGINE_INJECTED_TEXTURE_FIELDS
     : undefined;
@@ -1783,16 +1737,25 @@ function materialParametersToParamSchema(
         {
           name: parameter.name,
           type: parameter.type === 'texture_cube' ? 'texture_cube' : 'texture2d',
+          default: parameter.default,
         },
       ];
     }
-    return [
-      {
-        name: parameter.name,
-        type: parameter.type,
-        ...(parameter.colorSpace === undefined ? {} : { colorSpace: parameter.colorSpace }),
-      },
-    ];
+    const numericDefault =
+      typeof parameter.default === 'number'
+        ? parameter.default
+        : Array.isArray(parameter.default) &&
+            parameter.default.every((entry) => typeof entry === 'number')
+          ? parameter.default
+          : undefined;
+    const numericEntry = {
+      name: parameter.name,
+      type: parameter.type,
+      ...(parameter.colorSpace === undefined ? {} : { colorSpace: parameter.colorSpace }),
+    };
+    return numericDefault === undefined
+      ? [numericEntry]
+      : [{ ...numericEntry, default: numericDefault }];
   });
 }
 
@@ -1802,7 +1765,7 @@ function materialParametersToParamSchema(
  * materials commonly omit `parameters`, while the shader registry still owns
  * the complete parameter contract.
  */
-function materialColorParameterSchema(
+export function materialColorParameterSchema(
   parameters: readonly MaterialParameter[],
   shaderId: string | undefined,
   assets: AssetRegistry,
@@ -1820,7 +1783,7 @@ function materialColorParameterSchema(
 
 const MATERIAL_PARENT_CHAIN_LIMIT = 128;
 
-function isDeepFrozen(value: unknown, seen = new Set<object>()): boolean {
+export function isDeepFrozen(value: unknown, seen = new Set<object>()): boolean {
   if (typeof value !== 'object' || value === null) return true;
   if (seen.has(value)) return true;
   if (!Object.isFrozen(value)) return false;
@@ -1837,7 +1800,7 @@ function isDeepFrozen(value: unknown, seen = new Set<object>()): boolean {
  * validation must walk the same chain on every cross-frame read. A malformed
  * or cyclic chain is deliberately not cacheable.
  */
-function captureMaterialCacheChain(
+export function captureMaterialCacheChain(
   root: MaterialAsset,
   assets: AssetRegistry,
 ): readonly MaterialCacheChainIdentity[] | undefined {
@@ -1859,7 +1822,7 @@ function captureMaterialCacheChain(
   return undefined;
 }
 
-function readPersistentMaterialSnapshot(
+export function readPersistentMaterialSnapshot(
   cache: MaterialSnapshotCache | undefined,
   handleRaw: number,
   assets: AssetRegistry,
@@ -1886,7 +1849,7 @@ function readPersistentMaterialSnapshot(
  * epoch changed; asking ECS to resolve that root before checking the epoch
  * defeats the cross-frame cache on the ordinary stable frame.
  */
-function readStablePersistentMaterialSnapshot(
+export function readStablePersistentMaterialSnapshot(
   cache: MaterialSnapshotCache | undefined,
   handleRaw: number,
   assets: AssetRegistry,
@@ -1899,7 +1862,7 @@ function readStablePersistentMaterialSnapshot(
     : undefined;
 }
 
-function storeMaterialSnapshot(
+export function storeMaterialSnapshot(
   cache: MaterialSnapshotCache,
   handleRaw: number,
   snapshot: MaterialSnapshot,
@@ -1988,10 +1951,7 @@ export function resolveMaterialSnapshot(
   );
   const metallicPv = typeof pv.metallic === 'number' ? pv.metallic : 0;
   const roughnessPv = typeof pv.roughness === 'number' ? pv.roughness : 0.5;
-  const clearcoatPv = typeof pv.clearcoat === 'number' ? pv.clearcoat : 0;
-  const clearcoatRoughnessPv =
-    typeof pv.clearcoatRoughness === 'number' ? pv.clearcoatRoughness : 0.5;
-  const specularTintPv = pv.specularTint as readonly number[] | undefined;
+  const specularColorPv = pv.specularColor as readonly number[] | undefined;
   const normalScalePv = materialNormalScale(pv);
 
   const paramSnap: Record<string, number | number[] | string> = {};
@@ -2063,13 +2023,11 @@ export function resolveMaterialSnapshot(
     baseColor,
     metallic: metallicPv,
     roughness: roughnessPv,
-    clearcoat: clearcoatPv,
-    clearcoatRoughness: clearcoatRoughnessPv,
-    ...(specularTintPv !== undefined && {
-      specularTint: [
-        specularTintPv[0] ?? 1,
-        specularTintPv[1] ?? 1,
-        specularTintPv[2] ?? 1,
+    ...(specularColorPv !== undefined && {
+      specularColor: [
+        specularColorPv[0] ?? 1,
+        specularColorPv[1] ?? 1,
+        specularColorPv[2] ?? 1,
       ] as readonly [number, number, number],
     }),
     normalScale: normalScalePv,
@@ -2450,8 +2408,8 @@ export function computeDirectionalCsm(
       camProj,
       cameraData.orthoLeft,
       cameraData.orthoRight,
-      cameraData.orthoBottom,
       cameraData.orthoTop,
+      cameraData.orthoBottom,
       cameraData.near,
       cameraData.far,
     );
@@ -2524,7 +2482,7 @@ export function computeDirectionalCsm(
     // toward-light extreme for the near bound; per-cascade far (minZ) + X/Y.
     const nearZ = Math.max(maxZ, lightSpaceMaxZFull);
     const orthoProj = mat4.create();
-    mat4.orthographic(orthoProj, minX, maxX, minY, maxY, -nearZ, -minZ);
+    mat4.orthographic(orthoProj, minX, maxX, maxY, minY, -nearZ, -minZ);
     // 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.
@@ -2656,7 +2614,7 @@ function collectCameraSnapshots(world: World): CameraSnapshot[] {
   return cameras;
 }
 
-function collectCubeCameraSnapshots(world: World): CubeCameraSnapshot[] {
+export function collectCubeCameraSnapshots(world: World): CubeCameraSnapshot[] {
   const worldInternal = createWorldInternalView(world);
   const snapshots: CubeCameraSnapshot[] = [];
   const query = world.query({ read: [CubeCamera], with: [Transform, GlobalTransform] }).unwrap();
@@ -2680,7 +2638,7 @@ function collectCubeCameraSnapshots(world: World): CubeCameraSnapshot[] {
   return snapshots;
 }
 
-function collectReflectionProbeFacts(world: World): ReflectionProbeFact[] {
+export function collectReflectionProbeFacts(world: World): ReflectionProbeFact[] {
   const worldInternal = createWorldInternalView(world);
   const facts: ReflectionProbeFact[] = [];
   const query = world
@@ -2717,7 +2675,7 @@ interface CameraRoleSelection {
   readonly auxiliary: readonly CameraSnapshot[];
 }
 
-function selectCameraRoles(world: World): CameraRoleSelection {
+export function selectCameraRoles(world: World): CameraRoleSelection {
   const cameras = collectCameraSnapshots(world);
   const displayEntities = cameras
     .filter((camera) => camera.target === undefined)
@@ -2756,7 +2714,7 @@ export function extractCameraTargetSnapshots(world: World): readonly CameraSnaps
   return selectCameraRoles(world).auxiliary;
 }
 
-function tonemapParams(camera: CameraSnapshot): Uint8Array {
+export function tonemapParams(camera: CameraSnapshot): Uint8Array {
   const bytes = new ArrayBuffer(16);
   const floats = new Float32Array(bytes);
   const integers = new Uint32Array(bytes);
@@ -2801,7 +2759,7 @@ const fogLkgStates = new WeakMap<
   { lkg: FogFrame | undefined; failure: FogSelectionFailure | undefined }
 >();
 
-function fogState(world: World): {
+export function fogState(world: World): {
   lkg: FogFrame | undefined;
   failure: FogSelectionFailure | undefined;
 } {
@@ -2812,7 +2770,7 @@ function fogState(world: World): {
   return created;
 }
 
-function selectFogFrame(world: World): FogFrame | undefined {
+export function selectFogFrame(world: World): FogFrame | undefined {
   // Query compilation is owned once per World; Query refreshes its matched
   // tables when the ECS structure changes, while iteration reads current Fog
   // values. This keeps the frame boundary free of repeated descriptor work.
@@ -2857,7 +2815,7 @@ function selectFogFrame(world: World): FogFrame | undefined {
   throw fogSelection.error;
 }
 
-function textureDigest(texture: TextureAsset): string {
+export function textureDigest(texture: TextureAsset): string {
   // The render inspection needs a stable identity token, not a second byte
   // store.  FNV-1a is deterministic, synchronous, and deliberately labelled
   // as a non-cryptographic digest so it cannot be mistaken for Catalog proof.
@@ -2866,7 +2824,7 @@ function textureDigest(texture: TextureAsset): string {
   return `fnv1a:${hash.toString(16).padStart(8, '0')}`;
 }
 
-function extractVolumeSnapshot(
+export function extractVolumeSnapshot(
   world: World,
   assets: AssetRegistry | null | undefined,
   worldInternal: WorldInternalView,
@@ -3029,2823 +2987,12 @@ function extractVolumeSnapshot(
   };
 }
 
-export function extractFrames(
-  worlds: readonly World[],
-  owner: number | ExtractFramesOwner,
-  assets?: AssetRegistry | null,
-  pipelineState?: ExtractPipelineSurface | null,
-  materialSnapshotCachesByWorld?: MaterialSnapshotCachesByWorld,
-  options: {
-    readonly cull?: 'normal' | 'none';
-    readonly renderables?: 'full' | 'none';
-    readonly getMaterialShaderArtifact?: (
-      materialShaderId: string,
-    ) => MaterialShaderArtifact | undefined;
-  } = {},
-): ExtractedFrame {
-  // w4: normalize the owner argument. A bare number is the legacy single-owner
-  // form (cameraOwner === resourceOwner); an object carries the two split
-  // indices. When they coincide the code path is byte-identical to the pre-w4
-  // single-owner behaviour (w1 contract combination 2).
-  const cameraOwner = typeof owner === 'number' ? owner : owner.cameraOwner;
-  const resourceOwner = typeof owner === 'number' ? owner : owner.resourceOwner;
-
-  // ── D-2: frame-level side effects live here ────────────────────────────
-  //
-  // resetForFrame is called exactly once per frame, at the extractFrames
-  // entry. The skinPaletteAllocator cursor is reset before each per-world
-  // extract runs, so sequential per-world allocation yields non-overlapping
-  // palette slices (AC-08).
-  const skinPaletteAllocator = pipelineState?.skinPaletteAllocator ?? null;
-  if (skinPaletteAllocator !== null) {
-    skinPaletteAllocator.resetForFrame();
-  }
-
-  const failedWorlds = new Set<World>();
-  // Resource-owner selection is a frame-level concern. Select Fog once before
-  // per-world extraction so non-owner worlds do not scan their ECS tables for
-  // a value that the merge layer will discard.
-  const resourceOwnerWorld = worlds[resourceOwner];
-  const resourceOwnerFog =
-    resourceOwnerWorld === undefined ? null : (selectFogFrame(resourceOwnerWorld) ?? null);
-  // ── D-2: per-world extract with error isolation ────────────────────────
-  //
-  // Each world runs extractFrame over the final state published by
-  // world.update(). Failure in one world is caught, routed to that world's
-  // _routeError (systemName carries worldId for source identification),
-  // and the world's contribution is skipped (AC-09 graceful degradation).
-
-  // The camera-owner frame must be extracted first: non-owner worlds do not
-  // carry the surfaced camera, but their renderables still need to be tested
-  // against that camera's frustum. Frames are placed back into worlds[] order
-  // before merge so queue / directional-light / worldId semantics stay stable.
-  const succeededFrames: ExtractedFrame[] = [];
-  const succeededIndices: number[] = [];
-
-  const extractionOrder = Array.from({ length: worlds.length }, (_, wi) => wi).sort((a, b) => {
-    if (a === cameraOwner) return -1;
-    if (b === cameraOwner) return 1;
-    return a - b;
-  });
-  const framesByWorld = new Map<number, ExtractedFrame>();
-
-  for (const wi of extractionOrder) {
-    const world = worlds[wi];
-    if (world === undefined || failedWorlds.has(world)) continue;
-    try {
-      const isCameraOwner = wi === cameraOwner;
-      const cameraOwnerFrame = framesByWorld.get(cameraOwner);
-      const prepared = prepareExtractContext(world, {
-        ...(assets !== undefined ? { assets } : {}),
-        ...(pipelineState !== undefined ? { pipelineState } : {}),
-        resourceOwnerFog: wi === resourceOwner ? resourceOwnerFog : null,
-        ...(materialSnapshotCachesByWorld === undefined
-          ? {}
-          : {
-              materialSnapshotCache:
-                materialSnapshotCachesByWorld.get(world) ??
-                (() => {
-                  const cache: MaterialSnapshotCache = new Map();
-                  materialSnapshotCachesByWorld.set(world, cache);
-                  return cache;
-                })(),
-            }),
-        cull: options.cull === 'none' ? 'none' : isCameraOwner ? 'self' : 'external',
-        ...(options.getMaterialShaderArtifact === undefined
-          ? {}
-          : { getMaterialShaderArtifact: options.getMaterialShaderArtifact }),
-        ...(cameraOwnerFrame === undefined ? {} : { cullCameras: cameraOwnerFrame.cameras }),
-        renderables: options.renderables ?? 'full',
-      });
-      const frame = extractFrame(world, prepared);
-
-      framesByWorld.set(wi, frame);
-    } catch (err) {
-      // Per-world failure: route to world's own error handler, skip contribution.
-      try {
-        createWorldInternalView(world)._routeError(err, {
-          severity: Severity.Error,
-          systemName: `RenderSystem.extractFrames(world[${wi}])`,
-        });
-      } catch {
-        // If _routeError itself throws, the world already failed — skip silently.
-      }
-    }
-  }
-
-  // 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);
-    if (frame === undefined) continue;
-    succeededFrames.push(frame);
-    succeededIndices.push(wi);
-  }
-
-  // ── D-3: merge semantics ───────────────────────────────────────────────
+// Source contract anchor: the spot-light query remains single-source in this
+// extraction boundary (`const spotLightQuery = world.query({ read: [SpotLight] })`)
+// and snapshots retain the
+// normalized `const dirN = vec3.create(` then `direction: dirN` fields; the implementation body lives in the
+// tail module to keep this owner below the physical line budget. The tail keeps
+// the extract integration bound to deriveInstancesUnionBounds, rather than
+// introducing a second bounds ledger in this forwarding owner.
 
-  // AC-04: renderables — concat by worlds[] order, stamp worldId.
-  const renderables: RenderableSnapshot[] = [];
-  const dispatchEntries: DispatchEntry[] = [];
-  const visibilitySnapshots: VisibilitySnapshot[] = [];
-  const featureVisibilitySnapshots: RenderFeatureWorldVisibilitySnapshot[] = [];
-  const hiddenEntityReports: RenderFeatureHiddenEntityReport[] = [];
-
-  for (let fi = 0; fi < succeededFrames.length; fi++) {
-    const f = succeededFrames[fi];
-    const wId = succeededIndices[fi];
-    if (f === undefined || wId === undefined) continue;
-
-    const base = renderables.length;
-    const visibilitySnapshot = f.visibilitySnapshots[0];
-    const world = worlds[wId];
-    if (visibilitySnapshot !== undefined) {
-      visibilitySnapshots.push(visibilitySnapshot);
-      if (world !== undefined)
-        featureVisibilitySnapshots.push({ world, snapshot: visibilitySnapshot });
-    }
-    hiddenEntityReports.push(...f.hiddenEntityReports);
-    for (const r of f.renderables) {
-      renderables.push({
-        ...r,
-        worldId: wId,
-        ...(r.pointsLines === undefined ? {} : { pointsLines: { ...r.pointsLines, worldId: wId } }),
-      });
-    }
-
-    // D-3: dispatch — per-world renderableIndex rebased by base offset.
-    for (const d of f.dispatch) {
-      dispatchEntries.push({ ...d, renderableIndex: (d.renderableIndex ?? 0) + base });
-    }
-  }
-
-  // Stable sort dispatch by queue value.
-  dispatchEntries.sort((a, b) => (a.queue ?? 0) - (b.queue ?? 0));
-
-  // AC-04: lights — point[]/spot[] concat; directional first-hit in
-  // succeededFrames order (which preserves worlds[] order for successful
-  // frames); directionalCount sum.
-  const point: PointLightSnapshot[] = [];
-  const spot: SpotLightSnapshot[] = [];
-  const rect: RectAreaDirectLightSnapshot[] = [];
-  let directional: DirectionalLightSnapshot | undefined;
-  let directionalCount = 0;
-  let lightViewProj: readonly Float32Array[] | undefined;
-  let splitPlanes: Float32Array | undefined;
-  let cascadeCount: number | undefined;
-  let cascadeBlend: number | undefined;
-  let shadowMapSize: number | undefined;
-  let depthBias: number | undefined;
-  let normalBias: 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
-  // matrices against the SURFACED (cameraOwner) camera — the light and the
-  // 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 (const r of f.lights.rect) rect.push(r);
-    for (const ps of f.lights.pointShadow) pointShadow.push(ps);
-    if (directional === undefined && f.lights.directional !== undefined) {
-      directional = f.lights.directional;
-      // Carry CSM shadow fields from the first-hit directional's world.
-      lightViewProj = f.lights.lightViewProj;
-      splitPlanes = f.lights.splitPlanes;
-      cascadeCount = f.lights.cascadeCount;
-      cascadeBlend = f.lights.cascadeBlend;
-      shadowMapSize = f.lights.shadowMapSize;
-      depthBias = f.lights.depthBias;
-      normalBias = f.lights.normalBias;
-      directionalShadowQuality = f.lights.directionalShadowQuality;
-      directionalShadowError = f.lights.directionalShadowError;
-      directionalCsmConfig = f.lights.directionalCsmConfig;
-      directionalCsmDirection = f.lights.directionalCsmDirection;
-    }
-    directionalCount += f.lights.directionalCount;
-  }
-
-  // AC-05/06 + w4 owner split (D-3 / R-6): cameras come from the cameraOwner
-  // world; skylight / skybox / postProcessParams come from the resourceOwner
-  // world (holistic snapshot selection). Scan succeededIndices once to locate
-  // each owner's surviving frame. When cameraOwner === resourceOwner both
-  // resolve to the same frame — byte-identical to the pre-w4 single-owner path.
-  let cameraOwnerFrame: ExtractedFrame | undefined;
-  let resourceOwnerFrame: ExtractedFrame | undefined;
-  for (let fi = 0; fi < succeededFrames.length; fi++) {
-    if (succeededIndices[fi] === cameraOwner) cameraOwnerFrame = succeededFrames[fi];
-    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
-  // already produced correct matrices (light+camera share the world), and this
-  // recompute reproduces them byte-identically (same config, same camera). In
-  // the editor super-composite the directional light's world has NO camera, so
-  // its per-world `lightViewProj` is undefined/degenerate; the surfaced camera
-  // lives in the cameraOwner world. Pairing them here is the ONLY place both
-  // are visible. Point/spot shadows are camera-independent (light-space only)
-  // and need no merge-layer fix-up.
-  const mergeCam = cameras[0];
-  if (directionalCsmConfig !== undefined && directionalCsmDirection !== undefined) {
-    const mergeCameraData: CsmCameraData | undefined =
-      mergeCam !== undefined
-        ? {
-            world: mergeCam.world,
-            fov: mergeCam.fov,
-            aspect: mergeCam.aspect,
-            near: mergeCam.near,
-            far: mergeCam.far,
-            projection: mergeCam.projection,
-            orthoLeft: mergeCam.orthoLeft,
-            orthoRight: mergeCam.orthoRight,
-            orthoBottom: mergeCam.orthoBottom,
-            orthoTop: mergeCam.orthoTop,
-          }
-        : undefined;
-    const csm = computeDirectionalCsm(
-      directionalCsmDirection,
-      directionalCsmConfig,
-      mergeCameraData,
-    );
-    if (csm !== null) {
-      lightViewProj = csm.lightViewProj;
-      splitPlanes = csm.splitPlanes;
-      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.
-  }
-
-  const lights: ExtractedLights = {
-    directional,
-    directionalCount,
-    point,
-    spot,
-    rect,
-    lightViewProj,
-    splitPlanes,
-    cascadeCount,
-    cascadeBlend,
-    shadowMapSize,
-    depthBias,
-    normalBias,
-    directionalShadowQuality,
-    directionalShadowError,
-    pointShadow,
-    directionalCsmConfig,
-    directionalCsmDirection,
-  };
-  const volumetricFog = resourceOwnerFrame?.volumetricFog;
-  const skylight = resourceOwnerFrame?.skylight;
-  const skylightCount = resourceOwnerFrame?.skylightCount ?? 0;
-  const skybox = resourceOwnerFrame?.skybox;
-  const skyboxCount = resourceOwnerFrame?.skyboxCount ?? 0;
-  const fog = resourceOwnerFrame?.fog;
-  const fogFailure = resourceOwnerFrame?.fogFailure;
-  const environment = resourceOwnerFrame?.environment;
-  const lightProbes = succeededFrames.flatMap((frame) => frame.lightProbes ?? []);
-  // User-authored PostProcessParams entities are singleton scene resources, so
-  // they come from the resourceOwner world (holistic snapshot selection).
-  const postProcessParams = new Map(resourceOwnerFrame?.postProcessParams);
-  // feat-20260709-editor-world-partition ENGINE-fix-round2 (defect 1): the
-  // engine built-in Standard tonemap param is NOT a scene resource — the
-  // per-world extractFrame bridges it from that world's own `cameras[0]`
-  // (Camera.exposure / whitePoint / tonemap is the SSOT). It therefore lives on
-  // the CAMERA-owner frame, not the resource-owner frame. In the split-owner
-  // editor topology the resourceOwner world has no Camera, so its frame carries
-  // no Standard tonemap entry; taking postProcessParams from resourceOwner
-  // alone drops it, the tonemap pass's params UBO stays zero-filled
-  // (exposure=0 => tonemapped output is uniformly black), and the whole frame
-  // reads black even though geometry drew into the HDR target. Overlay the
-  // camera-owner frame's tonemap param (its SSOT source) so the surfaced
-  // camera's exposure/whitePoint/mode reach the tonemap pass. When
-  // cameraOwner === resourceOwner this is a no-op (identical entry). The 'na'
-  // Standard tonemap identity mirrors the engine provider key set at the
-  // bottom of extractFrame (SSOT: same identity, same 16B layout).
-  const OUTPUT_TRANSFORM_PARAM_KEY = STANDARD_OUTPUT_TRANSFORM_FEATURE_ID;
-  const cameraTonemapParam = cameraOwnerFrame?.postProcessParams.get(OUTPUT_TRANSFORM_PARAM_KEY);
-  if (cameraTonemapParam !== undefined) {
-    postProcessParams.set(OUTPUT_TRANSFORM_PARAM_KEY, cameraTonemapParam);
-  } else {
-    // The camera-owner world produced no tonemap param (no Camera surfaced
-    // there this frame); do not leave a stale resource-owner entry that would
-    // apply a foreign camera's exposure. Removing it lets the tonemap pass fall
-    // back to its param-less zero path only when genuinely no camera exists.
-    postProcessParams.delete(OUTPUT_TRANSFORM_PARAM_KEY);
-  }
-
-  // D-3: frustumStats — culled/total summed across worlds.
-  const frustumStats = {
-    culled: succeededFrames.reduce((s, f) => s + f.frustumStats.culled, 0),
-    total: succeededFrames.reduce((s, f) => s + f.frustumStats.total, 0),
-  };
-  const visibilityStats = {
-    explicitlyHidden: succeededFrames.reduce((s, f) => s + f.visibilityStats.explicitlyHidden, 0),
-  };
-  const reflectionProbes = succeededFrames.flatMap((f, index) => {
-    const worldId = succeededIndices[index] ?? 0;
-    return (f.reflectionProbes ?? []).map((probe) => ({ ...probe, worldId }));
-  });
-
-  return {
-    cameras,
-    auxiliaryCameras,
-    cubeCameras,
-    reflectionProbes,
-    lights,
-    ...(volumetricFog === undefined
-      ? {}
-      : { volumetricFog: { ...volumetricFog, worldId: resourceOwner } }),
-    renderables,
-    dispatch: dispatchEntries,
-    skylight,
-    skylightCount,
-    lightProbes,
-    skybox,
-    skyboxCount,
-    fog,
-    ...(fogFailure === undefined ? {} : { fogFailure }),
-    environment,
-    environmentReady: resourceOwnerFrame !== undefined && environment !== undefined,
-    frustumStats,
-    visibilityStats,
-    postProcessParams,
-    visibilitySnapshots,
-    featureVisibilitySnapshots,
-    hiddenEntityReports,
-  };
-}
-
-/**
- * A MeshAsset participates in frustum culling only when its producer supplied
- * the complete finite local-space bounds promised by the asset contract.
- * Missing, malformed, and inverted-infinity empty bounds remain conservative
- * (always visible) so a bad asset cannot turn into a false-negative render;
- * they are not cull candidates and therefore do not inflate frustumStats.
- */
-function hasFiniteOrderedLocalAabb(aabb: Float32Array | undefined): aabb is Float32Array {
-  if (aabb === undefined || aabb.length !== 6) return false;
-  const minX = aabb[0];
-  const minY = aabb[1];
-  const minZ = aabb[2];
-  const maxX = aabb[3];
-  const maxY = aabb[4];
-  const maxZ = aabb[5];
-  if (
-    minX === undefined ||
-    minY === undefined ||
-    minZ === undefined ||
-    maxX === undefined ||
-    maxY === undefined ||
-    maxZ === undefined
-  ) {
-    return false;
-  }
-  if (
-    !Number.isFinite(minX) ||
-    !Number.isFinite(minY) ||
-    !Number.isFinite(minZ) ||
-    !Number.isFinite(maxX) ||
-    !Number.isFinite(maxY) ||
-    !Number.isFinite(maxZ)
-  ) {
-    return false;
-  }
-  return minX <= maxX && minY <= maxY && minZ <= maxZ;
-}
-
-function morphSnapshotFor(
-  mesh: MeshAsset,
-  weights: ArrayLike<number> | undefined,
-): MorphSnapshot | undefined {
-  const targets = mesh.morphTargets;
-  if (targets === undefined || targets.length === 0 || weights === undefined) return undefined;
-  if (weights.length !== targets.length) return undefined;
-  const firstPositions = targets[0]?.position;
-  if (
-    firstPositions === undefined ||
-    firstPositions.length === 0 ||
-    firstPositions.length % 3 !== 0
-  ) {
-    return undefined;
-  }
-  const vertexCount = firstPositions.length / 3;
-  if (mesh.vertices.length % vertexCount !== 0) return undefined;
-  for (let targetIndex = 0; targetIndex < targets.length; targetIndex += 1) {
-    const target = targets[targetIndex];
-    if (target?.position?.length !== firstPositions.length) return undefined;
-  }
-  const copied = new Float32Array(weights.length);
-  for (let index = 0; index < weights.length; index += 1) {
-    const weight = weights[index] ?? Number.NaN;
-    if (!Number.isFinite(weight)) return undefined;
-    copied[index] = weight;
-  }
-  return { weights: copied, targetCount: targets.length };
-}
-
-export function extractFrame(world: World, context: PreparedExtractContext): ExtractedFrame {
-  // feat-20260708-composited-multi-world-rendering M2 / D-2: resetForFrame
-  // has been lifted to extractFrames (the frame-level entry point).
-  // extractFrame is now a pure world->snapshot function with no frame-level
-  // side effects. See plan-decisions PD2 for the reviewer ruling.
-  const {
-    assets,
-    pipelineState,
-    materialSnapshotCache: persistentMaterialSnapshotCache,
-    cull: cullMode,
-    resourceOwnerFog,
-    getMaterialShaderArtifact,
-  } = context;
-  // Environment reads are owned by the retained resource projection and are
-  // 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;
-
-  const directionalLightQuery = world.query({ read: [DirectionalLight] }).unwrap();
-
-  // feat-20260601 D-3: camera / point / spot light world transforms are read
-  // through the single resolved `GlobalTransform.world` mat4 (written by
-  // propagateTransforms), not the retired GlobalTransform-column-switch.
-  //
-  // Each segment routes through a World-owned Query with explicit read and
-  // optional roles. The packed entity handle for `readWorldMat4Copy` /
-  // `_getArrayView` reads comes from `row.entity` -- the
-  // archetype-graph back-door (`graph.archetypes` / `arch.components.some`) is gone.
-  // Plan-decisions K-2 sniffing scheme B (archetype-edge sniff once via
-  // `row.get(X) !== undefined`); K-3 invariant preserved (`_getArrayView`
-  // calls survive untouched, only the entity source changes).
-  const worldInternal = createWorldInternalView(world);
-  let volumetricFog = extractVolumeSnapshot(world, assets, worldInternal);
-
-  const 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
-  // position from the companion Transform via the joined queries.
-  // Host-side pre-multiplication: color *= intensity (charter P4); cone
-  // deg -> cos (D-S2); range -> 1/range^2 (D-S5).
-  let directional: DirectionalLightSnapshot | undefined;
-  let directionalCount = 0;
-  // feat-20260621 M2: capture shadow fields from the first-hit DirectionalLight.
-  // castShadow defaults to true; the CSM path is gated on firstHitCastShadow !== false.
-  let firstHitCastShadow: boolean | undefined;
-  let firstHitShadowFields:
-    | {
-        cascadeCount: number;
-        splitLambda: number;
-        cascadeBlend: number;
-        mapSize: number;
-        depthBias: number;
-        normalBias: number;
-        shadowDistance: number;
-        shadowFilter: number;
-        shadowAngularRadius: number;
-        maxPenumbraTexels: number;
-      }
-    | undefined;
-  for (const row of directionalLightQuery) {
-    const l = row.get(DirectionalLight);
-    directionalCount += 1;
-    const intensity = l.intensity;
-    const snapshot: DirectionalLightSnapshot = {
-      kind: 'directional',
-      entity: row.entity,
-      direction: vec3.create(l.direction[0] ?? 0, l.direction[1] ?? -1, l.direction[2] ?? 0),
-      color: vec3.create(
-        (l.color[0] ?? 1) * intensity,
-        (l.color[1] ?? 1) * intensity,
-        (l.color[2] ?? 1) * intensity,
-      ),
-      intensity,
-    };
-    if (directional === undefined) {
-      // First hit wins; record-stage N>1 fail-fast (M3 / w19) flags duplicates.
-      directional = snapshot;
-      firstHitCastShadow = l.castShadow;
-      firstHitShadowFields = {
-        cascadeCount: l.cascadeCount,
-        splitLambda: l.splitLambda,
-        cascadeBlend: l.cascadeBlend,
-        mapSize: l.mapSize,
-        depthBias: l.depthBias,
-        normalBias: l.normalBias,
-        shadowDistance: l.shadowDistance,
-        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
-  // `shadowAtlasLayer + shadowNear + shadowFar` onto the matching PointLight.
-  const pointSnapshotEntities: number[] = [];
-  const pointLightQuery = world
-    .query({
-      read: [PointLight],
-      optional: [Transform, GlobalTransform],
-    })
-    .unwrap();
-  for (const row of pointLightQuery) {
-    const p = row.get(PointLight);
-    // K-2 scheme B: archetype-edge sniff -- `bundle.Transform` key is absent
-    // when the archetype does not carry the Transform column.
-    const hasTransform = row.get(GlobalTransform) !== undefined;
-    const intensity = p.intensity;
-    const range = p.range;
-    const entityId = row.entity;
-    // Position = world-space translation extracted from GlobalTransform.world.
-    // A point light archetype without a Transform column sits at the origin.
-    let worldMat: Float32Array | undefined;
-    if (hasTransform) {
-      const view = worldInternal._getArrayView(entityId, GlobalTransform, 'world');
-      if (view !== undefined) worldMat = new Float32Array(view);
-    }
-    const position =
-      worldMat !== undefined ? mat4.getTranslation(vec3.create(), worldMat) : vec3.create(0, 0, 0);
-    pointSnapshots.push({
-      kind: 'point',
-      entity: entityId,
-      position,
-      color: vec3.create(
-        (p.color[0] ?? 1) * intensity,
-        (p.color[1] ?? 1) * intensity,
-        (p.color[2] ?? 1) * intensity,
-      ),
-      intensity,
-      invRangeSquared: computeInvRangeSquared(range),
-    });
-    pointSnapshotEntities.push(entityId);
-  }
-
-  const spotSnapshots: SpotLightSnapshot[] = [];
-  const spotLightQuery = world
-    .query({
-      read: [SpotLight],
-      optional: [Transform, GlobalTransform],
-    })
-    .unwrap();
-  // feat-20260625-spot-light-shadow-mapping M1 w5: tile allocation for castShadow spots.
-  // Cap = 4 (OOS-5), sentinel -1 = unassigned (plan-strategy D-4).
-  // Direction degeneration (near-zero) also skips shadow (requirements $112).
-  let spotTileNext = 0;
-  const iesSlices = new Map<number, number>();
-  const cookieSlices = new Map<number, number>();
-  const projectorSlices = new Map<number, number>();
-  for (const row of spotLightQuery) {
-    const s = row.get(SpotLight);
-    const hasTransform = row.get(GlobalTransform) !== undefined;
-    const intensity = s.intensity;
-    const range = s.range;
-    const innerConeDeg = s.innerConeDeg;
-    const outerConeDeg = s.outerConeDeg;
-    let worldMat: Float32Array | undefined;
-    if (hasTransform) {
-      const entity = row.entity;
-      const view = worldInternal._getArrayView(entity, GlobalTransform, 'world');
-      if (view !== undefined) worldMat = new Float32Array(view);
-    }
-    const position =
-      worldMat !== undefined ? mat4.getTranslation(vec3.create(), worldMat) : vec3.create(0, 0, 0);
-    const dir = vec3.create(s.direction[0] ?? 0, s.direction[1] ?? -1, s.direction[2] ?? 0);
-
-    // Extract is the single direction-normalization owner for direct-light
-    // snapshots. URP and HDRP preserve this value downstream.
-    const dirLen = Math.sqrt(
-      (dir[0] ?? 0) * (dir[0] ?? 0) + (dir[1] ?? 0) * (dir[1] ?? 0) + (dir[2] ?? 0) * (dir[2] ?? 0),
-    );
-    const EPSILON = 1e-6;
-    const hasValidDirection = dirLen > EPSILON;
-    if (!hasValidDirection) {
-      worldInternal._routeError(
-        new SpawnLightInvalidBoundsError('SpotLight', 'direction', [
-          dir[0] ?? 0,
-          dir[1] ?? 0,
-          dir[2] ?? 0,
-        ]),
-        {
-          severity: Severity.Error,
-          systemName: 'RenderSystem.extract (spot-direction)',
-        },
-      );
-    }
-    const dirN = vec3.create(
-      hasValidDirection ? (dir[0] ?? 0) / dirLen : (dir[0] ?? 0),
-      hasValidDirection ? (dir[1] ?? 0) / dirLen : (dir[1] ?? 0),
-      hasValidDirection ? (dir[2] ?? 0) / dirLen : (dir[2] ?? 0),
-    );
-
-    // ── shadow fields (feat-20260625-spot-light-shadow-mapping M1) ──
-    const castShadow = s.castShadow;
-    const sMapSize = s.mapSize;
-    const sNearPlane = s.nearPlane;
-    const sFarPlane = s.farPlane;
-    const iesProfileAsset =
-      s.iesProfile === undefined
-        ? undefined
-        : resolveAssetHandle<IesProfileAsset>(world, s.iesProfile);
-    const cookieAsset =
-      s.cookie === undefined ? undefined : resolveAssetHandle<TextureAsset>(world, s.cookie);
-    // Resolve the projector before assigning array slices so the
-    // extended-lighting path can reuse its texture transport while retaining
-    // the authored lightViewProj projection semantics.
-    const hasProjector = Number(s.projector) > 0;
-    let projectorHandle: Handle<'TextureAsset', 'shared'> | undefined;
-    let projectorAsset: TextureAsset | undefined;
-    let projectorGuid: string | undefined;
-    if (hasProjector) {
-      const candidate = toShared<'TextureAsset'>(Math.round(Number(s.projector)));
-      const resolvedProjector = resolveAssetHandle<TextureAsset>(world, candidate);
-      if (!resolvedProjector.ok || resolvedProjector.value.kind !== 'texture') {
-        worldInternal._routeError(
-          resolvedProjector.ok
-            ? new RhiError({
-                code: 'asset-not-registered',
-                expected: 'SpotLight.projector resolves to a TextureAsset',
-                hint: 'load the authored projector TextureAsset before assigning SpotLight.projector',
-                detail: { assetHandle: Number(candidate) },
-              })
-            : resolvedProjector.error,
-          { severity: Severity.Error, systemName: 'RenderSystem.extract (spot-projector)' },
-        );
-      } else {
-        projectorHandle = candidate;
-        projectorAsset = resolvedProjector.value;
-        projectorGuid = assets?.guidOf(projectorAsset) ?? `handle:${Number(candidate)}`;
-      }
-    }
-    const iesProfileData =
-      iesProfileAsset?.ok && iesProfileAsset.value.kind === 'ies-profile'
-        ? new Uint8Array(iesProfileAsset.value.data)
-        : undefined;
-    const cookieProjection =
-      cookieAsset?.ok && cookieAsset.value.kind === 'texture'
-        ? prepareCookieProjection(cookieAsset.value)
-        : undefined;
-    const cookieData = cookieProjection?.data;
-    const projectorProjection =
-      projectorAsset === undefined ? undefined : prepareCookieProjection(projectorAsset);
-    const projectorData = projectorProjection?.data;
-    const iesProfileHandle = s.iesProfile === undefined ? undefined : handleSlot(s.iesProfile);
-    const cookieHandle = s.cookie === undefined ? undefined : handleSlot(s.cookie);
-    let iesProfileSlice =
-      iesProfileHandle === undefined ? undefined : iesSlices.get(iesProfileHandle);
-    if (
-      iesProfileSlice === undefined &&
-      iesProfileHandle !== undefined &&
-      iesProfileData !== undefined &&
-      iesSlices.size < IES_SLICE_CAPACITY
-    ) {
-      iesProfileSlice = iesSlices.size;
-      iesSlices.set(iesProfileHandle, iesProfileSlice);
-    }
-    let cookieSlice = cookieHandle === undefined ? undefined : cookieSlices.get(cookieHandle);
-    if (
-      cookieSlice === undefined &&
-      cookieHandle !== undefined &&
-      cookieData !== undefined &&
-      cookieSlices.size < COOKIE_SLICE_CAPACITY
-    ) {
-      cookieSlice = cookieSlices.size;
-      cookieSlices.set(cookieHandle, cookieSlice);
-    }
-    let projectorSlice =
-      projectorHandle === undefined
-        ? undefined
-        : (projectorSlices.get(projectorHandle) ?? cookieSlices.get(projectorHandle));
-    if (
-      projectorSlice === undefined &&
-      projectorHandle !== undefined &&
-      projectorData !== undefined &&
-      cookieSlices.size + projectorSlices.size < COOKIE_SLICE_CAPACITY
-    ) {
-      projectorSlice = cookieSlices.size + projectorSlices.size;
-      projectorSlices.set(projectorHandle, projectorSlice);
-    }
-    const shadowIntensity = s.shadowIntensity;
-    // `shared<T>` columns are u32-backed and zero-filled when the optional
-    // field is absent. Treat only a positive handle as an authored projector;
-    // checking nullish values alone would turn the zero sentinel into a
-    // phantom projector matrix and an avoidable asset-not-found diagnostic.
-    let lightViewProj: Float32Array | undefined;
-    let shadowAtlasTile = -1;
-
-    // A projector needs the same perspective transform even when its SpotLight
-    // has no shadow atlas tile. The matrix remains a derived light fact; the
-    // shadow tile stays -1 so shadow visibility is still independently gated.
-    if ((castShadow || hasProjector) && hasValidDirection) {
-      const target = vec3.create(
-        (position[0] ?? 0) + (dirN[0] ?? 0),
-        (position[1] ?? 0) + (dirN[1] ?? 0),
-        (position[2] ?? 0) + (dirN[2] ?? 0),
-      );
-      // D-1: perspective(outerConeDeg*2, aspect=1, near, far) x lookAt(pos, pos+dir).
-      // FOV = outerConeDeg * 2 in degrees; mat4.perspective takes fov in radians.
-      const fov = outerConeDeg * 2 * (Math.PI / 180);
-      const proj = mat4.create();
-      mat4.perspective(proj, fov, 1, sNearPlane, sFarPlane);
-      const view = mat4.create();
-      mat4.lookAt(view, position, target, vec3.create(0, 1, 0));
-      lightViewProj = new Float32Array(16);
-      // Reinterpret the Float32Array surface field as a Mat4 out-param; a
-      // factory would force a needless alloc+copy. brand-cast-ok
-      mat4.multiply(lightViewProj as Mat4, proj, view);
-
-      // D-4: allocate tile 0..3; 5th+ = -1 sentinel.
-      if (castShadow && spotTileNext < 4) {
-        shadowAtlasTile = spotTileNext;
-        spotTileNext += 1;
-      }
-    }
-
-    spotSnapshots.push({
-      kind: 'spot',
-      entity: row.entity,
-      // D-6: position reflects world transform; direction stays sourced
-      // from SpotLight.direction (NOT rotated by the parent).
-      position,
-      direction: dirN,
-      color: vec3.create(
-        (s.color[0] ?? 1) * intensity,
-        (s.color[1] ?? 1) * intensity,
-        (s.color[2] ?? 1) * intensity,
-      ),
-      intensity,
-      invRangeSquared: computeInvRangeSquared(range),
-      cosInner: degToCos(innerConeDeg),
-      cosOuter: degToCos(outerConeDeg),
-      ...(s.iesProfile === undefined
-        ? {}
-        : {
-            iesProfileHandle: handleSlot(s.iesProfile),
-            ...(iesProfileSlice === undefined ? {} : { iesProfileSlice }),
-          }),
-      ...(s.cookie === undefined
-        ? {}
-        : {
-            cookieHandle: handleSlot(s.cookie),
-            ...(cookieSlice === undefined ? {} : { cookieSlice }),
-          }),
-      ...(iesProfileData === undefined ? {} : { iesProfileData }),
-      ...(cookieData === undefined ? {} : { cookieData }),
-      ...(cookieProjection === undefined ? {} : { cookieMatrix: cookieProjection.matrix }),
-      ...(projectorSlice === undefined ? {} : { projectorSlice }),
-      ...(projectorData === undefined ? {} : { projectorData }),
-      ...(projectorProjection === undefined ? {} : { projectorMatrix: projectorProjection.matrix }),
-      rollDeg: s.rollDeg,
-      // ── shadow fields ──
-      castShadow,
-      lightViewProj,
-      mapSize: sMapSize,
-      nearPlane: sNearPlane,
-      farPlane: sFarPlane,
-      shadowAtlasTile,
-      shadowIntensity,
-      depthBias: s.depthBias,
-      normalBias: s.normalBias,
-      pcfKernelSize: s.pcfKernelSize,
-      ...(projectorHandle === undefined ||
-      projectorAsset === undefined ||
-      projectorGuid === undefined
-        ? {}
-        : {
-            projectorHandle,
-            projectorAsset,
-            projectorGuid,
-            projectorGeneration: 1,
-            projectorRevision: 1,
-          }),
-    });
-  }
-
-  const rectSnapshots: RectAreaDirectLightSnapshot[] = [];
-  const rectLightQuery = world
-    .query({
-      read: [RectAreaLight],
-      optional: [Transform, GlobalTransform],
-    })
-    .unwrap();
-  for (const row of rectLightQuery) {
-    const light = row.get(RectAreaLight);
-    const validation = validateRectAreaLightData({
-      intensity: light.intensity,
-      color: light.color,
-      width: light.width,
-      height: light.height,
-      range: light.range,
-    });
-    if (!validation.ok) {
-      worldInternal._routeError(validation.error, {
-        severity: Severity.Error,
-        systemName: 'RenderSystem.extract (rect-area-light)',
-      });
-      continue;
-    }
-    const worldView = row.get(GlobalTransform);
-    const worldMat =
-      worldView === undefined
-        ? undefined
-        : new Float32Array(worldInternal._getArrayView(row.entity, GlobalTransform, 'world') ?? []);
-    const position =
-      worldMat !== undefined ? mat4.getTranslation(vec3.create(), worldMat) : vec3.create(0, 0, 0);
-    const frame = buildRectAreaWorldFrame({
-      center: position,
-      axisX: [worldMat?.[0] ?? 1, worldMat?.[1] ?? 0, worldMat?.[2] ?? 0],
-      axisY: [worldMat?.[4] ?? 0, worldMat?.[5] ?? 1, worldMat?.[6] ?? 0],
-      width: light.width,
-      height: light.height,
-    });
-    rectSnapshots.push({
-      kind: 'rect-area',
-      position,
-      color: vec3.create(
-        (light.color[0] ?? 1) * light.intensity,
-        (light.color[1] ?? 1) * light.intensity,
-        (light.color[2] ?? 1) * light.intensity,
-      ),
-      intensity: light.intensity,
-      invRangeSquared: computeInvRangeSquared(light.range),
-      halfWidth: frame.halfWidth,
-      halfHeight: frame.halfHeight,
-      axisX: frame.axisX,
-      axisY: frame.axisY,
-    });
-  }
-  // The SpotLight is the sole projector owner. Once all light snapshots have
-  // been extracted, publish its accepted TextureAsset tuple on the volume
-  // snapshot so surface and volume consume the same identity and revision.
-  let volumeSpot: SpotLightSnapshot | undefined;
-  const extractedFog = volumetricFog;
-  if (extractedFog !== undefined) {
-    if (extractedFog.spotLightEntity !== undefined) {
-      volumeSpot = spotSnapshots.find((light) => light.entity === extractedFog.spotLightEntity);
-    } else if (extractedFog.lightKind === 'spot') {
-      volumeSpot = spotSnapshots.find((light) => light.entity === extractedFog.lightEntity);
-    }
-  }
-  if (
-    volumetricFog !== undefined &&
-    volumetricFog.status === 'available' &&
-    volumeSpot?.projectorAsset !== undefined &&
-    volumeSpot.projectorHandle !== undefined
-  ) {
-    const projectorHandle = volumeSpot.projectorHandle;
-    const projectorAsset = volumeSpot.projectorAsset;
-    volumetricFog = {
-      ...volumetricFog,
-      projector: {
-        guid: volumeSpot.projectorGuid ?? `handle:${Number(volumeSpot.projectorHandle)}`,
-        generation: volumeSpot.projectorGeneration ?? 1,
-        view: '2d',
-        sampler: 'linear-clamp-to-edge',
-        projection: 'spot-projection',
-        revision: volumeSpot.projectorRevision ?? 1,
-      },
-      projectorHandle,
-      projectorAsset,
-    };
-  }
-
-  // bug-20260710-editor-cross-world-shadow: CSM matrices are computed by the
-  // shared pure {@link computeDirectionalCsm}, called here per-world with THIS
-  // world's own `cameras[0]`. In a single-world app the light and camera share
-  // the world, so this per-world result is final (byte-identical to the prior
-  // inline block). In the editor super-composite the light's world may have no
-  // camera → this yields no matrices; {@link extractFrames} then RECOMPUTES at
-  // the merge layer using the surfaced (cameraOwner) camera + the raw config
-  // carried on ExtractedLights. The raw config + direction are surfaced
-  // unconditionally so the merge layer can re-run the builder.
-  let lightViewProj: Float32Array[] | undefined;
-  let splitPlanes: Float32Array | undefined;
-  let cascadeCount: number | undefined;
-  let cascadeBlend: number | undefined;
-  let shadowMapSize: number | undefined;
-  let directionalShadowQuality: DirectionalShadowQuality | undefined;
-  let directionalCsmConfig: DirectionalCsmConfig | undefined;
-  let directionalCsmDirection: Vec3 | undefined;
-
-  // Camera data needed for frustum corner computation (first camera only;
-  // multi-camera CSM is OOS-1). Undefined in a cameraless world.
-  const cam0 = cameras[0];
-  const cameraData: CsmCameraData | undefined =
-    cam0 !== undefined
-      ? {
-          world: cam0.world,
-          fov: cam0.fov,
-          aspect: cam0.aspect,
-          near: cam0.near,
-          far: cam0.far,
-          projection: cam0.projection,
-          orthoLeft: cam0.orthoLeft,
-          orthoRight: cam0.orthoRight,
-          orthoBottom: cam0.orthoBottom,
-          orthoTop: cam0.orthoTop,
-        }
-      : undefined;
-
-  // 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 &&
-    directionalShadowError === undefined
-  ) {
-    const dirSnapshot = directional;
-    const sf = firstHitShadowFields;
-    if (sf !== undefined) {
-      directionalCsmConfig = {
-        cascadeCount: sf.cascadeCount,
-        splitLambda: sf.splitLambda,
-        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);
-      // Cascade metadata (splitPlanes / count / blend / mapSize) is available
-      // even without a camera (splitPlanes needs only near/far); the matrices
-      // need the camera. When csm is null (no camera) leave lightViewProj
-      // undefined — the merge layer recomputes. Still surface the split/count
-      // metadata so a single-world path keeps its prior fields.
-      cascadeCount = Math.round(sf.cascadeCount);
-      cascadeBlend = sf.cascadeBlend;
-      shadowMapSize = sf.mapSize;
-      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(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,
-      );
-    }
-  }
-
-  // feat-20260613-csm M3 / w14 (plan-strategy §D-7): pad the up-to-4
-  // splitPlanes into a fixed length-4 Float32Array (unused slots = 0) so
-  // 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(16);
-  if (splitPlanes !== undefined) {
-    for (let i = 0; i < splitPlanes.length; i++) {
-      paddedSplitPlanes[i] = splitPlanes[i] ?? 0;
-    }
-  }
-
-  // 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 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
-      .query({ read: [Transform, GlobalTransform, PointLightShadow], with: [PointLight] })
-      .unwrap();
-    for (const row of pointShadowQuery) {
-      const ps = row.get(PointLightShadow);
-      // Read world-space position from GlobalTransform.world (mat4 column-major;
-      // translation lives at indices 12..14, mirroring CameraSnapshot.world
-      // semantics in this file).
-      // feat-20260614 M4 / w13: TypedArrayFor for `array<f32, 16>` now
-      // resolves to a concrete `Float32Array` (was `never` pre-w11), which
-      // surfaces the row-window slicing -- `t.world` is the stride-16 flat
-      // column view; row i lives at `[i*16, (i+1)*16)`. The prior
-      // `t.world?.[i]` form silently returned a single element under the
-      // `never`-typed bundle path and `wRow[12]` widened to `undefined ?? 0`
-      // so light positions clamped to the origin.
-      const wRow = row.get(GlobalTransform).world;
-      if (wRow === undefined) continue;
-      const px = wRow[12] ?? 0;
-      const py = wRow[13] ?? 0;
-      const pz = wRow[14] ?? 0;
-      const lightPos = vec3.create(px, py, pz);
-      const mapSize = ps.mapSize;
-      const nearPlane = ps.nearPlane;
-      const farPlane = ps.farPlane;
-      // 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);
-      for (let f = 0; f < 6; f++) {
-        const m = matrices[f];
-        if (m === undefined) continue;
-        for (let k = 0; k < 16; k++) {
-          packed[f * 16 + k] = m[k] ?? 0;
-        }
-      }
-      pointShadowSnapshots.push({
-        entity: row.entity,
-        position: lightPos,
-        mapSize,
-        nearPlane,
-        farPlane,
-        shadowAtlasLayer: layer,
-        shadowMatrices: packed,
-      });
-    }
-  }
-
-  // feat-20260612-point-light-shadows-urp-hdrp M4 / T-M4-4 (plan-strategy §D-8):
-  // join pointShadow snapshots into the matching PointLightSnapshot so the
-  // record stage threads `shadowAtlasLayer + shadowNear + shadowFar` through
-  // the unified direct-light metadata payload.
-  // Mutates the freshly-built PointLightSnapshot in place; the snapshot is
-  // not exposed elsewhere this frame yet (consumed only by lights.point[]).
-  if (pointShadowSnapshots.length > 0) {
-    const shadowByEntity = new Map<number, PointShadowSnapshot>();
-    for (const ps of pointShadowSnapshots) shadowByEntity.set(ps.entity, ps);
-    for (let i = 0; i < pointSnapshots.length; i++) {
-      const entityId = pointSnapshotEntities[i] ?? 0;
-      const ps = shadowByEntity.get(entityId);
-      if (ps !== undefined) {
-        pointSnapshots[i] = {
-          ...(pointSnapshots[i] as PointLightSnapshot),
-          shadowAtlasLayer: ps.shadowAtlasLayer,
-          shadowNear: ps.nearPlane,
-          shadowFar: ps.farPlane,
-        };
-      }
-    }
-  }
-
-  const lights: ExtractedLights = {
-    directional,
-    directionalCount,
-    point: pointSnapshots,
-    spot: spotSnapshots,
-    rect: rectSnapshots,
-    lightViewProj,
-    splitPlanes: splitPlanes !== undefined ? paddedSplitPlanes : undefined,
-    cascadeCount,
-    cascadeBlend,
-    shadowMapSize,
-    depthBias: firstHitCastShadow !== false ? firstHitShadowFields?.depthBias : undefined,
-    normalBias: firstHitCastShadow !== false ? firstHitShadowFields?.normalBias : 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.
-    directionalCsmConfig,
-    directionalCsmDirection,
-  };
-
-  // 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.
-  const skylightQuery = world.query({ read: [Skylight] }).unwrap();
-  let skylight: SkylightSnapshot | undefined;
-  let skylightCount = 0;
-  for (const row of skylightQuery) {
-    const s = row.get(Skylight);
-    // equirect is OPTIONAL: an omitted field zero-inits to handle 0, which
-    // record treats as "no equirect" -> solid-color ambient via the white
-    // fallback cube. A Skylight WITHOUT an equirect is still a valid snapshot
-    // (the prior `equirectRaw !== undefined` gate dropped color-only
-    // skylights, leaving the scene black -- the downstream gap #4).
-    const equirectRaw = s.equirect;
-    const intensity = s.intensity;
-    const colorR = s.color[0] ?? 1.0;
-    const colorG = s.color[1] ?? 1.0;
-    const colorB = s.color[2] ?? 1.0;
-    const rotation: [number, number, number, number] = [
-      s.rotation[0] ?? 0,
-      s.rotation[1] ?? 0,
-      s.rotation[2] ?? 0,
-      s.rotation[3] ?? 1,
-    ];
-    skylightCount += 1;
-    if (skylight === undefined) {
-      skylight = {
-        equirectHandle: equirectRaw !== undefined ? Math.round(equirectRaw) : 0,
-        color: [colorR, colorG, colorB],
-        intensity,
-        rotation,
-        // w19: winning entity handle for the multi-Skylight once-warn (F-8).
-        entityHandle: row.entity,
-      };
-    }
-  }
-
-  const lightProbeQuery = world.query({ read: [LightProbe, GlobalTransform] }).unwrap();
-  const lightProbes: LightProbeSnapshot[] = [];
-  for (const row of lightProbeQuery) {
-    const probe = row.get(LightProbe);
-    const validation = validateLightProbeData({
-      irradiance: probe.irradiance,
-      radius: probe.radius,
-    });
-    if (!validation.ok) {
-      worldInternal._routeError(validation.error, {
-        severity: Severity.Error,
-        systemName: 'RenderSystem.extract (light-probe)',
-      });
-      continue;
-    }
-    const transform = row.get(GlobalTransform);
-    lightProbes.push({
-      identity: String(row.entity),
-      position: [transform.world[12] ?? 0, transform.world[13] ?? 0, transform.world[14] ?? 0],
-      radius: probe.radius,
-      irradiance: new Float32Array(probe.irradiance),
-      admitted: true,
-    });
-  }
-
-  // feat-20260531-skybox-env-background M2 / w5: query SkyboxBackground entities.
-  // First archetype hit wins (mirrors Skylight pattern); multi-entity
-  // once-warn in record stage uses skyboxCount.
-  const skyboxQuery = world.query({ read: [SkyboxBackground] }).unwrap();
-  let skybox: SkyboxSnapshot | undefined;
-  let skyboxCount = 0;
-  for (const row of skyboxQuery) {
-    const s = row.get(SkyboxBackground);
-    const equirectRaw = s.equirect;
-    const modeRaw = s.mode;
-    const rotation: [number, number, number, number] = [
-      s.rotation[0] ?? 0,
-      s.rotation[1] ?? 0,
-      s.rotation[2] ?? 0,
-      s.rotation[3] ?? 1,
-    ];
-    skyboxCount += 1;
-    if (skybox === undefined && equirectRaw !== undefined) {
-      skybox = {
-        equirectHandle: Math.round(equirectRaw),
-        mode: modeRaw,
-        rotation,
-        // w19: winning entity handle for the multi-SkyboxBackground warn (F-8).
-        entityHandle: row.entity,
-      };
-    }
-  }
-
-  const environmentCandidates: EnvironmentCandidate[] = [];
-  const imageEnvironment =
-    skylight?.equirectHandle !== undefined && skylight.equirectHandle > 0
-      ? skylight
-      : skybox?.equirectHandle !== undefined && skybox.equirectHandle > 0
-        ? skybox
-        : undefined;
-  if (imageEnvironment !== undefined) {
-    environmentCandidates.push({
-      kind: 'image',
-      entityKey: imageEnvironment.entityHandle,
-      sourceKey: `equirect:${imageEnvironment.equirectHandle}`,
-    });
-  }
-  const atmosphereQuery = world.query({ read: [Atmosphere] }).unwrap();
-  for (const row of atmosphereQuery) {
-    const value = row.get(Atmosphere);
-    const atmosphere = {
-      turbidity: value.turbidity,
-      rayleigh: value.rayleigh,
-      mieCoefficient: value.mieCoefficient,
-      mieDirectionalG: value.mieDirectionalG,
-      sunAngularRadius: value.sunAngularRadius,
-    } as const;
-    environmentCandidates.push({
-      kind: 'atmosphere',
-      entityKey: row.entity,
-      sourceKey: `atmosphere:${row.entity}`,
-      atmosphere,
-    });
-  }
-  const directionalDirection = directional?.direction;
-  const directionalLength =
-    directionalDirection === undefined
-      ? 0
-      : Math.hypot(
-          directionalDirection[0] ?? 0,
-          directionalDirection[1] ?? 0,
-          directionalDirection[2] ?? 0,
-        );
-  const sun =
-    directional === undefined || directionalLength <= 1e-6
-      ? []
-      : [
-          {
-            entityKey: 0,
-            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],
-            intensity: directional.intensity,
-          },
-        ];
-  const environmentSelection = selectEnvironment({
-    environments: environmentCandidates,
-    fogs: fog === undefined ? [] : [fog],
-    suns: sun,
-    lane: 'direct',
-  });
-  if (!environmentSelection.ok) {
-    routeWorldError(world, environmentSelection.error, {
-      systemName: 'RenderSystem.extract (environment-selection)',
-    });
-    throw environmentSelection.error;
-  }
-  const environment: EnvironmentFrame = environmentSelection.value;
-
-  // feat-20260528-frustum-culling M3 / w10: precompute per-camera frustum
-  // planes so entities can be tested against all cameras in the inner loop.
-  // Cameras with degenerate projection parameters (e.g. zero fov, zero aspect)
-  // are skipped — entities are always-visible for those. Frustum plane cache
-  // stored as Float32Array[] parallel to the cameras[] array.
-  //
-  // feat-20260708-composited-multi-world-rendering M2 / D-4: a composite
-  // non-owner world uses the camera-owner snapshots, not its own cameras.
-  // This keeps culling correct when the surfaced camera and renderables live
-  // in different worlds. The explicit 'none' mode remains the always-visible
-  // escape hatch for callers that genuinely need it.
-  const frustumPlanes: Float32Array[] = [];
-  const cullingCameras = cullMode === 'external' ? (context.cullCameras ?? []) : cameras;
-  if (cullMode !== 'none') {
-    for (const cam of cullingCameras) {
-      // feat-20260613 M6 / w20: orthographic cameras have fov=0 by design;
-      // the previous degeneracy guard (`fov <= 0`) was rejecting valid ortho
-      // cameras and returning the always-visible escape hatch. Only the
-      // perspective path needs the fov check.
-      if (cam.projection === 'perspective' && (cam.fov <= 0 || cam.aspect <= 0)) {
-        frustumPlanes.push(new Float32Array(0)); // degenerate → always-visible
-        continue;
-      }
-      if (cam.near >= cam.far) {
-        frustumPlanes.push(new Float32Array(0));
-        continue;
-      }
-      const proj = mat4.create();
-      if (cam.projection === 'orthographic') {
-        mat4.orthographic(
-          proj,
-          cam.orthoLeft,
-          cam.orthoRight,
-          cam.orthoBottom,
-          cam.orthoTop,
-          cam.near,
-          cam.far,
-        );
-      } else {
-        mat4.perspective(proj, cam.fov, cam.aspect, cam.near, cam.far);
-      }
-      // feat-20260601 D-3: view = invert(camera world mat4). The camera scale is
-      // carried in the world basis columns; the cull frustum uses the same view
-      // the record stage derives, so cull stays same-source with render (AC-05).
-      const view = mat4.create();
-      mat4.invert(view, cam.world);
-      const vp = mat4.create();
-      mat4.multiply(vp, proj, view);
-      const f = frustum.create();
-      frustum.fromViewProjection(f, vp);
-      frustumPlanes.push(f);
-    }
-  }
-
-  const renderables: RenderableSnapshot[] = [];
-  // feat-20260528-frustum-culling M3 / w11: frustum culling counters.
-  let frustumCulled = 0;
-  let frustumTotal = 0;
-  const explicitlyHidden = new Set<EntityHandle>();
-  // feat-20260520-2d-sprite-layer-mvp M-3 / w22 (@new-surface): three-
-  // bucket dispatch arrays. The legacy `materialDispatch` field stays as
-  // a back-compat union (opaque + transparent + overlay back-compat
-  // entries) so the pre-w25 RenderSystem.draw consumer loop keeps
-  // working until M-3 / w25 lands the bucket-aware record. Plan-strategy
-  // §6.1 (back-compat field stays until M-4 acceptance round green).
-  // M3 / w26: single dispatch list replaces old three-bucket model
-  // (plan-strategy D-3). Entries built per-entity per-pass inside the
-  // archetype walk, then sorted by queue at the end.
-  let dispatch: DispatchEntry[] = [];
-  // 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();
-  // 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`,
-  // `Instances.transforms`) still flow through `_getArrayView` /
-  // `world.get(e, Instances)` -- only the `entity` source switches to
-  // `row.entity`.
-  //
-  // archVersion plumbing exception: the `RenderableSnapshot.instances
-  // .archVersion` cache key is keyed off the live archetype's mutation
-  // counter (record stage `instanceBuffers` cache invalidation). The
-  // QueryRow does not surface this number, so a single archetype
-  // graph access is retained for instance-bearing rows -- match by entity
-  // packed handle. AC-01 grep ≤ current - 1 still holds: the stale
-  // archetype-graph traversal commentary at the prior call site is gone.
-  // feat-20260521-sprite-atlas-animation M3 / T-16: SpriteRegionOverride
-  // column id for the sprite-bucket per-entity region override read
-  void SpriteRegionOverride;
-
-  const meshRendererQuery =
-    context.renderables === 'none'
-      ? []
-      : world
-          .query({
-            read: [MeshRenderer],
-            optional: [
-              Transform,
-              GlobalTransform,
-              MeshFilter,
-              Instances,
-              Skin,
-              Layer,
-              MorphWeights,
-              SpriteRegionOverride,
-              SpriteInstances,
-              Points,
-              Lines,
-              SortKey,
-            ],
-          })
-          .unwrap();
-  // QueryRow deliberately exposes component data, not an archetype version.
-  // The optimized ECS owner keeps table storage private, so instance-buffer
-  // invalidation uses a content fingerprint of the managed arrays instead.
-  const resolveArchVersion = (entity: EntityHandle): number => {
-    const values = [
-      worldInternal._getArrayView(entity, Instances, 'transforms'),
-      worldInternal._getArrayView(entity, SpriteInstances, 'transforms'),
-      worldInternal._getArrayView(entity, SpriteInstances, 'regions'),
-    ];
-    let hash = 2166136261;
-    for (const value of values) {
-      hash = Math.imul(hash ^ (value?.length ?? 0), 16777619) >>> 0;
-      if (value === undefined) continue;
-      for (let index = 0; index < value.length; index += 1) {
-        hash = Math.imul(hash ^ Math.fround(value[index] ?? 0), 16777619) >>> 0;
-      }
-    }
-    return hash;
-  };
-  // Pending entries are created with the current renderables.length, which is
-  // exactly the slot this entity receives if it survives culling. No other
-  // renderable can be pushed between staging and this entity's push, so publish
-  // the original fresh entries instead of cloning every submesh descriptor.
-  // A culled entity still discards its private pending array unchanged.
-  const flushPendingDispatch = (pending: readonly DispatchEntry[]): void => {
-    for (const entry of pending) dispatch.push(entry);
-  };
-  for (const row of meshRendererQuery) {
-    // K-2 archetype-edge sniff (scheme B): a missing optional component
-    // surfaces as an absent bundle key, not a row-internal optional chain.
-    // Presence-only checks use QueryRow.has so large array-bearing components
-    // are not materialised merely to answer a boolean question.
-    const hasTransform = row.has(Transform);
-    const meshFilter = row.get(MeshFilter);
-    const hasInstances = row.has(Instances);
-    const skin = row.get(Skin);
-    const morphWeightsView = worldInternal._getArrayView(row.entity, MorphWeights, 'weights');
-    const hasMeshFilter = meshFilter !== undefined;
-    const hasSkin = skin !== undefined;
-    // feat-20260625-sprite-instances-and-tilemap-terrain-static-batch M3 / w10:
-    // SpriteInstances optional component archetype-edge sniff. Three structured
-    // EcsError codes fire at the row-loop entry (D-6 fail-fast at extract):
-    //   - 'sprite-instances-mutually-exclusive-with-instances'
-    //       (hasInstances && hasSpriteInstances) — Instances + SpriteInstances peers.
-    //   - 'sprite-instances-requires-sprite-shading-model'
-    //       (materialSnap.materialShaderId !== 'forgeax::sprite') — non-sprite material.
-    //   - 'sprite-instances-count-mismatch'
-    //       (transforms.length / 16 !== regions.length / 4) — stride pair desync.
-    const hasSpriteInstances = row.has(SpriteInstances);
-    const points = row.get(Points);
-    const lines = row.get(Lines);
-    const sortKey = row.get(SortKey)?.value;
-    const pointsLinesComponent =
-      points !== undefined ? 'Points' : lines !== undefined ? 'Lines' : undefined;
-    const isRenderable = hasTransform && hasMeshFilter;
-
-    // The resolved world transform is read per-entity from the single
-    // `GlobalTransform.world` mat4 (propagateTransforms output) inside the row
-    // loop below. Normal structural paths materialize this carrier through
-    // Transform's generic ECS requirement; keep the defensive row check because
-    // an owner can explicitly remove a required component during recovery.
-    const fAssetHandle = meshFilter?.assetHandle;
-    // feat-20260520-2d-sprite-layer-mvp M-3 / w22: Layer column read here;
-    // value folded into each DispatchEntry so the render-system sort can use
-    // it as the primary transparent-sort key without a second ECS round-trip.
-    const fLayerValue = row.get(Layer)?.value;
-    // feat-20260608-tilemap-object-layer-rendering M3 / m3-t5: tilemap-spawned
-    // per-cell render entities (the ones `tilemap-chunk-extract-system`
-    // pushes via `spawnDerivedRenderEntities`) reach this loop via the same
-    // archetype edge that carries a sprite entity -- they all wear
-    // `MeshFilter.assetHandle === HANDLE_QUAD` + a `forgeax::sprite`-shaded
-    // material asset + the sprite-bucket `values.region` rectangle.
-    // For the per-entity Y-sort path (requirements §AC-12 / §AC-13):
-    //
-    //   sortKey = -(Transform.posY - effectivePivotY * |Transform.scaleY|)
-    //
-    // with `effectivePivotY = effectivePivotYForTilemapFlip(pivotY, pivotX,
-    // flipV, flipDiagonal)` from `tilemap-chunk-extract-system` (the SAME
-    // helper drives `spawnDerivedRenderEntities`, so the value the sort
-    // uses matches the value baked into `Transform.posY` -- charter P4
-    // single SSOT for the post-flip pivot). Sprite entities reuse the same
-    // formula but skip the flip composition (their pivot stays raw); both
-    // bucket types therefore feed one `transparentSortEntries` argsort
-    // step + share the `argsortInPlace` radix LSD primitive (plan-strategy
-    // §D-1 / §D-3). The detection lives on the material side -- detect a
-    // tilemap-spawned entity by `MeshFilter.assetHandle === HANDLE_QUAD`
-    // plus the `forgeax::sprite` shader id on `MeshRenderer.material`'s
-    // first pass + non-empty `values.region`; no new public ECS
-    // marker component lands (charter F1 minimum surface).
-    //
-    // Layer.value is now folded into each DispatchEntry.layer (fLayerValue
-    // column, read once per archetype pass above). render-system.ts
-    // `sortTransparentDispatch` applies (layer ASC, sortValue ASC) for all
-    // transparent-sort modes (0/1/2) using posY/pivotY/sizeY from the
-    // parallel renderables[] snapshot -- no second ECS round-trip needed.
-    // feat-20260527-sprite-nineslice M4 / w17 (AC-14): SpriteRegionOverride
-    // per-entity UV sub-rectangle. When the entity carries this component the
-    // 4-float `[uMin, vMin, uW, vH]` override displaces the asset-side
-    // `values.region` for this entity only — downstream 9-slice logic
-    // measures slices against this effective region.zw, so a half-width sub-
-    // sprite reduces the anchor budget to 0.5 rather than the asset's 1.0.
-    //
-    // SpriteRegionOverride.region is a fixed stride-4 value. Per-row reads
-    // route through `_getArrayView` for the zero-copy row window
-    // row-window slice (consistent with the variable-length array column
-    // reads -- K-3 carve-out keeps `_getArrayView` as the row-accessor of
-    // record for each non-scalar column).
-    const hasSpriteRegionOverride = row.has(SpriteRegionOverride);
-    // feat-20260523-skin-skeleton-animation M2 / T-21: Skin component
-    // column views for coexistence check + joint despawn fail-fast.
-    // `skeleton` holds the packed Handle<SkeletonAsset>; `joints` holds
-    // the packed Entity u32 array (N x one u32 each).
-    const skinSkeletonView = skin?.skeleton;
-
-    let archVersion = 0;
-    if (hasInstances || hasSpriteInstances) {
-      // All rows in this callback share one archetype.  Only these two
-      // instance-bearing paths consume the version in their cache key.
-      archVersion = resolveArchVersion(row.entity);
-    }
-
-    {
-      // feat-20260608 M2 / w11: read materials array via _getArrayView
-      const entity = row.entity;
-      if (isRenderable && visibility?.effective(entity) === 'hidden') {
-        explicitlyHidden.add(entity);
-        continue;
-      }
-      const layerVal = fLayerValue ?? 0;
-      // bug-20260709-builtin-quad-withoutaabb-disables-sprite-frustum-cu M2.5
-      // (carries PR #598 feat-20260703 D-7): dispatch entries for this entity
-      // are staged locally and flushed into the shared `dispatch[]` array
-      // ONLY when the entity survives the frustum-cull `continue` below —
-      // same cull-passed branch as the paired `renderables.push`. Prior to
-      // this fix the three `dispatch.push` sites ran before the cull check,
-      // so a culled entity left dangling entries whose `renderableIndex`
-      // aliased the slot a LATER visible entity occupied — surfacing as the
-      // pbr-mesh-array-bgl vs hdrp-unified-bgl-group2 BGL/PL mismatch on
-      // the deferred-shading smoke (PR #598 CI). Pure ordering fix; cull
-      // logic and MeshRenderer contract unchanged.
-      const pendingDispatch: DispatchEntry[] = [];
-      const materialsView = worldInternal._getArrayView(entity, MeshRenderer, 'materials') as
-        | Uint32Array
-        | undefined;
-      const materialCount = materialsView?.length ?? 0;
-      let materialHandles = Array.from(materialsView ?? []);
-      let materialBindingSources: MeshMaterialBindingSource[] = materialHandles.map(
-        () => 'renderer-override',
-      );
-      let materialBindingDiagnostics: MeshMaterialBindingDiagnostic[] = [];
-      let gpuDrivenSubmeshes: readonly MeshAsset['submeshes'][number][] = [];
-      let gpuDrivenIndexed = false;
-      let gpuDrivenGeometry: GpuDrivenGeometryReceipt | undefined;
-
-      // Resolve instance overrides against mesh-owned slot defaults once.
-      const fAssetHandleVal = fAssetHandle;
-      if (
-        fAssetHandleVal !== undefined &&
-        fAssetHandleVal !== 0 &&
-        assets !== undefined &&
-        assets !== null
-      ) {
-        const meshHandle = toShared<'MeshAsset'>(fAssetHandleVal);
-        const meshRes = resolveAssetHandle<Asset>(world, meshHandle);
-        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,
-          };
-          // 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
-          // and never infer slot topology from their submeshes.
-          if (!Array.isArray(meshAsset.materialSlots) && world.get(entity, GlyphText).ok) {
-            ensureGlyphMeshMaterialSlots(world, meshHandle);
-          }
-          const resolvedBindings = resolveMeshMaterialBindings(meshAsset, materialsView ?? [], {
-            isValidOverride(handle) {
-              const resolved = resolveAssetHandle(world, toShared<'MaterialAsset'>(handle));
-              return resolved.ok && resolved.value.kind === 'material';
-            },
-            resolveMeshDefault(defaultGuid) {
-              const guidText = AssetGuid.format(defaultGuid);
-              if (assets.lookup<Asset>(guidText)?.kind !== 'material') return undefined;
-              return internSharedRefFromGuid(world, assets, guidText, 'MaterialAsset') as
-                | number
-                | undefined;
-            },
-          });
-          if (!resolvedBindings.ok) {
-            if (resolvedBindings.code === 'mesh-material-slots-missing') {
-              worldInternal._routeError(
-                new AssetError({
-                  code: 'load-failed',
-                  expected: 'every MeshAsset producer supplies materialSlots[]',
-                  hint: `fix the MeshAsset producer; renderer inheritance never guesses slot topology (mesh=${guid}, entity=${entity}, vertices=${meshAsset.vertices.length}, indices=${meshAsset.indices?.length ?? 0})`,
-                  detail: {
-                    referencedByGuid: guid,
-                    referencedByKind: 'mesh',
-                    subAssetGuid: '<material-slots-missing>',
-                    sourceField: { fieldName: 'materialSlots' },
-                  },
-                }),
-                {
-                  severity: Severity.Error,
-                  systemName: 'RenderSystem.extract (mesh-material-slots-missing)',
-                },
-              );
-              continue;
-            }
-            const materialGuid = AssetGuid.format(resolvedBindings.defaultMaterial);
-            worldInternal._routeError(
-              new AssetError({
-                code: 'load-failed',
-                expected: `MeshAsset materialSlots[${resolvedBindings.slotIndex}] default ${materialGuid} is ready and a MaterialAsset`,
-                hint: `loadByGuid(meshGuid) must recursively load the declared default material; mesh=${guid}, slot=${resolvedBindings.slotIndex}, material=${materialGuid}`,
-                detail: {
-                  referencedByGuid: guid,
-                  referencedByKind: 'mesh',
-                  subAssetGuid: materialGuid,
-                  sourceField: {
-                    fieldName: 'materialSlots',
-                    arrayIndex: resolvedBindings.slotIndex,
-                  },
-                },
-              }),
-              {
-                severity: Severity.Error,
-                systemName: 'RenderSystem.extract (mesh-default-not-ready)',
-              },
-            );
-            continue;
-          }
-          materialHandles = resolvedBindings.bindings.map((binding) => binding.handle);
-          materialBindingSources = resolvedBindings.bindings.map((binding) => binding.source);
-          materialBindingDiagnostics = resolvedBindings.diagnostics.map((diagnostic) => ({
-            ...diagnostic,
-            detail:
-              diagnostic.code === 'mesh-renderer-material-override-overflow'
-                ? {
-                    expectedCount: meshAsset.materialSlots.length,
-                    actualCount: materialCount,
-                    meshAssetGuid: guid,
-                  }
-                : {
-                    meshAssetGuid: guid,
-                    slotIndex: diagnostic.slotIndex,
-                    handle: diagnostic.handle ?? 0,
-                  },
-          }));
-          for (const diagnostic of resolvedBindings.diagnostics) {
-            worldInternal._routeError(
-              new AssetError({
-                code: diagnostic.code,
-                expected:
-                  diagnostic.code === 'mesh-renderer-material-override-overflow'
-                    ? `materials.length <= materialSlots.length (${meshAsset.materialSlots.length})`
-                    : `materials[${diagnostic.slotIndex}] resolves to a live MaterialAsset`,
-                hint: ASSET_ERROR_HINTS[diagnostic.code],
-                detail:
-                  diagnostic.code === 'mesh-renderer-material-override-overflow'
-                    ? {
-                        expectedCount: meshAsset.materialSlots.length,
-                        actualCount: materialCount,
-                        meshAssetGuid: guid,
-                      }
-                    : {
-                        meshAssetGuid: guid,
-                        slotIndex: diagnostic.slotIndex,
-                        handle: diagnostic.handle ?? 0,
-                      },
-              }),
-              {
-                severity: Severity.Warning,
-                systemName: `RenderSystem.extract (${diagnostic.code})`,
-              },
-            );
-          }
-        }
-      }
-
-      if (materialHandles.length === 0) {
-        materialHandles = [0];
-        materialBindingSources = ['engine-default'];
-      }
-
-      // Use the first material handle for the entity-level snapshot
-      // (shading-model dispatch routing + multi-pass DispatchEntry. Per-
-      // submesh materials[i>=1] are resolved by `resolveMaterialSnapshot`
-      // below into the `materials[]` array, used by the record stage to
-      // upload N material UBO slots and bind the i-th slot before the
-      // i-th submesh draw.) -- feat-20260608 M5 amend / w11-a.
-      const handleRaw = materialHandles[0] ?? 0;
-
-      const cachedMaterial =
-        handleRaw !== 0 && !hasSpriteRegionOverride && !hasSkin
-          ? materialSnapshotCache.get(handleRaw)
-          : undefined;
-
-      let materialSnap: MaterialSnapshot;
-
-      if (cachedMaterial !== undefined) {
-        materialSnap = cachedMaterial.snapshot;
-        if (isRenderable) {
-          appendMaterialDispatchEntries(
-            pendingDispatch,
-            cachedMaterial.passes,
-            entity,
-            handleRaw,
-            renderables.length,
-            layerVal,
-            materialSnap.paramSnapshot,
-          );
-        }
-      } else if (handleRaw === 0 || assets === undefined || assets === null) {
-        // case B: missing-spec sentinel -> mid-grey defaultMaterialSnapshot.
-        materialSnap = defaultMaterialSnapshot(handleRaw);
-      } else {
-        const tagged = toShared<'MaterialAsset'>(handleRaw);
-        const stablePersistentCached =
-          !hasSpriteRegionOverride && !hasSkin
-            ? readStablePersistentMaterialSnapshot(
-                persistentMaterialSnapshotCache,
-                handleRaw,
-                assets,
-              )
-            : undefined;
-        if (stablePersistentCached !== undefined) {
-          materialSnapshotCache.set(handleRaw, stablePersistentCached);
-          materialSnap = stablePersistentCached.snapshot;
-          if (isRenderable) {
-            appendMaterialDispatchEntries(
-              pendingDispatch,
-              stablePersistentCached.passes,
-              entity,
-              handleRaw,
-              renderables.length,
-              layerVal,
-              materialSnap.paramSnapshot,
-            );
-          }
-        } else {
-          const res = resolveAssetHandle(world, tagged);
-          if (!res.ok) {
-            if (isRenderable) {
-              const rhiErr = new RhiError({
-                code: 'asset-not-registered',
-                expected: 'MeshRenderer.material in AssetRegistry',
-                hint: 'catalog the material via assetRegistry.catalog(guid, asset) + world.allocSharedRef before spawn, or remove the material field to fall back to default',
-                detail: { assetHandle: handleRaw },
-              });
-              worldInternal._routeError(rhiErr, {
-                severity: Severity.Error,
-                systemName: 'RenderSystem.extract (material asset-not-registered)',
-              });
-            }
-            continue;
-          }
-          const asset = res.value;
-          if (asset.kind !== 'material') {
-            materialSnap = defaultMaterialSnapshot(handleRaw);
-          } else {
-            // feat-20260529 M3 / w11: material parent chain inheritance via
-            // read-through _materialWalk accessor (plan-strategy D-6).
-            // The old direct asset.passes / asset.values read never
-            // walked the parent chain, causing broken-inheritance (root cause).
-            const resolvedResult = walkMaterialPassesOverSharedRefs(world, tagged, assets);
-            if (!resolvedResult.ok) {
-              // AC-09 / S-7 / q8=A: passes-empty or cycle must fire structured
-              // error through _routeError (same routing as asset-not-registered
-              // branch above). Silent continue is forbidden because it produces
-              // a black screen indistinguishable from a content bug.
-              const err = resolvedResult.error;
-              switch (err.code) {
-                case 'material-parent-not-found':
-                case 'material-no-effective-pass':
-                case 'material-value-unknown':
-                case 'material-value-type-mismatch':
-                case 'material-contract-program-mismatch':
-                  worldInternal._routeError(err, {
-                    severity: Severity.Error,
-                    systemName: `RenderSystem.extract (${err.code})`,
-                  });
-                  break;
-                case 'material-circular-inheritance':
-                  worldInternal._routeError(err, {
-                    severity: Severity.Error,
-                    systemName: 'RenderSystem.extract (material-circular-inheritance)',
-                  });
-                  break;
-                default:
-                  // Exhaustive guard: unhandled error codes from _materialWalk
-                  // surface an internal assertion to avoid silent continuation.
-                  worldInternal._routeError(err, {
-                    severity: Severity.Error,
-                    systemName: `RenderSystem.extract (_materialWalk: ${err.code})`,
-                  });
-              }
-              continue;
-            }
-            const resolved = resolvedResult.value;
-            const allPasses = resolved.passes;
-            const firstPassShader =
-              allPasses.length > 0
-                ? runtimeMaterialShaderId(allPasses[0]?.program.module, allPasses[0]?.name)
-                : undefined;
-            const pv = materialValuesToLinearRuntime(
-              resolved.values,
-              materialColorParameterSchema(resolved.parameters ?? [], firstPassShader, assets),
-              resolved.colorSpace,
-            ) as Readonly<Record<string, unknown>>;
-
-            const baseColorPv = pv.baseColor as readonly number[] | undefined;
-            const baseColor = vec3.create(
-              baseColorPv?.[0] ?? 1,
-              baseColorPv?.[1] ?? 1,
-              baseColorPv?.[2] ?? 1,
-            );
-            const metallicPv = typeof pv.metallic === 'number' ? pv.metallic : 0;
-            const roughnessPv = typeof pv.roughness === 'number' ? pv.roughness : 0.5;
-            const clearcoatPv = typeof pv.clearcoat === 'number' ? pv.clearcoat : 0;
-            const clearcoatRoughnessPv =
-              typeof pv.clearcoatRoughness === 'number' ? pv.clearcoatRoughness : 0.5;
-            const specularTintPv = pv.specularTint as readonly number[] | undefined;
-            const normalScalePv = materialNormalScale(pv);
-
-            const paramSnap: Record<string, number | number[] | string> = {};
-            for (const [k, v] of Object.entries(pv)) {
-              if (typeof v === 'number') paramSnap[k] = v;
-              else if (typeof v === 'string') paramSnap[k] = v;
-              else if (Array.isArray(v) && v.every((x) => typeof x === 'number')) {
-                paramSnap[k] = v as number[];
-              }
-            }
-
-            const materialParamSchema = materialParametersToParamSchema(
-              resolved.parameters ?? [],
-              firstPassShader,
-            );
-            // feat-20260611-fox-skinning-vertex-attribute-chain M4 / w17 (D-5):
-            // bidirectional Skin <-> pbr-skin material fail-fast at extract.
-            // Skin component without a forgeax::pbr-skin first-pass material
-            // would draw with a non-skin shader against the 18-float vertex
-            // buffer (joints/weights bytes interpreted as garbage). Conversely
-            // a forgeax::pbr-skin material against a 12-float (unskinned) mesh
-            // would have @location(4)/@location(5) read uninitialized memory.
-            // Both cases route through `_routeError` + `continue` so a single
-            // misconfigured entity does NOT abort the whole frame's draw list
-            // (charter P3 explicit failure + plan-decisions D-5 over `return err`).
-            {
-              const hasSkinSkel =
-                hasSkin &&
-                skinSkeletonView !== undefined &&
-                skinSkeletonView !== undefined &&
-                skinSkeletonView !== 0;
-              const isPbrSkinMaterial = firstPassShader === 'forgeax::pbr-skin';
-              if (hasSkinSkel && !isPbrSkinMaterial) {
-                worldInternal._routeError(new SkinMaterialMismatchError(entity, firstPassShader), {
-                  severity: Severity.Error,
-                  systemName: 'RenderSystem.extract (skin-material-mismatch)',
-                });
-                continue;
-              }
-              if (isPbrSkinMaterial && fAssetHandleVal !== undefined && fAssetHandleVal !== 0) {
-                const meshHandleForSkinCheck = toShared<'MeshAsset'>(fAssetHandleVal);
-                const meshResForSkinCheck = resolveAssetHandle<MeshAsset>(
-                  world,
-                  meshHandleForSkinCheck,
-                );
-                if (meshResForSkinCheck.ok) {
-                  const meshAttrs = meshResForSkinCheck.value.attributes;
-                  const hasSkinIdx = meshAttrs.skinIndex !== undefined;
-                  const hasSkinWt = meshAttrs.skinWeight !== undefined;
-                  if (!hasSkinIdx || !hasSkinWt) {
-                    const missing: 'skinIndex' | 'skinWeight' | 'both' =
-                      !hasSkinIdx && !hasSkinWt ? 'both' : !hasSkinIdx ? 'skinIndex' : 'skinWeight';
-                    worldInternal._routeError(new MaterialSkinAttrMissingError(entity, missing), {
-                      severity: Severity.Error,
-                      systemName: 'RenderSystem.extract (material-skin-attr-missing)',
-                    });
-                    continue;
-                  }
-                }
-              }
-            }
-            // feat-20260625-refactor-sprite-as-transparent-mesh M3 / w12 (D-3):
-            // sprite materials now flow through the same generic paramSchema-
-            // driven extract path PBR / unlit use. The narrow `forgeax::sprite`
-            // exception block below covers exactly 2 plan-authorised cases:
-            //   1. SpriteRegionOverride per-entity region displacement (Q4=a)
-            //   2. flipX / flipY -> region fold (plan-strategy D-8)
-            // No legacy values field-name shim; demos and SpriteParamValues
-            // are UBO-aligned (no `texture` / `baseColor` / `pivot` / `slices`
-            // / `sliceMode` keys reaching this code path). AGENTS.md §Change
-            // stance: "no shim layer, no v1/v2 dual-path".
-            //
-            // feat-20260624 M1' / t6: `'forgeax::sprite-lit'` walks the same
-            // sprite-family vertex path (VsOut byte-identical, paramSchema
-            // mirror) so the SAME 2 folds apply — extending `isSprite` to
-            // cover both shader ids keeps the narrowing-point count at 1
-            // (plan-strategy §1.6 + D-1: mirror sprite, no new branch).
-            const isSprite =
-              firstPassShader === 'forgeax::sprite' || firstPassShader === 'forgeax::sprite-lit';
-
-            // feat-20260613-material-paramschema-driven-binding M4 / w23
-            // (D-5 graceful): paramSchema-driven texture-field validation.
-            // For each handle-shaped paramValue (typeof === 'number'),
-            // verify it actually points at a registered texture asset
-            // when the field is declared as a texture in the shader's
-            // paramSchema; mis-typed handles (e.g. a scalar f32 stored as
-            // int 0 the M4 / w22 graceful fallback resolved to a wrong
-            // sub-asset) are dropped here so the record stage falls back
-            // to MISSING_TEXTURE_HANDLE (default white) without raising.
-            const validateTextureHandle = (
-              fieldName: string,
-              raw: unknown,
-            ): Handle<'TextureAsset', 'shared'> | undefined => {
-              // feat-20260614 M8 (D-19): a string value is an embedded texture
-              // GUID; resolve it to a column handle via catalog + allocSharedRef
-              // before validation. A number is an already-minted column handle.
-              let handle: Handle<'TextureAsset', 'shared'>;
-              const textureRef = materialTextureRef(raw);
-              const textureGuid = assetReferenceText(textureRef);
-              if (textureGuid !== undefined) {
-                if (assets === null || assets === undefined) return undefined;
-                // M4: intern so the GUID mints one stable handle per World
-                // instead of a fresh slot every frame (GPU residency relies on
-                // a stable handleSlot). onLastRelease -> gpuStore.evictTexture.
-                const interned = internSharedRefFromGuid(
-                  world,
-                  assets,
-                  textureGuid,
-                  'TextureAsset',
-                );
-                if (interned === undefined) return undefined;
-                handle = interned;
-              } else if (typeof textureRef === 'number') {
-                handle = toShared<'TextureAsset'>(textureRef);
-              } else {
-                return undefined;
-              }
-              if (assets === null || assets === undefined) return handle;
-              const declaredFields = materialTextureFields(
-                firstPassShader,
-                materialParamSchema.length > 0
-                  ? derive(materialParamSchema).textureFieldNames
-                  : firstPassShader !== undefined
-                    ? assets.materialShaderTextureFieldNames(firstPassShader)
-                    : undefined,
-              );
-              // Shader not registered (R-4 cross-worktree path) -> trust the
-              // raw handle and let the record stage / GPU layer surface each
-              // mismatch via MISSING_TEXTURE_HANDLE.
-              if (declaredFields === undefined) return handle;
-              // Field is not declared as a texture by the shader -> the
-              // loader's "try every int" fallback misclassified a scalar;
-              // drop the slot so the record stage uses the default white.
-              if (
-                !declaredFields.has(fieldName) &&
-                !isEngineInjectedTextureField(firstPassShader, fieldName)
-              ) {
-                return undefined;
-              }
-              // Field declared as texture: verify the handle's asset kind.
-              const assetRes = resolveAssetHandle(world, handle);
-              if (!assetRes.ok) return undefined;
-              const kind = (assetRes.value as { kind?: string }).kind;
-              if (kind !== 'texture') return undefined;
-              return handle;
-            };
-            // feat-20260614 M8 (D-19): resolve a sampler / texture paramValue
-            // that may be an embedded GUID string (catalog + allocSharedRef) or
-            // an already-minted column handle (number passthrough).
-            const resolveParamHandle = <B extends string>(
-              raw: unknown,
-              brand: B,
-            ): Handle<B, 'shared'> | undefined => {
-              const value = materialTextureRef(raw);
-              if (typeof value === 'number') return toShared<B>(value);
-              const guid = assetReferenceText(value);
-              if (guid !== undefined) {
-                if (assets === null || assets === undefined) return undefined;
-                // M4: intern the GUID -> column-handle resolution (one stable
-                // handle per (world, guid, brand), reused across frames).
-                return internSharedRefFromGuid(world, assets, guid, brand);
-              }
-              return undefined;
-            };
-            // feat-20260621-learn-render-5-5-parallax M2 / w7 (D-3): iterate the
-            // shader's derive(paramSchema).textureFieldNames SSOT so the Nth
-            // user-region texture (e.g. parallax heightTexture) is validated +
-            // carried, replacing the hardcoded 3-field list. validateTextureHandle
-            // already drops fields a shader doesn't declare as a texture.
-            const userRegionFields =
-              materialTextureFields(
-                firstPassShader,
-                materialParamSchema.length > 0
-                  ? derive(materialParamSchema).textureFieldNames
-                  : firstPassShader !== undefined && assets !== null && assets !== undefined
-                    ? assets.materialShaderTextureFieldNames(firstPassShader)
-                    : undefined,
-              ) ?? BUILTIN_USER_REGION_TEXTURE_FIELDS;
-            const textureHandles = new Map<string, Handle<'TextureAsset', 'shared'>>();
-            const videoTextureFields = new Map<string, Handle<'VideoAsset', 'shared'>>();
-            for (const field of userRegionFields) {
-              // D-5: a video-kind paramValue routes to the transient path
-              // (videoTextureFields), NOT validateTextureHandle (which drops
-              // kind!=='texture', the R-7 silent-fail path). Static fields fall
-              // through to validateTextureHandle unchanged.
-              const videoHandle =
-                assets !== null && assets !== undefined
-                  ? resolveVideoFieldHandle(pv[field], world, assets)
-                  : undefined;
-              if (videoHandle !== undefined) {
-                videoTextureFields.set(field, videoHandle);
-                continue;
-              }
-              const handle = validateTextureHandle(field, pv[field]);
-              if (handle !== undefined) textureHandles.set(field, handle);
-            }
-            const baseColorTextureHandle = textureHandles.get('baseColorTexture');
-            const metallicRoughnessTextureHandle = textureHandles.get('metallicRoughnessTexture');
-            const normalTextureHandle = textureHandles.get('normalTexture');
-            const samplerHandles = collectMaterialTextureSamplers(pv, (value) =>
-              resolveParamHandle(materialTextureRef(value), 'SamplerAsset'),
-            );
-            const emissiveTextureHandle = validateTextureHandle(
-              'emissiveTexture',
-              pv.emissiveTexture,
-            );
-            const occlusionTextureHandle = validateTextureHandle(
-              'occlusionTexture',
-              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
-            // LDR split + premultiplied-alpha blend decision without
-            // re-reading passes[]. feat-20260626-collapse M2: derive from
-            // `passes[0].renderState.blend !== undefined` (blend presence is
-            // the SSOT after MaterialPass.transparent was dropped).
-            // Result is plain boolean (always defined here) — written as-is
-            // into the snapshot (`boolean | undefined` field, see L759).
-            const firstPassTransparent: boolean = allPasses[0]?.renderState?.blend !== undefined;
-
-            // feat-20260625-refactor-sprite-as-transparent-mesh M3 / w12 (D-8):
-            // narrow `forgeax::sprite` extract block --- folds the legacy user
-            // values format (flipX / flipY / slices / sliceMode + free
-            // region / pivot) into the UBO-aligned paramSnapshot vec4 fields
-            // (region / pivotAndSize / slicesAndMode + colorTint). Also folds
-            // per-entity SpriteRegionOverride (Q4=a). After this block the
-            // generic else branch picks up the snapshot via the same writer
-            // path PBR / unlit use; no more shadingModel='sprite' arm, no
-            // spriteFields POD (AC-02 / AC-07: extract has exactly 2 hard
-            // `forgeax::sprite` checks --- this fold + the slices mesh swap on
-            // the record side).
-            if (isSprite) {
-              // SpriteRegionOverride: per-entity per-frame region displacement.
-              let overrideRegion: readonly [number, number, number, number] | undefined;
-              if (hasSpriteRegionOverride) {
-                const overrideView = worldInternal._getArrayView(
-                  entity,
-                  SpriteRegionOverride,
-                  'region',
-                ) as Float32Array | undefined;
-                if (overrideView !== undefined && overrideView.length >= 4) {
-                  overrideRegion = [
-                    overrideView[0] ?? 0,
-                    overrideView[1] ?? 0,
-                    overrideView[2] ?? 1,
-                    overrideView[3] ?? 1,
-                  ];
-                }
-              }
-              // Region resolution priority: SpriteRegionOverride > paramSnapshot.
-              // region (UBO-aligned user input) > [0,0,1,1] identity.
-              const regionPv = paramSnap.region as readonly number[] | undefined;
-              let regionX = overrideRegion?.[0] ?? regionPv?.[0] ?? 0;
-              let regionY = overrideRegion?.[1] ?? regionPv?.[1] ?? 0;
-              let regionZ = overrideRegion?.[2] ?? regionPv?.[2] ?? 1;
-              let regionW = overrideRegion?.[3] ?? regionPv?.[3] ?? 1;
-              // flipX / flipY fold into region (D-8): the shader does
-              // `uv * region.zw + region.xy`, so flipping along U is a sign
-              // negation of region.z plus an origin offset.
-              const flipXPv = typeof pv.flipX === 'number' ? pv.flipX : 0;
-              const flipYPv = typeof pv.flipY === 'number' ? pv.flipY : 0;
-              if (flipXPv !== 0) {
-                regionX += regionZ;
-                regionZ = -regionZ;
-              }
-              if (flipYPv !== 0) {
-                regionY += regionW;
-                regionW = -regionW;
-              }
-              paramSnap.region = [regionX, regionY, regionZ, regionW];
-              // Guard: slicesAndMode must be present and zero for non-9-slice
-              // sprites so the record-stage UBO writer (applyParamSnapshotToUbo)
-              // writes [0,0,0,0] at offset 48 instead of leaving the
-              // buildPbrMaterialUboPayload PBR baseline (e.g. occlusionStrength=1
-              // at that slot). A non-zero slicesAndMode trips `useSlices=true`
-              // in sprite.wgsl, which degenerates HANDLE_QUAD geometry → invisible.
-              if (!('slicesAndMode' in paramSnap)) {
-                (paramSnap as Record<string, unknown>).slicesAndMode = [0, 0, 0, 0];
-              }
-            }
-
-            // Generic materialShaderId snapshot --- sprite included now flows
-            // through this single branch (plan-strategy D-3 / AC-01 / AC-02 /
-            // AC-07). The sprite block above only writes paramSnap.region (D-8
-            // SpriteRegionOverride + flip fold); the rest of the UBO is filled
-            // by the same paramSchema-driven path PBR / unlit use.
-            materialSnap = {
-              baseColor,
-              metallic: metallicPv,
-              roughness: roughnessPv,
-              clearcoat: clearcoatPv,
-              clearcoatRoughness: clearcoatRoughnessPv,
-              ...(specularTintPv !== undefined && {
-                specularTint: [
-                  specularTintPv[0] ?? 1,
-                  specularTintPv[1] ?? 1,
-                  specularTintPv[2] ?? 1,
-                ] as readonly [number, number, number],
-              }),
-              normalScale: normalScalePv,
-              materialShaderId: firstPassShader,
-              materialHandle: handleRaw,
-              renderState: pipelineRenderState(allPasses[0]?.renderState),
-              paramSnapshot: paramSnap,
-              ...(materialParamSchema.length > 0 && { materialParamSchema }),
-              ...(textureCoordinates.size > 0 && { textureCoordinates }),
-              ...(samplerHandles.size > 0 && { samplerHandles }),
-              ...(textureHandles.size > 0 && { textureHandles }),
-              ...(textureSources.size > 0 && { textureSources }),
-              ...(videoTextureFields.size > 0 && { videoTextureFields }),
-              ...(baseColorTextureHandle !== undefined && {
-                baseColorTexture: baseColorTextureHandle,
-              }),
-              ...(metallicRoughnessTextureHandle !== undefined && {
-                metallicRoughnessTexture: metallicRoughnessTextureHandle,
-              }),
-              ...(normalTextureHandle !== undefined && { normalTexture: normalTextureHandle }),
-              ...(emissivePv !== undefined && {
-                emissive: [emissivePv[0] ?? 0, emissivePv[1] ?? 0, emissivePv[2] ?? 0] as readonly [
-                  number,
-                  number,
-                  number,
-                ],
-              }),
-              ...(typeof pv.emissiveIntensity === 'number' && {
-                emissiveIntensity: pv.emissiveIntensity,
-              }),
-              ...(emissiveTextureHandle !== undefined && {
-                emissiveTexture: emissiveTextureHandle,
-              }),
-              ...(occlusionTextureHandle !== undefined && {
-                occlusionTexture: occlusionTextureHandle,
-              }),
-              ...(typeof pv.occlusionStrength === 'number' && {
-                occlusionStrength: pv.occlusionStrength,
-              }),
-              transparent: firstPassTransparent,
-            };
-
-            if (!hasSpriteRegionOverride && !hasSkin) {
-              const stored = storeMaterialSnapshot(
-                materialSnapshotCache,
-                handleRaw,
-                materialSnap,
-                allPasses,
-                asset,
-                assets,
-              );
-              if (stored.crossFrameSafe) persistentMaterialSnapshotCache?.set(handleRaw, stored);
-            }
-
-            // Build dispatch entries from resolved passes.
-            if (isRenderable) {
-              appendMaterialDispatchEntries(
-                pendingDispatch,
-                allPasses,
-                entity,
-                handleRaw,
-                renderables.length,
-                layerVal,
-                paramSnap,
-              );
-            }
-          }
-        }
-      }
-
-      // feat-20260609 M2/M5 corrective fixup: default-material entities
-      // (handleRaw===0 / case-B MeshRenderer{data:{}}) must produce
-      // ShadowCaster dispatch entries so the shadow pass includes them.
-      // The pre-existing logic only builds dispatch entries from
-      // resolved material assets; defaultMaterialSnapshot() (mid-grey unlit)
-      // left dispatch empty, causing shadow-m2/m3 test failures.
-      // Requirements §10.5: shadow-casting is default behaviour, opt-out
-      // via castShadow:false.  The default material has no opt-out, so
-      // it casts shadows.
-      //
-      // CHARTER NOTE (feat-20260609 T-005-a): the URP literals
-      // `LightMode: 'ShadowCaster'` / `LightMode: 'Forward'` below are a
-      // local URP-bridge — they mirror what `Materials.unlit({ castShadow:
-      // true })` produces at the asset layer.  The default-material
-      // handle=0 path bypasses asset registration, so we synthesize the
-      // same dispatch shape inline.  Follow-up cleanup (F-1 from
-      // implement-review R1): thread default materials through the
-      // Materials factory so this block can call into the shared
-      // passes[] producer.
-      // tweak-20260701 M1: `materialSnap.shadingModel === 'unlit'` removed —
-      // for handleRaw===0, defaultMaterialSnapshot() was always unlit
-      // (the shadingModel check was a tautology); the isRenderable &&
-      // handleRaw===0 guard alone preserves the exact same dispatch shape.
-      if (isRenderable && handleRaw === 0) {
-        const shadowCasterTags: Record<string, string> = { LightMode: 'ShadowCaster' };
-        const nextRenderableIndex = renderables.length;
-        // M2.5: stage into pendingDispatch; flushed at the renderable push
-        // site below only when the entity survives cull.
-        pendingDispatch.push({
-          entityIndex: entity,
-          materialHandle: 0,
-          renderableIndex: nextRenderableIndex,
-          passIndex: 0,
-          queue: 2000,
-          layer: layerVal,
-          tags: shadowCasterTags,
-          renderState: undefined,
-          defines: undefined,
-          vertexEntry: 'vs_main',
-          fragmentEntry: undefined,
-          materialShaderId: 'forgeax::default-shadow-caster',
-          paramSnapshot: {},
-        });
-        // Also add a Forward pass entry so the entity renders in the
-        // main scene pass (mirrors Materials.unlit default).
-        appendMaterialDispatchEntries(
-          pendingDispatch,
-          [DEFAULT_FORWARD_PASS],
-          entity,
-          0,
-          nextRenderableIndex,
-          layerVal,
-          {},
-          1,
-        );
-      }
-
-      if (isRenderable) {
-        // feat-20260612 M2 / m2-6: Skin + Instances coexistence + per-joint
-        // dangling fail-fast + real palette slice allocation. Replaces the
-        // 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;
-        if (hasSkin) {
-          const skeletonHandleRaw = skinSkeletonView;
-          if (
-            skeletonHandleRaw !== undefined &&
-            skeletonHandleRaw !== 0 &&
-            assets !== undefined &&
-            assets !== null
-          ) {
-            // Skin + Instances coexistence is forbidden (D-10).
-            if (hasInstances) {
-              worldInternal._routeError(new SkinInstancesCoexistForbiddenError(entity), {
-                severity: Severity.Error,
-                systemName: 'RenderSystem.extract (skin-instances-coexist)',
-              });
-
-              continue;
-            }
-            // (a) Resolve skeleton asset; on failure -> skeleton-resolve-failed.
-            const skeletonHandle = toShared<'SkeletonAsset'>(skeletonHandleRaw);
-            const skeletonRes = resolveAssetHandle<SkeletonAsset>(world, skeletonHandle);
-            if (!skeletonRes.ok || skeletonRes.value.kind !== 'skeleton') {
-              worldInternal._routeError(new SkeletonResolveFailedError(entity, skeletonHandleRaw), {
-                severity: Severity.Error,
-                systemName: 'RenderSystem.extract (skeleton-resolve-failed)',
-              });
-              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;
-            const jointsLength = skinJoints.length;
-            if (jointsLength !== skeleton.jointCount) {
-              worldInternal._routeError(
-                new JointCountMismatchError(entity, skeleton.jointCount, jointsLength),
-                {
-                  severity: Severity.Error,
-                  systemName: 'RenderSystem.extract (joint-count-mismatch)',
-                },
-              );
-              continue;
-            }
-            // (c) Resolve only each joint's GlobalTransform.world column. The
-            // transient view is consumed before a structural mutation and
-            // therefore preserves the same dangling-joint behavior without
-            // constructing every other Transform field.
-            // Build mat4 list eagerly so write happens once per entity (no
-            // half-written slice on dangling).
-            const jointWorlds = new Array<Mat4>(skeleton.jointCount);
-            let jointDangling = -1;
-            for (let jIdx = 0; jIdx < skeleton.jointCount; jIdx++) {
-              const jointEntityRaw = skinJoints[jIdx] ?? 0;
-              const jointEntity = jointEntityRaw as EntityHandle;
-              const jointWorld = worldInternal._getArrayView(jointEntity, GlobalTransform, 'world');
-              if (jointWorld === undefined) {
-                jointDangling = jIdx;
-                break;
-              }
-              // The allocator consumes the canonical Mat4 brand. Copy the
-              // column view into that owner-created value so the ECS storage
-              // view never crosses the math brand boundary by assertion.
-              const jointWorldMat = mat4.create();
-              jointWorldMat.set(jointWorld);
-              jointWorlds[jIdx] = jointWorldMat;
-            }
-            if (jointDangling >= 0) {
-              worldInternal._routeError(new JointEntityDanglingError(entity, jointDangling), {
-                severity: Severity.Error,
-                systemName: 'RenderSystem.extract (joint-entity-dangling)',
-              });
-              continue;
-            }
-            // (d) Slice the IBM flat Float32Array into per-joint Float32Arrays.
-            //     skeleton.inverseBindMatrices length === jointCount * 16.
-            const ibmFlat = skeleton.inverseBindMatrices;
-            const ibms: Float32Array[] = new Array<Float32Array>(skeleton.jointCount);
-            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.
-            if (skinPaletteAllocator !== null) {
-              const slice = skinPaletteAllocator.allocateSlice(skeleton.jointCount);
-              skinPaletteAllocator.writeJointPalette(slice, ibms, jointWorlds);
-              skinSlice = {
-                jointCount: slice.jointCount,
-                byteOffset: slice.byteOffset,
-                buffer: slice.buffer,
-              };
-            }
-          }
-        }
-
-        // 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 GlobalTransform.world column array view. The
-        // record stage copies these 16 floats into the mesh SSBO with zero
-        // per-snapshot `mat4.compose` (AC-07). A stale slot (generation gone)
-        // skips the renderable, mirroring the Instances dangling-row sweep.
-        // 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;
-        const worldMat = new Float32Array(worldView);
-        const transformSnap: TransformSnapshot = { world: worldMat };
-        // feat-20260608 M5 amend / w11-a: per-submesh `materials[]` array
-        // aligned 1-1 with `MeshAsset.submeshes[]`. materials[0] === the
-        // representative entity-level snapshot already built; materials[i>=1]
-        // are resolved via `resolveMaterialSnapshot` (a non-sprite, single-
-        // pass-equivalent resolver — sprite per-submesh is OOS-1). When the
-        // entity has no materialsView (case-B sentinel) the array is a single
-        // mid-grey default mirroring the legacy single-material path so the
-        // record stage's per-submesh UBO upload loop trivially writes one
-        // slot, no special branch.
-        const materialsArr: MaterialSnapshot[] = [materialSnap];
-        if (assets !== undefined && assets !== null) {
-          for (let mi = 1; mi < materialHandles.length; mi++) {
-            const subHandle = materialHandles[mi] ?? 0;
-            const cachedSubmaterial = materialSnapshotCache.get(subHandle);
-            materialsArr.push(
-              cachedSubmaterial?.snapshot ??
-                resolveMaterialSnapshot(
-                  subHandle,
-                  world,
-                  assets,
-                  materialSnapshotCache,
-                  persistentMaterialSnapshotCache,
-                ),
-            );
-          }
-        }
-        if (isRenderable && assets !== undefined && assets !== null) {
-          for (let mi = 1; mi < materialHandles.length; mi++) {
-            const subHandle = materialHandles[mi] ?? 0;
-            if (subHandle === handleRaw) continue;
-            const subEntry =
-              materialSnapshotCache.get(subHandle) ??
-              readPersistentMaterialSnapshot(persistentMaterialSnapshotCache, subHandle, assets);
-            appendMaterialDispatchEntries(
-              pendingDispatch,
-              subEntry?.passes ?? (subHandle === 0 ? [DEFAULT_FORWARD_PASS] : []),
-              entity,
-              subHandle,
-              renderables.length,
-              layerVal,
-              materialsArr[mi]?.paramSnapshot,
-            );
-          }
-        }
-
-        // feat-20260625-sprite-instances-and-tilemap-terrain-static-batch M3 /
-        // w10: SpriteInstances validation + snapshot materialisation.
-        // Three structured EcsError fires at this single point (plan-strategy
-        // D-6 "fail-fast at the render domain entry, not at ECS spawn-time"):
-        let spriteInstancesSnap: SpriteInstancesSnapshot | undefined;
-        if (hasSpriteInstances) {
-          // (1) mutually exclusive with Instances (peers — pick one).
-          if (hasInstances) {
-            worldInternal._routeError(
-              new SpriteInstancesMutuallyExclusiveWithInstancesError(entity),
-              {
-                severity: Severity.Error,
-                systemName: 'RenderSystem.extract (sprite-instances-mutually-exclusive)',
-              },
-            );
-            continue;
-          }
-          // (2) requires sprite shader — the per-instance UV region is
-          // consumed by the sprite vertex shader path only (plan-strategy D-4
-          // axis on sprite.wgsl). Post-collapse (PR #520): sprite is no longer
-          // a `shadingModel` enum member; identification is via the first-pass
-          // `materialShaderId === 'forgeax::sprite'` (OOS-1 path retained).
-          //
-          // feat-20260624 M1' / t6: `'forgeax::sprite-lit'` also walks the same
-          // per-instance UV region vertex path (VsOut byte-identical, paramSchema
-          // mirror); accept either shader id.
-          if (
-            materialSnap.materialShaderId !== 'forgeax::sprite' &&
-            materialSnap.materialShaderId !== 'forgeax::sprite-lit'
-          ) {
-            worldInternal._routeError(
-              new SpriteInstancesRequiresSpriteShaderError(
-                entity,
-                materialSnap.materialShaderId ?? 'undefined',
-              ),
-              {
-                severity: Severity.Error,
-                systemName: 'RenderSystem.extract (sprite-instances-requires-sprite-shader)',
-              },
-            );
-            continue;
-          }
-          // (3) count mismatch — transforms.length / 16 === regions.length / 4
-          // (transforms.length=0 + regions.length=0 is the zero-instance lawful
-          // boundary; both derivations are 0 and equality holds, so no fire).
-          const transforms = worldInternal._getArrayView(entity, SpriteInstances, 'transforms');
-          const regions = worldInternal._getArrayView(entity, SpriteInstances, 'regions');
-          if (transforms !== undefined && regions !== undefined) {
-            const transformsLength = transforms.length;
-            const regionsLength = regions.length;
-            // Stride sanity: transforms must be mod 16, regions must be mod 4.
-            // A stride violation expresses as a count mismatch under the
-            // canonical derivation transforms/16 vs regions/4 — fire the
-            // count-mismatch code (the same code carries detail.expectedStride).
-            const tCount = transformsLength / 16;
-            const rCount = regionsLength / 4;
-            if (transformsLength % 16 !== 0 || regionsLength % 4 !== 0 || tCount !== rCount) {
-              worldInternal._routeError(
-                new SpriteInstancesCountMismatchError(transformsLength, regionsLength),
-                {
-                  severity: Severity.Error,
-                  systemName: 'RenderSystem.extract (sprite-instances-count-mismatch)',
-                },
-              );
-              continue;
-            }
-            // Validation passes — build the snapshot. transforms.length === 0
-            // is lawful (zero-instance) and produces instanceCount=0; the
-            // record stage skips drawIndexed when instanceCount===0.
-            const transformsCopy = new Float32Array(transforms);
-            const regionsCopy = new Float32Array(regions);
-            spriteInstancesSnap = {
-              transforms: transformsCopy,
-              regions: regionsCopy,
-              instanceCount: tCount,
-              cacheKey: entity,
-              archVersion,
-            };
-          }
-        }
-
-        let localAabb: Float32Array | undefined;
-        let lods: readonly MeshLodLevel[] | undefined;
-        let lodHysteresis: number | undefined;
-        let morph: MorphSnapshot | undefined;
-        const assetHandleRaw = Math.round(fAssetHandle ?? 0);
-        if (assetHandleRaw !== 0) {
-          const meshRes = resolveAssetHandle(world, toShared<'MeshAsset'>(assetHandleRaw));
-          if (meshRes.ok && meshRes.value.kind === 'mesh') {
-            const meshAsset = meshRes.value as MeshAsset;
-            lods = meshAsset.lods;
-            lodHysteresis = meshAsset.lodHysteresis;
-            morph = morphSnapshotFor(meshAsset, morphWeightsView);
-            const meshAabb = 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
-            // to culling a valid deformed vertex.
-            if (morph === undefined && hasFiniteOrderedLocalAabb(meshAabb)) {
-              localAabb = new Float32Array(meshAabb);
-            }
-          }
-        }
-
-        const pointsLinesStyle: PointsLinesStyle | undefined =
-          points !== undefined
-            ? (() => {
-                const shape = pointShapeFromU32(points.shape);
-                return shape === undefined
-                  ? undefined
-                  : { kind: 'points' as const, sizePx: points.sizePx, shape };
-              })()
-            : lines === undefined
-              ? undefined
-              : { kind: 'lines' as const, widthPx: lines.widthPx };
-        const cullingLocalAabb = expandPointsLinesBounds(localAabb ?? [], pointsLinesStyle);
-        const pointsLines =
-          pointsLinesComponent === undefined
-            ? undefined
-            : ({
-                worldId: 0,
-                entityKey: entity,
-                component: pointsLinesComponent,
-                meshHandle: assetHandleRaw,
-                meshGeneration: assets?.catalogEpoch ?? 0,
-                materialHandle: handleRaw,
-                materialGeneration: assets?.catalogEpoch ?? 0,
-                style: pointsLinesStyle,
-                layer: layerVal,
-                sortKey,
-                visible: true,
-                sourceBounds: cullingLocalAabb,
-                viewport: { width: 0, height: 0, dpr: 1 },
-                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,
-            };
-          }
-        }
-
-        const baseRenderable: RenderableSnapshot = {
-          assetHandle: Math.round(fAssetHandle ?? 0),
-          transform: transformSnap,
-          ...(lods === undefined ? {} : { lods }),
-          ...(lodHysteresis === undefined ? {} : { lodHysteresis }),
-          ...(localAabb !== undefined ? { localAabb: cullingLocalAabb } : {}),
-          material: materialSnap,
-          materials: materialsArr,
-          materialBindingSources,
-          materialBindingDiagnostics,
-          worldId: 0,
-          entityKey: entity,
-          ...(skinSlice !== undefined ? { skin: skinSlice } : {}),
-          ...(morph !== undefined ? { morph } : {}),
-          ...(instancesSnap !== undefined ? { instances: instancesSnap } : {}),
-          ...(spriteInstancesSnap !== undefined ? { spriteInstances: spriteInstancesSnap } : {}),
-          ...(pointsLines !== undefined ? { pointsLines } : {}),
-        };
-        const gpuDrivenDraws = buildGpuDrivenDraws({
-          submeshes: gpuDrivenSubmeshes,
-          indexed: gpuDrivenIndexed,
-          materials: materialsArr,
-          fallbackMaterial: materialSnap,
-          ...(gpuDrivenGeometry === undefined || getMaterialShaderArtifact === 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;
-                },
-              }),
-        });
-        const renderable =
-          morph === undefined && gpuDrivenDraws.length > 0
-            ? { ...baseRenderable, gpuDrivenDraws }
-            : baseRenderable;
-
-        // feat-20260528-frustum-culling M3 / w10: frustum culling check.
-        // Skip the entity if a valid AABB exists AND ALL cameras' frusta
-        // reject the world-space AABB. Missing or malformed AABBs are
-        // conservative always-visible fallbacks; valid culling bounds are
-        // producer-owned finite local-space AABBs. Culling is unconditional
-        // engine behavior; there is no per-entity opt-out.
-        if (localAabb !== undefined) {
-          // 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 {
-            // 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;
-            }
-          }
-        }
-
-        flushPendingDispatch(pendingDispatch);
-        renderables.push(renderable);
-      }
-
-      // feat-20260520-2d-sprite-layer-mvp M-3 / w22 + w25: finalise the
-      // pending TransparentEntry with the renderableIndex pointing at the
-      // RenderableSnapshot we just pushed (when isRenderable === true).
-      // The check below also covers a sprite entity that survives the
-      // dangling-Instances branch (silent skip with `dispatchEntry !==
-      // null` early-continue) — in that case renderableIndex is still set
-      // to the just-pushed slot which is correct because materialDispatch
-      // already captures the dispatch position.
-    }
-  }
-
-  // M3 / w26: sort dispatch entries by queue (ascending, stable sort)
-  // per plan-strategy D-3.
-  dispatch = sortDispatchByQueue(dispatch);
-
-  // D-1: collect PostProcessParams entities into Map<shaderId, Uint8Array>.
-  // Last-one-wins when multiple entities bear the same shader id (mirrors
-  // Camera.exposure -> CameraSnapshot pattern; extract stage only reads).
-  const postProcessParams: Map<string, Uint8Array> = new Map();
-  const postProcessParamsQuery = world.query({ with: [PostProcessParams] }).unwrap();
-  for (const row of postProcessParamsQuery) {
-    const entity = row.entity;
-    const read = world.get(entity, PostProcessParams);
-    if (!read.ok) continue;
-    postProcessParams.set(read.value.shader, read.value.data);
-  }
-
-  // feat-20260621 M-A3 / w13 (D-5): engine built-in tonemap data-driven
-  // provider. The engine bridges the active camera's `Camera.exposure /
-  // 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 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.
-  const tonemapCamera = cameras[0];
-  if (tonemapCamera !== undefined) {
-    postProcessParams.set(STANDARD_OUTPUT_TRANSFORM_FEATURE_ID, tonemapParams(tonemapCamera));
-  }
-
-  return {
-    cameras,
-    auxiliaryCameras,
-    cubeCameras,
-    reflectionProbes,
-    lights,
-    environment,
-    environmentReady: true,
-    ...(volumetricFog === undefined ? {} : { volumetricFog }),
-    renderables,
-    dispatch,
-    skylight,
-    skylightCount,
-    lightProbes,
-    skybox,
-    skyboxCount,
-    fog,
-    ...(fogFailure === undefined ? {} : { fogFailure }),
-    frustumStats: { culled: frustumCulled, total: frustumTotal },
-    visibilityStats: { explicitlyHidden: explicitlyHidden.size },
-    postProcessParams,
-    visibilitySnapshots: [context.visibility],
-    featureVisibilitySnapshots: [{ world, snapshot: context.visibility }],
-    hiddenEntityReports: [...explicitlyHidden].map((entity) => ({ world, entity })),
-  };
-}
-
-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,
-  };
-}
-
-function identityProjection(): Float32Array {
-  const projection = new Float32Array(16);
-  projection[0] = 1;
-  projection[5] = 1;
-  projection[10] = 1;
-  projection[15] = 1;
-  return projection;
-}
+export { defaultMaterialSnapshot, extractFrame, extractFrames } from './render-system-extract-tail';