@forgeax/engine-render 0.1.2

package/src/record/frame.ts

@@ -0,0 +1,1874 @@
+// @forgeax/engine-runtime - RenderSystem record stage: frame.
+// Extracted from render-system-record.ts (feat-20260704 M3/w17, pure move).
+
+import type { World } from '@forgeax/engine-ecs';
+import { createWorldProjection } from '@forgeax/engine-ecs/projection';
+import { type RhiCommandEncoder, RhiError, type TextureView } from '@forgeax/engine-rhi';
+import type { MaterialRenderState, MeshAsset } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { resolveRenderAsset } from '../assets/resolve-render-asset';
+import type { EngineMetrics } from '../engine-metrics';
+import type { ExtractedEnvironment } from '../environment/extracted-environment';
+import {
+  beginEnvironmentGeneration,
+  environmentConsumerSnapshot,
+  publishEnvironmentGeneration,
+} from '../environment/generation';
+import { createEnvironmentGpuBundle } from '../environment/gpu-bundle';
+import type { EnvironmentTransactionAttempt } from '../environment/graph';
+import {
+  completeEnvironmentQueue,
+  destroyCompletedEnvironmentGenerations,
+  resizeEnvironmentGeneration,
+} from '../environment/lifecycle';
+import {
+  deriveEnvironmentBundleDescriptors,
+  environmentBundleBytes,
+  environmentSignature,
+} from '../environment/signature';
+import { buildSubmissionCandidateMembership } from '../gpu-driven/batch-topology';
+import type { GpuDrivenProduction, PreparedGpuDrivenFrame } from '../gpu-driven/production-raster';
+import type { CpuMultiViewVisibilityResult } from '../gpu-driven/view-gpu';
+import { disposeTransientInstanceBuffers } from '../instance-buffer-cache';
+import type { PersistentGpuDrivenState } from '../persistent-render-scene';
+import type { _InternalRenderPipelineContext } from '../render-pipeline-context';
+import type { RenderSceneProjection, RenderSceneSubmissionDelta } from '../render-scene-projection';
+import type { MeshGpuHandles, RenderSystemInternals } from '../render-system';
+import type {
+  CameraSnapshot,
+  DispatchEntry,
+  ExtractedLights,
+  FogSnapshot,
+  MaterialSnapshot,
+  RenderableSnapshot,
+} from '../render-system-extract';
+// feat-20260622-chunk-gpu-instancing-sprite-tilemap M1 / w4 (D-1 record-stage
+// fold operator). Pure linear-scan helper that groups transparent-dispatch
+// entries with equal (Layer.value, sortKey, materialHandle) into FoldBucket
+// descriptors. The drawIndexed swap (1 instanced draw per bucket vs N
+// per-entity draws) hooks into the sprite-pass dispatch loop below
+// (w4-record-swap), using {@link buildFoldDispatchPlan} to translate
+// renderableIndex-keyed buckets into validatedOrdered-index-keyed
+// head/skip maps.
+import {
+  buildFoldDispatchPlan,
+  evaluateFoldBucketUniformCap,
+  type FoldBucket,
+  type FoldDispatchPlan,
+  foldDispatchBuckets,
+  incrementFoldedDrawsMetric,
+} from '../render-system-fold';
+import type { RenderRecordPhase } from '../renderer';
+import {
+  getTransparentSortConfig,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+} from '../systems/transparent-sort-config';
+import type { TemporalCoverageSummary } from '../temporal-coverage';
+import type { TemporalFrameAttempt, TemporalFrameTransaction } from '../temporal-frame-transaction';
+import {
+  buildPerFrameBindGroups,
+  createEnvironmentConsumerSnapshot,
+  prepareFrameLighting,
+  resolveSkyboxActive,
+  warnZeroLightStandard,
+  writeHdrpClusterAndSsaoBuffers,
+  writePointSpotLightBuffers,
+  writeShadowParamsBuffer,
+} from './frame-lighting';
+import {
+  type BindGroupCounts,
+  clampPcfKernelSize,
+  type DirectionalShadowCache,
+  type DirectionalShadowWorldState,
+  type DispatchCounts,
+  makeZeroCameraFallbackSnapshot,
+  type RasterItemKey,
+  type RenderFrameState,
+  type ValidatedRenderable,
+  worldEntityKey,
+} from './frame-snapshot';
+import {
+  acquireSwapChainTarget,
+  graphExecutionPhase,
+  resolveShadowMapSize,
+  resolveSpotShadowMapSize,
+} from './frame-targets';
+import {
+  computeViewMatrix,
+  driveLazyEquirectProjection,
+  selectLazyEquirectHandle,
+  variantSetFromDefines,
+  warnMultiSkybox,
+  warnMultiSkylight,
+} from './helpers';
+import { computeSplitLdrSprite } from './main-pass-sprite';
+import {
+  buildMaterialSlotPlan,
+  findRenderablePrefixForSlotCapacity,
+  materialSlotCountForPrefix,
+} from './material-slot-plan';
+import { cleanPerEntityCache, ensureMeshSsboCapacity, uploadMeshSsboBatch } from './mesh-ssbo';
+import { writeShadowCasterUniforms } from './shadow-caster-uniform';
+import { ensureCompiledFrameGraph, executeCompiledFrameGraph } from './typed-frame-graph';
+import { writeViewUbo } from './view-ubo';
+
+export type RecordProfileRunner = <T>(phase: RenderRecordPhase, action: () => T) => T;
+
+const EMPTY_RASTER_ITEM_KEYS: ReadonlySet<RasterItemKey> = new Set<RasterItemKey>();
+
+type ShadowSceneSlot = PersistentGpuDrivenState['slots'][number];
+
+// PersistentRenderScene publishes the production O(1) stable-id join. The
+// compatibility path below deliberately rebuilds its small index per token
+// calculation: custom/test doubles may mutate a slots array in place, so an
+// identity cache would be able to return a stale slot and create a false hit.
+function shadowSlotIndex(slots: readonly ShadowSceneSlot[]): ReadonlyMap<number, ShadowSceneSlot> {
+  const index = new Map<number, ShadowSceneSlot>();
+  for (const slot of slots) index.set(slot.slot, slot);
+  return index;
+}
+
+function sortedUniqueStableIds(values: readonly number[]): number[] {
+  const sorted = [...values].sort((left, right) => left - right);
+  let write = 0;
+  for (const value of sorted) {
+    if (write > 0 && sorted[write - 1] === value) continue;
+    sorted[write] = value;
+    write += 1;
+  }
+  sorted.length = write;
+  return sorted;
+}
+
+function visibilityCandidateIndices(
+  visibility: CpuMultiViewVisibilityResult | undefined,
+  kind: 'main' | 'cascade',
+  cascadeIndex?: number,
+): ReadonlySet<number> | undefined {
+  const view = visibility?.views.find(
+    (candidate) =>
+      candidate.kind === kind && (kind === 'main' || candidate.cascadeIndex === cascadeIndex),
+  );
+  if (view === undefined) return undefined;
+  return new Set(
+    view.compactVisible.flatMap((candidate) =>
+      candidate.candidateIndex === undefined ? [] : [candidate.candidateIndex],
+    ),
+  );
+}
+
+function runRecordProfilePhase<T>(
+  runner: RecordProfileRunner | undefined,
+  phase: RenderRecordPhase,
+  action: () => T,
+): T {
+  return runner === undefined ? action() : runner(phase, action);
+}
+
+const ANALYTIC_SKY_QUALITY = Object.freeze({ skySize: 128, irradianceSize: 32, prefilterMips: 5 });
+const ANALYTIC_SKY_ALGORITHM = 'preetham-perez-1999-r1';
+
+function beginProductionEnvironmentGeneration(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  environment: ExtractedEnvironment,
+): EnvironmentTransactionAttempt | undefined {
+  if (environment.kind !== 'atmosphere') {
+    const state = frameState.environmentGeneration;
+    const oldHandles = [state.active?.handle, state.candidate?.handle].filter(
+      (handle): handle is NonNullable<typeof handle> => handle !== undefined,
+    );
+    if (oldHandles.length > 0) {
+      resizeEnvironmentGeneration(state);
+      void internals.device.queue.onSubmittedWorkDone().then(() => {
+        for (const handle of oldHandles) {
+          if (typeof handle === 'object' && handle !== null && 'destroy' in handle) {
+            (handle as { readonly destroy: (device: typeof internals.device) => unknown }).destroy(
+              internals.device,
+            );
+          }
+        }
+      });
+    }
+    return undefined;
+  }
+  const quality = ANALYTIC_SKY_QUALITY;
+  const signature = environmentSignature({
+    atmosphere: {
+      turbidity: environment.atmosphere.turbidity,
+      rayleigh: environment.atmosphere.rayleigh,
+      mieCoefficient: environment.atmosphere.mieCoefficient,
+      mieDirectionalG: environment.atmosphere.mieDirectionalG,
+      sunAngularRadius: environment.atmosphere.sunAngularRadius,
+    },
+    sun: {
+      direction: environment.atmosphere.sun.direction,
+      color: environment.atmosphere.sun.color,
+      illuminance: environment.atmosphere.sun.illuminance,
+    },
+    quality,
+    algorithmRevision: ANALYTIC_SKY_ALGORITHM,
+    worldId: environment.worldId,
+    entity: environment.atmosphere.entity,
+    deviceGeneration:
+      typeof frameState.environmentGeneration.deviceGeneration === 'number'
+        ? frameState.environmentGeneration.deviceGeneration
+        : 0,
+    outputFormat: 'rgba16float',
+  });
+  const state = frameState.environmentGeneration;
+  if (state.active?.signature === signature) {
+    return undefined;
+  }
+  if (state.candidate !== undefined) return undefined;
+  const descriptors = deriveEnvironmentBundleDescriptors(quality, 'rgba16float');
+  const attempt = beginEnvironmentGeneration(state, {
+    signature,
+    bytes: environmentBundleBytes(descriptors),
+  });
+  const bundle = createEnvironmentGpuBundle(internals.device, descriptors);
+  if (!bundle.ok) {
+    attempt.fail('readiness');
+    internals.errorRegistry.fire(bundle.error);
+    return undefined;
+  }
+  const candidateSnapshot = createEnvironmentConsumerSnapshot({
+    generation: attempt.generation,
+    signature: String(attempt.desired.signature),
+    direction: [
+      environment.atmosphere.sun.direction[0] ?? 0,
+      environment.atmosphere.sun.direction[1] ?? 0,
+      environment.atmosphere.sun.direction[2] ?? 0,
+    ],
+    color: [
+      environment.atmosphere.sun.color[0] ?? 0,
+      environment.atmosphere.sun.color[1] ?? 0,
+      environment.atmosphere.sun.color[2] ?? 0,
+    ],
+    illuminance: environment.atmosphere.sun.illuminance,
+    atmosphere: {
+      turbidity: environment.atmosphere.turbidity,
+      rayleigh: environment.atmosphere.rayleigh,
+      mieCoefficient: environment.atmosphere.mieCoefficient,
+      mieDirectionalG: environment.atmosphere.mieDirectionalG,
+      sunAngularRadius: environment.atmosphere.sunAngularRadius,
+    },
+    source: { worldId: environment.worldId, entity: environment.atmosphere.entity },
+  });
+  const candidate = attempt.complete(bundle.value, candidateSnapshot);
+  const queueCompletion = `analytic-sky:${candidate.generation}:${frameState.frameNumber}`;
+  let settled = false;
+  const abandonCandidate = (stage: 'execute' | 'finish' | 'submit'): void => {
+    if (settled) return;
+    settled = true;
+    attempt.fail(stage);
+    bundle.value.destroy(internals.device);
+  };
+  return {
+    abort: abandonCandidate,
+    publish: () => {
+      if (settled) return;
+      settled = true;
+      publishEnvironmentGeneration(state, candidate, queueCompletion);
+      void internals.device.queue.onSubmittedWorkDone().then(() => {
+        completeEnvironmentQueue(state, queueCompletion);
+        destroyCompletedEnvironmentGenerations(state, internals.device, queueCompletion);
+      });
+    },
+  };
+}
+
+export function recordFrame(
+  internals: RenderSystemInternals,
+  world: World,
+  cameras: CameraSnapshot[],
+  lights: ExtractedLights,
+  renderables: RenderableSnapshot[],
+  transparentDispatch: readonly DispatchEntry[],
+  frameState: RenderFrameState,
+  dispatchCounts: DispatchCounts,
+  bindGroupCounts: BindGroupCounts,
+  environment: ExtractedEnvironment,
+  postProcessParams: ReadonlyMap<string, Uint8Array>,
+  // feat-20260709-editor-world-partition ENGINE-fix-round2 (defect 2): the
+  // The ordered worlds[] remains the shadow-composition input. Renderer-owned
+  // snapshots use stable WorldRenderId values, so production passes the
+  // worldForRenderId lookup below instead of treating those ids as indexes.
+  // Direct unit callers without that lookup retain the historical array-index
+  // behavior.
+  worlds: readonly World[] = [world],
+  profilePhase?: RecordProfileRunner,
+  gpuDriven?: {
+    readonly owner: GpuDrivenProduction;
+    readonly scene: PersistentGpuDrivenState | undefined;
+    readonly onCoverage: (ownsAll: boolean) => void;
+  },
+  worldForRenderId?: (worldId: number) => World | undefined,
+  temporal?: {
+    readonly transaction: TemporalFrameTransaction;
+    readonly projection: RenderSceneProjection;
+    readonly coverage: TemporalCoverageSummary;
+    readonly reactiveRevision?: number | undefined;
+    readonly onSceneSubmitted?: ((delta: RenderSceneSubmissionDelta) => void) | undefined;
+  },
+  fog?: FogSnapshot | undefined,
+): boolean {
+  const skylight =
+    environment.kind === 'none' || environment.kind === 'image' ? environment.skylight : undefined;
+  const skylightCount = environment.skylightCount;
+  const skybox = environment.kind === 'image' ? environment.skybox : undefined;
+  const skyboxCount = environment.skyboxCount;
+  // The `try / finally` wrapper advances `frameState.frameNumber` exactly
+  // once per `recordFrame` invocation regardless of which early-return
+  // branch is taken (camera missing, cap exceeded, pipeline pending,
+  // swap-chain unavailable, etc).
+  // The boolean result reports whether the shared frame encoder reached queue
+  // submission; prepared graphics uses it to distinguish in-flight from
+  // unsubmitted buffer leases.
+  // Case B: 0 Camera => fire onError diagnostic. After
+  // feat-20260608-create-app-param-surface-trim / M1 / D-8, the frame
+  // is NOT skipped: a synthetic CameraSnapshot is injected so the
+  // downstream clear-pass-only path (Case E softening, D-Q7) still
+  // paints the swap-chain with the `ZERO_CAMERA_CLEAR_FALLBACK` color
+  // (`[0, 0, 0, 1]` opaque black; AC-05). The synthetic camera carries
+  // identity-shaped projection / view inputs (fov=PI/4, aspect=1,
+  // near=0.1, far=100) so the existing matrix math stays numerically
+  // stable; no MeshRenderer entity will pass validation in this state
+  // (no Camera = no scene), so geometry submission is a no-op and only
+  // the swap-chain clear lands.
+  let activeCameras = cameras;
+  let temporalAttempt: TemporalFrameAttempt | undefined;
+  let environmentAttempt: EnvironmentTransactionAttempt | undefined;
+  let frameSubmitted = false;
+  if (activeCameras.length === 0) {
+    internals.errorRegistry.fire(
+      new RhiError({
+        code: 'render-system-no-camera',
+        expected: 'world has at least one entity with Transform + Camera',
+        hint: 'world.spawn({ component: Transform, data: { pos: [x, y, z], quat: [x, y, z, w], scale: [x, y, z] } }, { component: Camera, data: { fov, aspect, near, far, clearColor: [r, g, b, a] } }) before renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 })',
+      }),
+    );
+    activeCameras = [makeZeroCameraFallbackSnapshot()];
+  }
+  try {
+    // Case D: N>1 Camera => fire onError, use first hit (D-S7).
+    if (activeCameras.length > 1) {
+      internals.errorRegistry.fire(
+        new RhiError({
+          code: 'render-system-multi-camera',
+          expected: 'world has exactly one entity with Transform + Camera',
+          hint: 'remove duplicate Camera entities or wait for feat-future-multi-viewport',
+        }),
+      );
+    }
+    const camera = activeCameras[0];
+    if (!camera) return false;
+    const pipelineState = internals.getPipelineState();
+    if (pipelineState === null) return false;
+    frameState.currentFrameObservationSource = undefined;
+    frameState.currentDirectionalShadowView = null;
+    frameState.currentSpotShadowView = null;
+    environmentAttempt = beginProductionEnvironmentGeneration(internals, frameState, environment);
+    // `beginProductionEnvironmentGeneration` owns the producer snapshot and
+    // updates the active snapshot only after a successful submit. This keeps
+    // direct light/CSM consumers on the previous LKG while a replacement is
+    // still a candidate.
+
+    // Record-stage fold operator linear scan (groups transparent-sort entries
+    // into fold buckets + records the fold-eligible count metric). Extracted to
+    // computeFoldBuckets (M3/w18).
+    const { foldBuckets, light } = runRecordProfilePhase(profilePhase, 'record/scene-state', () => {
+      const foldBuckets = runRecordProfilePhase(
+        profilePhase,
+        'record/scene-state/fold-buckets',
+        () => computeFoldBuckets(world, frameState, transparentDispatch, renderables),
+      );
+
+      // Multi-light warnings + point/spot shadow-snapshot pin + point-shadow atlas
+      // ensure + ExtractedLights three-arm destructure (directional fallback,
+      // point/spot arrays, totalLightCount). Extracted to prepareFrameLighting
+      // (M3/w18) so recordFrame stays a skeleton.
+      const { light, pointLights, spotLights, totalLightCount } = runRecordProfilePhase(
+        profilePhase,
+        'record/scene-state/lighting-prep',
+        () => prepareFrameLighting(internals, frameState, lights),
+      );
+
+      runRecordProfilePhase(profilePhase, 'record/scene-state/ambient-resolution', () => {
+        // feat-20260520-skylight-ibl-cubemap M4 / t27 (AC-10 + F-4 nit):
+        // 0-light three-condition conjunction (plan-strategy D-5):
+        //   no Skylight (skylight === undefined)
+        //   AND 0 direct light (totalLightCount === 0)
+        //   AND StandardMaterial (renderables.some materialShaderId !== 'forgeax::default-unlit')
+        // All three true -> black + warn. Any one false -> no warn.
+        //
+        // Multi-Skylight warn (F-4 nit + feat-20260630 M3 / w19): >1 Skylight
+        // entity -> warn ONCE per RenderSystem lifetime (not per frame), naming the
+        // winning entity handle so the scene author can tell which Skylight is used
+        // (F-8: warn carries conflicting entity info). First Skylight (by archetype
+        // order) wins.
+        warnMultiSkylight(frameState, skylightCount, skylight?.entityHandle ?? 0);
+
+        // Multi-SkyboxBackground warn (feat-20260630 M3 / w19): mirror the Skylight
+        // once-warn + winning-entity-handle pattern. First SkyboxBackground (by
+        // archetype order) wins.
+        warnMultiSkybox(frameState, skyboxCount, skybox?.entityHandle ?? 0);
+
+        // feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w18:
+        // lazy equirect-to-cubemap projection trigger (the single per-frame driver;
+        // plan-strategy D-4 + sequence diagram). The Skylight (or, when present
+        // without one, the SkyboxBackground) supplies the equirect handle; both
+        // reuse the same handle so a single projection serves IBL ambient + skybox.
+        //   - handle 0          -> no equirect (solid-color ambient); skip
+        //   - caps.rgba16float
+        //     Renderable false  -> permanent white fallback; never project (AC-06,
+        //                          the only IBL gate; no UA guard)
+        //   - status undefined  -> first sight: resolve POD + fire-and-forget launch
+        //                          (does NOT await; the store writes status:'pending'
+        //                          synchronously so this launches exactly once)
+        //   - status pending    -> projection in flight; white fallback this frame
+        //                          (normal transition, not an error -- no fire)
+        //   - status ready      -> real IBL bound by the recordMainPass cache check
+        //   - status failed     -> fire EquirectProjectionFailedError ONCE per
+        //                          handle (R-2/AC-09: store records failed
+        //                          permanently and never retries; the latch keeps
+        //                          the channel from flooding)
+        const lazyEquirectHandle = selectLazyEquirectHandle(skylight, skybox);
+        if (lazyEquirectHandle !== 0) {
+          driveLazyEquirectProjection(internals, world, frameState, lazyEquirectHandle);
+        }
+      });
+
+      // feat-20260608-cluster-lighting M5 / w21 + M6 / w23: HDRP per-frame CPU
+      // cluster binning + light-data / cluster-grid / SSAO buffer uploads. Runs
+      // only when the HDRP pipeline is active and there is at least one punctual
+      // light. Extracted to a sub-function (M3/w18) so recordFrame stays a
+      // skeleton; fail-soft error semantics are preserved verbatim.
+      runRecordProfilePhase(profilePhase, 'record/scene-state/hdrp-cluster', () => {
+        writeHdrpClusterAndSsaoBuffers(
+          internals,
+          frameState,
+          camera,
+          pointLights,
+          spotLights,
+          profilePhase,
+          pipelineState.hdrpClusterMembershipPipeline !== null &&
+            internals.device.caps?.compute === true &&
+            internals.membershipTiming?.usesCpuControl() !== true,
+          pipelineState.hdrpClusterMembershipBindGroupLayout,
+        );
+      });
+
+      // Zero-light standard-material once-warn (no Skylight + 0 direct light +
+      // >=1 lit material -> black). Extracted to warnZeroLightStandard (M3/w18).
+      warnZeroLightStandard(frameState, renderables, skylight, totalLightCount);
+
+      return { foldBuckets, light };
+    });
+
+    void activeCameras; // referenced below
+
+    // Case E (this commit): 0 renderables = legitimate scene (LO §1.1
+    // hello-window minimum semantic). Mirrors the Case C softening for
+    // 0 DirectionalLight (line 134 above; D-Q7). recordFrame() falls
+    // through to encode + submit a clear-pass-only render pass so the
+    // canvas is painted with `clearColor` even when no entity carries
+    // MeshFilter + MeshRenderer. Geometry submission (mat4 uploads,
+    // bind-group construction, vertex/index binding, drawIndexed) is
+    // conditional on `validatedOrdered.length > 0` further down.
+
+    // Point-shadow params UBO write (per-layer near/far/invSpan). Extracted to
+    // writeShadowParamsBuffer (M3/w18).
+    writeShadowParamsBuffer(internals, frameState, pipelineState);
+
+    // feat-20260625-spot-light-shadow-mapping w25 (scope-amend webkit-fallback):
+    // the per-spot perspective `lightViewProj` matrices fold into the View UBO
+    // tail (`view.spotLightViewProj`, floats 132..195 / bytes 528..784) and are
+    // written as part of the per-frame viewPayload below — no standalone binding
+    // 9 uniform buffer (it overflowed the WebGL2 fallback fragment uniform-buffer
+    // budget). See the viewPayload construction (VIEW_PAYLOAD_FLOATS = 196).
+
+    const effectiveShadowMapSize = resolveShadowMapSize(internals, lights);
+    const effectiveSpotShadowMapSize = resolveSpotShadowMapSize(internals, lights);
+    const graphShadowMapSize = effectiveShadowMapSize ?? effectiveSpotShadowMapSize;
+
+    const validated = runRecordProfilePhase(profilePhase, 'record/validation', () =>
+      validateRenderables(
+        internals,
+        world,
+        worlds,
+        renderables,
+        transparentDispatch,
+        worldForRenderId,
+      ),
+    );
+    const residentMeshes = new Map<number, MeshGpuHandles>();
+    const meshWorlds = new Map<number, number>();
+    const ambiguousMeshHandles = new Set<number>();
+    for (const entry of validated) {
+      const handle = entry.source.assetHandle;
+      if (ambiguousMeshHandles.has(handle)) continue;
+      const priorWorld = meshWorlds.get(handle);
+      if (priorWorld !== undefined && priorWorld !== entry.source.worldId) {
+        residentMeshes.delete(handle);
+        ambiguousMeshHandles.add(handle);
+        continue;
+      }
+      meshWorlds.set(handle, entry.source.worldId);
+      residentMeshes.set(handle, entry.mesh);
+    }
+
+    let preparedGpuDriven: PreparedGpuDrivenFrame | undefined;
+    if (gpuDriven !== undefined) {
+      const prepared = gpuDriven.owner.prepare({
+        scene: gpuDriven.scene,
+        camera,
+        meshes: residentMeshes,
+        viewBindGroupLayout: pipelineState.viewBindGroupLayout,
+        materialBindGroupLayout: pipelineState.materialBindGroupLayout,
+        meshResidencyEpoch: internals.gpuStore.meshResidencyEpoch,
+        hdrp: frameState.isHdrpActive,
+      });
+      if (prepared.ok) preparedGpuDriven = prepared.value;
+      else if (prepared.error.code !== 'rhi-not-available')
+        internals.errorRegistry.fire(prepared.error);
+    }
+    const cpuVisibility = gpuDriven?.owner.inspect().cpuVisibility;
+    const multiViewSubmissions = gpuDriven?.owner.multiViewSubmissions() ?? [];
+
+    // The GPU lane owns only the primary opaque raster today. Shadow membership
+    // is owned by the batch-aligned multi-view submissions below; the existing
+    // shadow encoder consumes them through a one-way direct-RHI adapter.
+    const cpuShadowCastersActive =
+      (effectiveShadowMapSize ?? 0) > 0 ||
+      lights.pointShadow.length > 0 ||
+      lights.spot.some((spot) => spot.castShadow);
+    const gpuOwnsAllPrimaryRaster = preparedGpuDriven?.ownsAllForwardItems === true;
+    gpuDriven?.onCoverage(gpuOwnsAllPrimaryRaster && !cpuShadowCastersActive);
+
+    const activeEnvironmentSignature =
+      frameState.environmentGeneration.candidate?.signature ??
+      frameState.environmentGeneration.active?.signature;
+    const preflightGraph = runRecordProfilePhase(profilePhase, 'record/render-graph', () =>
+      ensureCompiledFrameGraph(
+        internals,
+        frameState,
+        pipelineState,
+        camera,
+        lights,
+        Math.max(1, internals.canvas.width),
+        Math.max(1, internals.canvas.height),
+        graphShadowMapSize,
+        preparedGpuDriven,
+        temporal?.transaction,
+      ),
+    );
+    if (preflightGraph === null) return false;
+    temporalAttempt = temporal?.transaction.begin({
+      camera,
+      surfaceWidth: Math.max(1, internals.canvas.width),
+      surfaceHeight: Math.max(1, internals.canvas.height),
+      projection: temporal.projection,
+      visible: renderables,
+      coverage: temporal.coverage,
+      ...(Object.hasOwn(temporal, 'reactiveRevision')
+        ? { reactiveRevision: temporal.reactiveRevision }
+        : {}),
+      environmentSignature:
+        typeof activeEnvironmentSignature === 'string' ? activeEnvironmentSignature : undefined,
+      ...(temporal.onSceneSubmitted === undefined
+        ? {}
+        : { onSceneSubmitted: temporal.onSceneSubmitted }),
+    });
+
+    // Acquire the swap-chain texture + colour view + target dimensions (with
+    // one reconfigure-and-retry on surface-outdated). Extracted to
+    // acquireSwapChainTarget (M3/w18); returns null on unrecoverable failure
+    // (context null / double getCurrentTexture fail / view creation fail), in
+    // which case recordFrame bails after the finally-block frame advance.
+    const swapTarget = runRecordProfilePhase(profilePhase, 'record/swapchain', () =>
+      acquireSwapChainTarget(internals, pipelineState),
+    );
+    if (swapTarget === null) return false;
+    const currentTexture = swapTarget.currentTexture;
+    const view = swapTarget.view;
+    const targetW = swapTarget.targetW;
+    const targetH = swapTarget.targetH;
+
+    const depthView: TextureView | null = null;
+    // feat-20260709 M3 / D-3: clear-color read from the active CameraSnapshot's
+    // single `clearColor` array field (first-archetype-hit per OOS-2). When the
+    // world had zero Camera entities, `camera` here is the synthetic fallback
+    // snapshot built above (Case B), which carries
+    // `ZERO_CAMERA_CLEAR_FALLBACK = [0, 0, 0, 1]`.
+    const clear: readonly [number, number, number, number] = [
+      camera.clearColor[0],
+      camera.clearColor[1],
+      camera.clearColor[2],
+      camera.clearColor[3],
+    ];
+
+    pipelineState.perPassResources.shadowMapSize = graphShadowMapSize ?? 0;
+    pipelineState.perPassResources.shadowCascadeCount = lights.cascadeCount ?? 0;
+    pipelineState.perPassResources.shadowDepthBias = lights.depthBias ?? 0.005;
+    pipelineState.perPassResources.shadowNormalBias = lights.normalBias ?? 0.05;
+    pipelineState.perPassResources.shadowPcfKernelSize = clampPcfKernelSize(lights.pcfKernelSize);
+    const environmentSunDirection = environmentConsumerSnapshot(frameState.environmentGeneration)
+      ?.csm.direction;
+    const environmentShadowDirection =
+      environmentSunDirection === undefined
+        ? undefined
+        : [
+            -(environmentSunDirection[0] ?? 0),
+            -(environmentSunDirection[1] ?? 0),
+            -(environmentSunDirection[2] ?? 0),
+          ];
+    pipelineState.perPassResources.shadowLightDirection =
+      environmentShadowDirection !== undefined
+        ? new Float32Array(environmentShadowDirection)
+        : lights.directional === undefined
+          ? null
+          : new Float32Array([
+              lights.directional.direction[0] ?? 0,
+              lights.directional.direction[1] ?? 0,
+              lights.directional.direction[2] ?? 0,
+            ]);
+    const firstDirectionalShadowMatrix = lights.lightViewProj?.[0];
+    pipelineState.perPassResources.shadowLightSpaceMatrix =
+      firstDirectionalShadowMatrix === undefined
+        ? null
+        : new Float32Array(firstDirectionalShadowMatrix);
+    if (lights.lightViewProj === undefined) {
+      pipelineState.perPassResources.shadowCsmLightViewProj = null;
+      pipelineState.perPassResources.shadowCsmSelection = null;
+    } else {
+      const csmMatrices = new Float32Array(64);
+      for (let cascade = 0; cascade < 4; cascade += 1) {
+        const matrix = lights.lightViewProj[cascade];
+        if (matrix !== undefined) csmMatrices.set(matrix, cascade * 16);
+      }
+      pipelineState.perPassResources.shadowCsmLightViewProj = csmMatrices;
+      pipelineState.perPassResources.shadowCsmSelection =
+        lights.splitPlanes === undefined
+          ? null
+          : {
+              viewMatrix: new Float32Array(computeViewMatrix(camera)),
+              splitPlanes: new Float32Array(lights.splitPlanes),
+              cascadeBlend: lights.cascadeBlend ?? 0,
+            };
+    }
+
+    // Tonemap + skybox-active resolution (skybox requires tonemap HDR target +
+    // a resident cubemap view). Extracted to resolveSkyboxActive (M3/w18).
+    const { tonemapActive, skyboxActive } = resolveSkyboxActive(
+      internals,
+      frameState,
+      camera,
+      skybox,
+    );
+    const atmosphereActive =
+      frameState.environmentGeneration.active !== undefined ||
+      frameState.environmentGeneration.candidate !== undefined;
+
+    // feat-20260604-learn-render-4.10-anti-aliasing-msaa M2 / w9 (D-6, C-9):
+    // MSAA is a per-Camera switch derived from `camera.antialias`, never
+    // stored separately. When active the geometry pass writes a count=4
+    // multisample colour target and resolves to a single-sample output; the
+    // record stage selects the `*Msaa` pipeline variants and the geometry
+    // pass attaches the resolve target. When inactive every attachment +
+    // pipeline stays single-sample (the pre-MSAA path is byte-for-byte
+    // unchanged).
+    // Geometry colour / depth / resolve / sprite-split target view resolution
+    // (MSAA + tonemap routing) + MSAA writeback to perPassResources. Extracted
+    // to resolveGeometryTargetViews (M3/w18) so recordFrame stays a skeleton.
+    const msaaActive =
+      camera.antialias === 'msaa' && internals.device.caps.backendKind !== 'wgpu-webgl2';
+    const geometryColorView = view;
+    const geometryDepthView = depthView;
+    const geometryDepthKey: string | null = null;
+    const geometryColorResolveView: TextureView | null = null;
+    const ldrSpriteColorView: TextureView | null = null;
+
+    // Validate renderable handles + collect render plan. Empty `renderables`
+    // input or all-unregistered handles both produce `validatedOrdered.length === 0`,
+    // which is the Case E (clear-pass-only) path.
+    //
+    // feat-20260520-2d-sprite-layer-mvp M-3 / w25 (@new-surface): per-entry
+    // `renderableIndex` tracks the position into the original renderables[]
+    // array so the bucket-aware reordering below can correlate
+    // transparent-sort output (TransparentEntry.renderableIndex) back to
+    // the validated row.
+    // bug-20260527-renderstate-pipeline-dispatch-gap D-4:
+    // build a renderableIndex -> renderState map from dispatch entries
+    // so each ValidatedRenderable carries its per-material renderState
+    // override without an O(n^2) back-scan in the draw loop.
+    const gpuOwnedItemKeys = preparedGpuDriven?.ownedItemKeys ?? EMPTY_RASTER_ITEM_KEYS;
+    gpuDriven?.owner.recordCpuValidation(validated, gpuOwnedItemKeys);
+
+    // Per-frame cache clean-up: drop per-entity BG cache entries + instance
+    // buffers whose entityKey is absent from the current validated set (despawn
+    // eviction). Extracted to cleanPerFrameCaches (M3/w18).
+    cleanPerFrameCaches(internals, frameState, validated);
+
+    // Dispatch-ordered render plan: reorder validated renderables to dispatch
+    // order, run the mesh-SSBO capacity gate (graceful truncation), and build
+    // the fold dispatch plan. Extracted to buildDispatchPlan (M3/w18).
+    const dispatchPlan = runRecordProfilePhase(profilePhase, 'record/dispatch-plan', () =>
+      buildDispatchPlan(internals, validated, transparentDispatch, foldBuckets),
+    );
+    const validatedOrdered = dispatchPlan.validatedOrdered;
+    // Build the candidate-index owner once at the frame boundary. Directional
+    // CPU fallback consumes the same multi-view membership contract as the
+    // indirect path and must not rediscover selected casters by scanning the
+    // complete dispatch for every cascade.
+    const validatedByCandidateIndex = new Map<number, ValidatedRenderable>();
+    const validatedIndexByCandidateIndex = new Map<number, number>();
+    for (let validatedIndex = 0; validatedIndex < validatedOrdered.length; validatedIndex += 1) {
+      const entry = validatedOrdered[validatedIndex];
+      if (entry === undefined) continue;
+      const candidateIndex = entry.source.candidateIndex ?? entry.renderableIndex;
+      if (!validatedByCandidateIndex.has(candidateIndex)) {
+        validatedByCandidateIndex.set(candidateIndex, entry);
+        validatedIndexByCandidateIndex.set(candidateIndex, validatedIndex);
+      }
+    }
+    // Build the compatibility shadow geometry owner once. Directional CSM
+    // uses its compact per-cascade submission; point/spot fallback passes
+    // need the main-view domain and the original validated slot for their
+    // dynamic mesh offset. Keeping both facts here removes a full
+    // validatedOrdered walk from every point face and spot tile while
+    // preserving the existing overflow-conservative behavior.
+    const mainSubmission = multiViewSubmissions.find((submission) => submission.kind === 'main');
+    const mainShadowCandidateIndices =
+      mainSubmission === undefined || mainSubmission.overflow
+        ? undefined
+        : mainSubmission.candidateIndices;
+    const validatedShadowEntries = Object.freeze(
+      validatedOrdered.flatMap((entry, validatedIndex) => {
+        const candidateIndex = entry.source.candidateIndex ?? entry.renderableIndex;
+        if (
+          mainShadowCandidateIndices !== undefined &&
+          !mainShadowCandidateIndices.has(candidateIndex)
+        ) {
+          return [];
+        }
+        return [{ entry, validatedIndex }];
+      }),
+    );
+    const foldDispatchPlan = dispatchPlan.foldDispatchPlan;
+    const materialSlotIndices = dispatchPlan.materialSlotIndices;
+    const materialSlots = dispatchPlan.materialSlots;
+    const materialSlotOwners = dispatchPlan.materialSlotOwners;
+    const materialSlotCount = dispatchPlan.materialSlotCount;
+
+    // D-2 (bug-20260527): LDR sprite pass split, generalised feat-20260625
+    // M2 / w7 via {@link computeSplitLdrSprite}; M3 w13 finalised by deleting
+    // the legacy shadingModel arm — transparent is the single SSOT. AC-05
+    // (non-sprite shader carrying transparent:true) trips the split too;
+    // the unit suite render-system-record.test.ts 'transparent decouples
+    // from sprite shader' locks the contract.
+    //
+    // When the LDR path (tonemapActive=false) has transparent entities in
+    // the validated draw list, the render is split into two serial passes
+    // sharing one color attachment. The transparent pass format is resolved
+    // by transparentPassColorFormat: native linear-LDR frames use the
+    // graph-owned `ldrColor` attachment (which may be rgba16float), while
+    // the swap-chain fallback uses its raw storage view. The encoder and
+    // sprite PSO must use the same resolved format because WebGPU requires
+    // attachment and pipeline target formats to match.
+    const splitLdrSprite = computeSplitLdrSprite(validatedOrdered, tonemapActive);
+    let ldrSpritePassView: TextureView | null = null;
+    if (splitLdrSprite) {
+      const unormViewRes = internals.device.createTextureView(currentTexture, {});
+      if (!unormViewRes.ok) {
+        internals.errorRegistry.fire(unormViewRes.error);
+        return false;
+      }
+      ldrSpritePassView = unormViewRes.value;
+    }
+
+    // View / mesh uniform uploads are only needed when geometry will be drawn,
+    // OR when a skybox is active (skybox pass reads inverseViewProj from
+    // the View UBO). Skip the writeBuffer round-trips on the Case E
+    // (clear-pass-only) path only when neither condition is met.
+    // feat-20260531-skybox-env-background M2 / w6: gate relaxed from
+    // `validatedOrdered.length > 0` to include skybox-only frames
+    // (plan-strategy D-3, R-3). Feature-only passes (for example VFX) also
+    // consume the View UBO through their group(0) contract even when the
+    // scene validation list is empty; keep that payload authoritative before
+    // the graph executes those passes.
+    const renderFeaturesActive = (internals.featureHost?.size ?? 0) > 0;
+    if (validatedOrdered.length > 0 || skyboxActive || atmosphereActive || renderFeaturesActive) {
+      runRecordProfilePhase(profilePhase, 'record/uploads', () => {
+        // View UBO + CSM/spot-shadow matrix pack: assembled + uploaded in one
+        // queue.writeBuffer round-trip. Extracted to view-ubo.ts (M3/w18) so
+        // recordFrame stays an orchestration skeleton (D-2).
+        writeViewUbo(
+          internals.device.queue,
+          pipelineState.viewUniformBuffer,
+          camera,
+          light,
+          lights,
+          frameState.spotShadowSnapshots,
+          temporalAttempt?.view,
+          fog,
+        );
+        writeShadowCasterUniforms(
+          internals.device.queue,
+          pipelineState.shadowCasterCascadeBuffer,
+          lights,
+        );
+
+        // Per-frame full rewrite of the PointLight + SpotLight std430 storage
+        // buffers (header + first-slice cap N=4 slots). Extracted to
+        // writePointSpotLightBuffers (M3/w18).
+        writePointSpotLightBuffers(internals, pipelineState, lights);
+
+        // Per-renderable entity_world upload (batched): all N mat4+normalMatrix
+        // slots assembled into a single contiguous scratch buffer, then flushed
+        // as one writeBuffer call. Extracted to mesh-ssbo.ts (M3/w21) so its
+        // module-scoped scratch buffer co-locates with the other mesh-SSBO lets.
+        uploadMeshSsboBatch(
+          internals.device.queue,
+          pipelineState.meshStorageBuffer,
+          validatedOrdered,
+          foldDispatchPlan,
+          temporalAttempt?.reactiveRevisionChanged ?? false,
+        );
+      });
+    }
+
+    const preparedDirectionalShadowCache = runRecordProfilePhase(
+      profilePhase,
+      'record/scene-state/directional-shadow-cache',
+      () =>
+        prepareDirectionalShadowCache(
+          internals,
+          frameState,
+          worlds,
+          lights,
+          effectiveShadowMapSize,
+          validatedOrdered,
+          cpuVisibility,
+          gpuDriven?.scene,
+        ),
+    );
+    const directionalShadowTileClearPipeline =
+      internals.getDirectionalShadowTileClearPipeline?.() ?? null;
+    const directionalShadowCache =
+      !preparedDirectionalShadowCache.reuse &&
+      preparedDirectionalShadowCache.hitMask !== 0 &&
+      directionalShadowTileClearPipeline === null
+        ? { ...preparedDirectionalShadowCache, hitMask: 0 }
+        : preparedDirectionalShadowCache;
+    frameState.directionalShadowCacheRecorded = false;
+
+    const encoderResult = internals.device.createCommandEncoder({ label: 'render-system-frame' });
+    if (!encoderResult.ok) {
+      internals.errorRegistry.fire(encoderResult.error);
+      return false;
+    }
+    const encoder: RhiCommandEncoder = encoderResult.value;
+
+    // Per-frame bind group cache resolution (view / mesh / HDRP-cluster).
+    // Extracted to buildPerFrameBindGroups (M3/w18) so recordFrame stays a
+    // skeleton; returns null groups on the Case E (0-validated) path.
+    const { viewBindGroup, meshBindGroup, hdrpClusterBindGroup, hdrpClusterMembershipBindGroup } =
+      runRecordProfilePhase(profilePhase, 'record/bind-groups', () =>
+        buildPerFrameBindGroups(
+          internals,
+          frameState,
+          pipelineState,
+          validated.length > 0 || preparedGpuDriven !== undefined,
+          bindGroupCounts,
+          undefined,
+          false,
+        ),
+      );
+
+    // ── feat-20260529-rendergraph-pass-abstraction M4 / w13b ───────────
+    // The compiled typed graph is the sole per-frame pass owner.
+    //
+    // Every pass records into the shared encoder. The graph owns ordering and
+    // the renderer finishes and submits exactly once after graph execution.
+    // feat-20260601 M2 / w12: the per-frame shared state is the clean
+    // `RenderPipelineContext` - `internals` is replaced by the named `assets`
+    // (CPU POD) / `store` (GPU residency) / `pipelineState` / `runtime` (device +
+    // errorRegistry + shader-cache lookups) surfaces (`internals` itself satisfies
+    // `RenderSystemRuntime` so `runtime: internals` is a zero-cost reference). The
+    // 0-consumed `skyboxCount` residual is dropped.
+    const csmPlan = lights.directionalCsm;
+    const mainMembership = visibilityCandidateIndices(cpuVisibility, 'main');
+    const mainDispatch =
+      mainMembership === undefined
+        ? transparentDispatch
+        : transparentDispatch.filter((entry) => {
+            const source = renderables[entry.renderableIndex];
+            const candidateIndex = source?.candidateIndex ?? entry.renderableIndex;
+            return mainMembership.has(candidateIndex);
+          });
+
+    const passCtx: _InternalRenderPipelineContext = {
+      assets: internals.assets,
+      world,
+      gpuDrivenItemKeys: gpuOwnedItemKeys,
+      gpuDrivenOwnsAllForwardItems: gpuOwnsAllPrimaryRaster,
+      validatedByCandidateIndex,
+      validatedIndexByCandidateIndex,
+      validatedShadowEntries,
+      store: internals.gpuStore,
+      pipelineState,
+      runtime: internals,
+      temporalFrame: temporalAttempt,
+      encoder,
+      view,
+      clear,
+      targetW,
+      targetH,
+      currentTexture,
+      camera,
+      tonemapActive,
+      geometryColorView,
+      geometryDepthView,
+      geometryDepthKey,
+      validated,
+      validatedOrdered,
+      viewBindGroup,
+      meshBindGroup,
+      frameState,
+      dispatchCounts,
+      bindGroupCounts,
+      skylight,
+      skylightCount,
+      skyboxActive,
+      skybox,
+      splitLdrSprite,
+      ldrSpritePassView,
+      msaaActive,
+      geometryColorResolveView,
+      ldrSpriteColorView,
+      postProcessParams,
+      dispatch: mainDispatch,
+      shadowDispatch: transparentDispatch,
+      directionalCsmPlan: csmPlan,
+      shadowDebugObservation: internals.shadowDebugObservation,
+      hdrpClusterBindGroup,
+      hdrpClusterMembershipBindGroup,
+      foldDispatchPlan,
+      materialSlotIndices,
+      materialSlots,
+      materialSlotOwners,
+      materialSlotCount,
+      materialBgAssemblyCache: frameState.materialBgAssemblyCache,
+      directionalShadowCacheReuse: directionalShadowCache.reuse,
+      directionalShadowCacheTokens: directionalShadowCache.cascadeTokens,
+      directionalShadowCacheHitMask: directionalShadowCache.hitMask,
+      multiViewSubmissions,
+      ...(profilePhase !== undefined ? { profilePhase } : {}),
+    };
+    frameSubmitted = runRecordProfilePhase(profilePhase, 'record/graph-execute', () =>
+      executeCompiledFrameGraph(
+        internals,
+        frameState,
+        passCtx,
+        encoder,
+        profilePhase === undefined
+          ? undefined
+          : (pass, encode) => profilePhase(graphExecutionPhase(pass.name), encode),
+        temporalAttempt,
+        environmentAttempt,
+      ),
+    );
+    if (frameSubmitted && !directionalShadowCache.reuse) {
+      frameState.directionalShadowCache = frameState.directionalShadowCacheRecorded
+        ? directionalShadowCache.next
+        : null;
+    }
+    return frameSubmitted;
+  } finally {
+    temporalAttempt?.abort();
+    if (!frameSubmitted) environmentAttempt?.abort('execute');
+    frameState.frameNumber += 1;
+    // feat-20260608-cluster-lighting M5 / w22: clear HDRP once-per-frame fired
+    // set so the next frame re-fires if the condition persists.
+    frameState.hdrpOncePerFrameFired.clear();
+  }
+}
+
+interface DirectionalShadowCacheDecision {
+  readonly reuse: boolean;
+  readonly next: DirectionalShadowCache | null;
+  readonly cascadeTokens: readonly string[];
+  readonly hitMask: number;
+}
+
+export type DirectionalShadowCacheMissReason =
+  | 'no-entry'
+  | 'shadow-map-size'
+  | 'cascade-count'
+  | 'pipeline'
+  | 'graph-topology'
+  | 'scene-mode'
+  | 'asset-catalog'
+  | 'mesh-residency'
+  | 'world-state'
+  | 'cascade-token';
+
+function observeDirectionalShadowTokenBuild(
+  metrics: EngineMetrics,
+  enabled: boolean,
+  built: { readonly tokens: readonly string[]; readonly productionSceneToken: boolean },
+): void {
+  if (!enabled || built.tokens.length === 0) return;
+  metrics.increment('shadow.csm.token-build');
+  metrics.increment(
+    built.productionSceneToken
+      ? 'shadow.csm.token-production-scene'
+      : 'shadow.csm.token-validated-fallback',
+  );
+  for (const _token of built.tokens) metrics.increment('shadow.csm.token-cascade');
+}
+
+function observeDirectionalShadowCacheDecision(
+  metrics: EngineMetrics,
+  enabled: boolean,
+  decision: Pick<DirectionalShadowCacheDecision, 'reuse' | 'cascadeTokens' | 'hitMask'>,
+  missReason: DirectionalShadowCacheMissReason | undefined,
+): void {
+  if (!enabled || decision.cascadeTokens.length === 0) return;
+  metrics.increment(decision.reuse ? 'shadow.csm.cache.reuse' : 'shadow.csm.cache.refresh');
+  if (decision.hitMask !== 0 && !decision.reuse) {
+    metrics.increment('shadow.csm.cache.partial-hit');
+  }
+  for (let index = 0; index < decision.cascadeTokens.length; index += 1) {
+    metrics.increment(
+      (decision.hitMask & (1 << index)) !== 0
+        ? 'shadow.csm.cache.cascade-hit'
+        : 'shadow.csm.cache.cascade-miss',
+    );
+  }
+  if (missReason !== undefined) metrics.increment(`shadow.csm.cache.miss.${missReason}`);
+}
+
+function classifyDirectionalShadowCacheMiss(input: {
+  readonly cached: DirectionalShadowCache | null;
+  readonly built: { readonly productionSceneToken: boolean };
+  readonly shadowMapSize: number | undefined;
+  readonly cascadeCount: number | undefined;
+  readonly pipelineHandle: number;
+  readonly graphTopologyKey: string | null;
+  readonly assetCatalogEpoch: number;
+  readonly meshResidencyEpoch: number;
+  readonly worldStateMatches: boolean;
+}): DirectionalShadowCacheMissReason {
+  const cached = input.cached;
+  if (cached === null) return 'no-entry';
+  if (cached.shadowMapSize !== input.shadowMapSize) return 'shadow-map-size';
+  if (cached.cascadeCount !== input.cascadeCount) return 'cascade-count';
+  if (cached.pipelineHandle !== input.pipelineHandle) return 'pipeline';
+  if (cached.graphTopologyKey !== input.graphTopologyKey) return 'graph-topology';
+  if (cached.productionSceneToken !== input.built.productionSceneToken) return 'scene-mode';
+  if (cached.assetCatalogEpoch !== input.assetCatalogEpoch) return 'asset-catalog';
+  if (cached.meshResidencyEpoch !== input.meshResidencyEpoch) return 'mesh-residency';
+  if (!input.built.productionSceneToken && !input.worldStateMatches) return 'world-state';
+  return 'cascade-token';
+}
+
+/**
+ * @internal Pure cache decision owner used by recordFrame and its semantic
+ * invalidation tests. Keeping the comparison separate makes the dangerous
+ * path explicit: a hit is only reusable when every cascade token matches and
+ * all frame/resource owners agree; a forced redraw is represented by
+ * `reuse:false` even when one cascade happens to match.
+ */
+export function evaluateDirectionalShadowCache(input: {
+  readonly cached: DirectionalShadowCache | null;
+  readonly cascadeTokens: readonly string[];
+  readonly productionSceneToken: boolean;
+  readonly shadowMapSize: number | undefined;
+  readonly cascadeCount: number | undefined;
+  readonly pipelineHandle: number;
+  readonly graphTopologyKey: string | null;
+  readonly assetCatalogEpoch: number;
+  readonly meshResidencyEpoch: number;
+  readonly worldStateMatches: boolean;
+}): {
+  readonly reuse: boolean;
+  readonly hitMask: number;
+  readonly missReason: DirectionalShadowCacheMissReason | undefined;
+} {
+  const cached = input.cached;
+  const commonHit =
+    cached !== null &&
+    cached.shadowMapSize === input.shadowMapSize &&
+    cached.cascadeCount === input.cascadeCount &&
+    cached.pipelineHandle === input.pipelineHandle &&
+    cached.graphTopologyKey === input.graphTopologyKey &&
+    cached.productionSceneToken === input.productionSceneToken &&
+    cached.assetCatalogEpoch === input.assetCatalogEpoch &&
+    cached.meshResidencyEpoch === input.meshResidencyEpoch &&
+    (input.productionSceneToken || input.worldStateMatches);
+  let hitMask = 0;
+  if (commonHit && cached !== null) {
+    for (let index = 0; index < input.cascadeTokens.length; index += 1) {
+      if (cached.cascadeTokens[index] === input.cascadeTokens[index]) hitMask |= 1 << index;
+    }
+  }
+  const reuse = input.cascadeTokens.length > 0 && hitMask === (1 << input.cascadeTokens.length) - 1;
+  return {
+    reuse,
+    hitMask,
+    missReason: reuse
+      ? undefined
+      : classifyDirectionalShadowCacheMiss({
+          cached,
+          built: { productionSceneToken: input.productionSceneToken },
+          shadowMapSize: input.shadowMapSize,
+          cascadeCount: input.cascadeCount,
+          pipelineHandle: input.pipelineHandle,
+          graphTopologyKey: input.graphTopologyKey,
+          assetCatalogEpoch: input.assetCatalogEpoch,
+          meshResidencyEpoch: input.meshResidencyEpoch,
+          worldStateMatches: input.worldStateMatches,
+        }),
+  };
+}
+
+const SHADOW_TOKEN_NUMBER = new DataView(new ArrayBuffer(8));
+
+function hashShadowTokenByte(hash: number, value: number): number {
+  return Math.imul((hash ^ value) >>> 0, 16_777_619) >>> 0;
+}
+
+function hashShadowTokenNumber(hash: number, value: number | undefined): number {
+  SHADOW_TOKEN_NUMBER.setFloat64(0, value ?? Number.NaN, true);
+  let next = hash;
+  for (let index = 0; index < 8; index += 1) {
+    next = hashShadowTokenByte(next, SHADOW_TOKEN_NUMBER.getUint8(index));
+  }
+  return next;
+}
+
+function hashShadowTokenString(hash: number, value: string): number {
+  let next = hash;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    next = hashShadowTokenByte(next, code & 0xff);
+    next = hashShadowTokenByte(next, code >>> 8);
+  }
+  return next;
+}
+
+function hashShadowTokenNumbers(hash: number, values: ArrayLike<number>): number {
+  let next = hash;
+  for (let index = 0; index < values.length; index += 1) {
+    next = hashShadowTokenNumber(next, values[index]);
+  }
+  return next;
+}
+
+/** @internal Deterministic cascade-local invalidation token producer. */
+export function buildCascadeLocalCacheTokens(input: {
+  readonly lights: ExtractedLights;
+  readonly visibility: CpuMultiViewVisibilityResult | undefined;
+  readonly scene: PersistentGpuDrivenState | undefined;
+  readonly validated: readonly ValidatedRenderable[];
+}): { readonly tokens: readonly string[]; readonly productionSceneToken: boolean } {
+  const plan = input.lights.directionalCsm;
+  if (plan === undefined) return { tokens: [], productionSceneToken: false };
+  const productionSceneToken = input.visibility !== undefined && input.scene !== undefined;
+  // PersistentRenderScene already owns O(1) slot lookup. The fallback map is
+  // retained only for older test/custom state doubles that do not expose the
+  // projection owner; it is intentionally not identity-cached because those
+  // doubles may mutate their slots array in place.
+  const slotByStableId =
+    input.scene === undefined || input.scene.projection !== undefined
+      ? undefined
+      : shadowSlotIndex(input.scene.slots);
+  const submissionMembership =
+    input.scene === undefined ? undefined : buildSubmissionCandidateMembership(input.scene.plan);
+  const cascadeCount = Math.min(input.lights.cascadeCount ?? 0, plan.cascades.length);
+  const tokens: string[] = [];
+  for (let cascadeIndex = 0; cascadeIndex < cascadeCount; cascadeIndex += 1) {
+    const cascade = plan.cascades[cascadeIndex];
+    if (cascade === undefined) continue;
+    let hash = 2_166_136_261;
+    hash = hashShadowTokenString(hash, 'csm-cache-v2');
+    hash = hashShadowTokenNumber(hash, cascadeIndex);
+    hash = hashShadowTokenNumber(hash, cascade.revision);
+    hash = hashShadowTokenNumbers(hash, cascade.lightViewProj);
+    hash = hashShadowTokenNumbers(hash, cascade.clipLightBounds);
+    hash = hashShadowTokenNumbers(hash, cascade.casterBroadphaseWorldAabb);
+    hash = hashShadowTokenNumber(hash, cascade.rasterViewport.x);
+    hash = hashShadowTokenNumber(hash, cascade.rasterViewport.y);
+    hash = hashShadowTokenNumber(hash, cascade.rasterViewport.w);
+    hash = hashShadowTokenNumber(hash, cascade.rasterViewport.h);
+
+    const visibilityView = input.visibility?.views.find(
+      (view) => view.kind === 'cascade' && view.cascadeIndex === cascadeIndex,
+    );
+    if (
+      productionSceneToken &&
+      visibilityView !== undefined &&
+      input.scene !== undefined &&
+      (slotByStableId !== undefined || input.scene.projection !== undefined)
+    ) {
+      const visibleStableIds = sortedUniqueStableIds(visibilityView.stableIds);
+      for (const stableId of visibleStableIds) {
+        const slot = input.scene.projection?.slotByIndex(stableId) ?? slotByStableId?.get(stableId);
+        if (slot === undefined) continue;
+        const revisions = slot.fact.revisions;
+        hash = hashShadowTokenNumber(hash, stableId);
+        hash = hashShadowTokenNumber(hash, slot.generation);
+        hash = hashShadowTokenNumber(hash, revisions.transform);
+        hash = hashShadowTokenNumber(hash, revisions.geometry);
+        hash = hashShadowTokenNumber(hash, revisions.material);
+        hash = hashShadowTokenNumber(hash, revisions.eligibility);
+        hash = hashShadowTokenNumber(hash, revisions.space);
+        hash = hashShadowTokenNumber(hash, revisions.batch);
+        hash = hashShadowTokenNumber(hash, revisions.resource);
+      }
+      const visibleBatchIds = new Set<number>();
+      if (submissionMembership !== undefined) {
+        for (const stableId of visibleStableIds) {
+          for (const entry of submissionMembership.byPrimitiveIndex.get(stableId) ?? []) {
+            visibleBatchIds.add(entry.batchId);
+          }
+        }
+        // SubmissionPlan owns a stable numeric batch order. Normalize the
+        // token input explicitly instead of inheriting Set insertion order
+        // from primitive/cascade traversal; a reorder must be a conservative
+        // miss at most, never a semantic token change by accident.
+        for (const batchId of [...visibleBatchIds].sort((left, right) => left - right)) {
+          const batch = submissionMembership.byBatchId.get(batchId);
+          if (batch === undefined) continue;
+          hash = hashShadowTokenNumber(hash, batch.batchId);
+          hash = hashShadowTokenNumber(hash, batch.generation);
+          hash = hashShadowTokenNumber(hash, batch.key.resourceRevision);
+          hash = hashShadowTokenNumber(hash, batch.key.materialRevision);
+          hash = hashShadowTokenString(hash, batch.key.pipelineClass);
+          hash = hashShadowTokenString(hash, batch.key.materialClass);
+          hash = hashShadowTokenString(hash, batch.key.materialResourceClass);
+        }
+      }
+    } else {
+      hash = hashShadowTokenNumbers(hash, cascade.casterRenderableIndices);
+      const casterMembership = new Set(cascade.casterRenderableIndices);
+      for (const entry of input.validated) {
+        const candidateIndex = entry.source.candidateIndex ?? entry.renderableIndex;
+        if (!casterMembership.has(candidateIndex)) continue;
+        const revisions = entry.source.sceneFact?.revisions;
+        hash = hashShadowTokenNumber(hash, candidateIndex);
+        hash = hashShadowTokenNumber(hash, revisions?.transform);
+        hash = hashShadowTokenNumber(hash, revisions?.geometry);
+        hash = hashShadowTokenNumber(hash, revisions?.material);
+        hash = hashShadowTokenNumber(hash, revisions?.eligibility);
+        hash = hashShadowTokenNumber(hash, revisions?.space);
+        hash = hashShadowTokenNumber(hash, revisions?.batch);
+        hash = hashShadowTokenNumber(hash, revisions?.resource);
+      }
+    }
+    tokens.push(`csm-${cascadeIndex}-${hash.toString(16).padStart(8, '0')}`);
+  }
+  return { tokens: Object.freeze(tokens), productionSceneToken };
+}
+
+function snapshotWorldState(world: World): DirectionalShadowWorldState {
+  return { projection: createWorldProjection(world) };
+}
+
+function sameWorldState(cached: DirectionalShadowCache, worlds: readonly World[]): boolean {
+  if (cached.worlds.length !== worlds.length) return false;
+  for (let index = 0; index < worlds.length; index += 1) {
+    const world = worlds[index];
+    if (world === undefined || cached.worlds[index] !== world) return false;
+    const cachedState = cached.worldStateTokens[index];
+    if (cachedState === undefined) return false;
+    const evidence = cachedState.projection.poll();
+    if (evidence.status !== 'delta' || evidence.changes.length > 0) return false;
+  }
+  return true;
+}
+
+function prepareDirectionalShadowCache(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  worlds: readonly World[],
+  lights: ExtractedLights,
+  shadowMapSize: number | undefined,
+  validatedOrdered: readonly ValidatedRenderable[],
+  visibility: CpuMultiViewVisibilityResult | undefined,
+  scene: PersistentGpuDrivenState | undefined,
+): DirectionalShadowCacheDecision {
+  const observeShadowCensus = internals.shadowDebugObservation === true;
+  const cascadeCount = lights.cascadeCount;
+  const built = buildCascadeLocalCacheTokens({
+    lights,
+    visibility,
+    scene,
+    validated: validatedOrdered,
+  });
+  observeDirectionalShadowTokenBuild(internals.metrics, observeShadowCensus, built);
+  if (
+    frameState.compiledFrameGraph === null ||
+    frameState.compiledFrameGraphTopologyKey === null ||
+    shadowMapSize === undefined ||
+    shadowMapSize <= 0 ||
+    cascadeCount === undefined ||
+    cascadeCount <= 0 ||
+    built.tokens.length === 0 ||
+    validatedOrdered.length === 0
+  ) {
+    if (observeShadowCensus && built.tokens.length > 0) {
+      internals.metrics.increment('shadow.csm.cache.precondition');
+    }
+    return { reuse: false, next: null, cascadeTokens: built.tokens, hitMask: 0 };
+  }
+
+  const cached = frameState.directionalShadowCache;
+  const assetCatalogEpoch = internals.assets.epoch;
+  const meshResidencyEpoch = internals.gpuStore.meshResidencyEpoch;
+  const evaluation = evaluateDirectionalShadowCache({
+    cached,
+    cascadeTokens: built.tokens,
+    productionSceneToken: built.productionSceneToken,
+    shadowMapSize,
+    cascadeCount,
+    pipelineHandle: frameState.installedPipelineHandle,
+    graphTopologyKey: frameState.compiledFrameGraphTopologyKey,
+    assetCatalogEpoch,
+    meshResidencyEpoch,
+    worldStateMatches:
+      cached !== null ? built.productionSceneToken || sameWorldState(cached, worlds) : false,
+  });
+  if (evaluation.reuse) {
+    const decision = {
+      reuse: true,
+      next: null,
+      cascadeTokens: built.tokens,
+      hitMask: evaluation.hitMask,
+    };
+    observeDirectionalShadowCacheDecision(
+      internals.metrics,
+      observeShadowCensus,
+      decision,
+      undefined,
+    );
+    return decision;
+  }
+
+  const decision = {
+    reuse: false,
+    next: null,
+    cascadeTokens: built.tokens,
+    hitMask: evaluation.hitMask,
+  };
+  observeDirectionalShadowCacheDecision(
+    internals.metrics,
+    observeShadowCensus,
+    decision,
+    observeShadowCensus ? evaluation.missReason : undefined,
+  );
+
+  const worldStateTokens = worlds.map((world) => snapshotWorldState(world));
+  if (worldStateTokens.some((state) => state === null)) {
+    // A world that does not expose the ECS mutation tokens cannot safely
+    // participate in a static-shadow reuse decision. Keep the conservative
+    // path for custom/test worlds instead of collapsing token indexes with a
+    // filter and risking a false-positive match.
+    if (observeShadowCensus) {
+      internals.metrics.increment('shadow.csm.cache.world-state-unavailable');
+    }
+    return decision;
+  }
+
+  return {
+    reuse: false,
+    cascadeTokens: built.tokens,
+    hitMask: evaluation.hitMask,
+    next: {
+      worlds: worlds.slice(),
+      worldStateTokens,
+      assetCatalogEpoch,
+      pipelineHandle: frameState.installedPipelineHandle,
+      graphTopologyKey: frameState.compiledFrameGraphTopologyKey,
+      shadowMapSize,
+      cascadeCount,
+      meshResidencyEpoch,
+      cascadeTokens: built.tokens,
+      productionSceneToken: built.productionSceneToken,
+    },
+  };
+}
+
+/**
+ * feat-20260704 M3/w18: validate renderable handles + collect the render plan,
+ * extracted verbatim from `recordFrame`. Empty `renderables` input or all-
+ * unregistered handles both yield an empty result (the Case E clear-pass-only
+ * path). Builds per-entry renderState / stencilReference overlays from the
+ * transparent-dispatch entries, resolves each MeshFilter.assetHandle through
+ * the AssetRegistry + GPU store (with the sprite 9-slice mesh swap), and fires
+ * structured `asset-not-registered` errors for handles that fail to resolve.
+ *
+ * @internal
+ */
+function validateRenderables(
+  internals: RenderSystemInternals,
+  world: World,
+  // feat-20260709-editor-world-partition ENGINE-fix-round2 (defect 2): the full
+  // Each renderable's mesh handle is a slot in its OWN world's
+  // sharedRefs; resolving against a foreign world either misses or resolves
+  // the wrong slot payload. Production resolves stable WorldRenderId through
+  // the renderer-owned lookup. Direct tests without that lookup retain the
+  // historical ordered-array fallback.
+  worlds: readonly World[],
+  renderables: readonly RenderableSnapshot[],
+  transparentDispatch: readonly DispatchEntry[],
+  worldForRenderId?: (worldId: number) => World | undefined,
+): ValidatedRenderable[] {
+  // bug-20260527-renderstate-pipeline-dispatch-gap D-4:
+  // build a renderableIndex -> renderState map from dispatch entries
+  // so each ValidatedRenderable carries its per-material renderState
+  // override without an O(n^2) back-scan in the draw loop.
+  const renderStateByRenderableIdx = new Map<number, MaterialRenderState | undefined>();
+  // w10: also build a renderableIndex -> stencilReference map from
+  // dispatch entries for per-draw setStencilReference calls.
+  const stencilRefByRenderableIdx = new Map<number, number | undefined>();
+  const variantSetByRenderableIdx = new Map<number, string | undefined>();
+  // Keep these three independent maps because each overlay has its own
+  // consumer and the last dispatch entry remains authoritative.  Populate
+  // them in one pass: the old code walked the same dispatch list three times
+  // and repeated the same renderableIndex branch / hash writes.
+  for (const de of transparentDispatch) {
+    const renderableIndex = de.renderableIndex;
+    if (renderableIndex === undefined) continue;
+    renderStateByRenderableIdx.set(renderableIndex, de.renderState);
+    stencilRefByRenderableIdx.set(renderableIndex, de.stencilReference);
+    variantSetByRenderableIdx.set(renderableIndex, variantSetFromDefines(de.defines));
+  }
+  const validated: ValidatedRenderable[] = [];
+  for (let rIdx = 0; rIdx < renderables.length; rIdx++) {
+    const r = renderables[rIdx];
+    if (r === undefined) continue;
+    // feat-20260709-editor-world-partition ENGINE-fix-round2 (defect 2): resolve
+    // this renderable's mesh against the world it was EXTRACTED from — NOT the
+    // single resource-owner `world`.
+    const renderableWorld =
+      worldForRenderId === undefined ? (worlds[r.worldId] ?? world) : worldForRenderId(r.worldId);
+    if (renderableWorld === undefined) {
+      internals.errorRegistry.fire(
+        new RhiError({
+          code: 'asset-not-registered',
+          expected: `attached renderer WorldRenderId ${r.worldId}`,
+          hint: 'keep every World passed to renderer.draw attached until its frame retires',
+          detail: { assetHandle: r.assetHandle },
+        }),
+      );
+      continue;
+    }
+    const assetRes = resolveRenderAsset<MeshAsset>(
+      renderableWorld,
+      toShared<'MeshAsset'>(r.assetHandle),
+    );
+    if (!assetRes.ok) {
+      internals.errorRegistry.fire(
+        new RhiError({
+          code: 'asset-not-registered',
+          expected: 'MeshFilter.assetHandle in the owning World sharedRefs',
+          hint: 'allocate or intern the MeshAsset in the same World before assigning MeshFilter.assetHandle',
+          detail: { assetHandle: r.assetHandle },
+        }),
+      );
+      continue;
+    }
+    const meshAssetHandle = toShared<'MeshAsset'>(r.assetHandle);
+    let meshHandles = internals.gpuStore.getMeshGpuHandles(meshAssetHandle, r.worldId);
+    if (meshHandles === undefined) {
+      const residentRes = internals.gpuStore.ensureResident(
+        meshAssetHandle,
+        assetRes.value,
+        r.worldId,
+      );
+      if (residentRes.ok) {
+        meshHandles = residentRes.value;
+      } else if (residentRes.error instanceof RhiError) {
+        internals.errorRegistry.fire(residentRes.error);
+      }
+    }
+    if (meshHandles === undefined) {
+      internals.errorRegistry.fire(
+        new RhiError({
+          code: 'asset-not-registered',
+          expected: 'GPU mesh buffers uploaded for assetHandle',
+          hint: 'await renderer.ready before draw; keep the MeshAsset live in the renderable World',
+          detail: { assetHandle: r.assetHandle },
+        }),
+      );
+      continue;
+    }
+    validated.push({
+      source: r,
+      mesh: meshHandles,
+      renderableIndex: rIdx,
+      renderState: renderStateByRenderableIdx.get(rIdx),
+      variantSet: variantSetByRenderableIdx.get(rIdx),
+      stencilReference: stencilRefByRenderableIdx.get(rIdx),
+    });
+  }
+  return validated;
+}
+
+/**
+ * feat-20260704 M3/w18: build the dispatch-ordered render plan, extracted
+ * verbatim from `recordFrame`. (1) M3/w26 dispatch-ordered reorder: reorder
+ * `validated` to follow the transparent-dispatch order (extract-order fallback
+ * for unmatched entries). (2) feat-20260608 mesh-SSBO capacity gate: size the
+ * mesh-SSBO + material-UBO pair to the larger of entity vs cumulative
+ * material-slot count, truncating on ceiling (graceful degradation). (3)
+ * feat-20260622 fold dispatch plan: build + apply the WebGL2 uniform-cap
+ * fallback + bump the folded-draws metric.
+ *
+ * @internal
+ */
+function buildDispatchPlan(
+  internals: RenderSystemInternals,
+  validated: readonly ValidatedRenderable[],
+  transparentDispatch: readonly DispatchEntry[],
+  foldBuckets: readonly FoldBucket[],
+): {
+  validatedOrdered: readonly ValidatedRenderable[];
+  foldDispatchPlan: FoldDispatchPlan | null;
+  materialSlotIndices: readonly (readonly number[])[];
+  materialSlots: readonly MaterialSnapshot[];
+  materialSlotOwners: readonly number[];
+  materialSlotCount: number;
+} {
+  // M3 / w26: dispatch-ordered render. The dispatch list is pre-sorted
+  // by queue (ascending, stable) by the extract stage per plan-strategy D-3.
+  // Reorder validated renderables to follow the dispatch order, falling
+  // back to extract order for renderables with no matching dispatch entry.
+  let dispatchOrderMatchesValidated = transparentDispatch.length === validated.length;
+  if (dispatchOrderMatchesValidated) {
+    for (let i = 0; i < validated.length; i++) {
+      if (transparentDispatch[i]?.renderableIndex !== validated[i]?.renderableIndex) {
+        dispatchOrderMatchesValidated = false;
+        break;
+      }
+    }
+  }
+  let validatedOrdered: readonly ValidatedRenderable[] = dispatchOrderMatchesValidated
+    ? validated
+    : [...validated];
+  if (transparentDispatch.length > 0 && !dispatchOrderMatchesValidated) {
+    const validatedByRenderableIdx = new Map<number, ValidatedRenderable>();
+    const seen = new Set<number>();
+    for (const v of validated) {
+      validatedByRenderableIdx.set(v.renderableIndex, v);
+    }
+    const ordered: ValidatedRenderable[] = [];
+    for (const de of transparentDispatch) {
+      if (de.renderableIndex === undefined) continue;
+      const v = validatedByRenderableIdx.get(de.renderableIndex);
+      if (v !== undefined && !seen.has(de.renderableIndex)) {
+        seen.add(de.renderableIndex);
+        ordered.push(v);
+      }
+    }
+    // Append any renderables not in the dispatch list (e.g. default-material entities)
+    for (const v of validated) {
+      if (!seen.has(v.renderableIndex)) {
+        ordered.push(v);
+      }
+    }
+    validatedOrdered = ordered;
+  }
+
+  const materialGroups = validatedOrdered.map((entry): readonly MaterialSnapshot[] => {
+    const shaderId = entry.source.material.materialShaderId;
+    if (shaderId === 'forgeax::sprite' || shaderId === 'forgeax::sprite-lit') {
+      return [entry.source.material];
+    }
+    return entry.source.materials.length > 0 ? entry.source.materials : [entry.source.material];
+  });
+  const materialSlotPlan = buildMaterialSlotPlan(materialGroups);
+  let materialSlotIndices = materialSlotPlan.slotIndices;
+  let materialSlots = materialSlotPlan.slots;
+  let materialSlotOwners = materialSlotPlan.slotOwners;
+  let materialSlotCount = materialSlots.length;
+
+  // feat-20260608-mesh-ssbo-dynamic-grow-l1-lift-1024-entity-cap M3 / T-M3-04:
+  // ensure the mesh-SSBO + material-UBO buffer pair is large enough to hold
+  // the render plan BEFORE the first per-entity writeBuffer.
+  // On `ok:false` the controller has already fired a structured RuntimeError
+  // (`mesh-ssbo-ceiling-reached` / `mesh-ssbo-capacity-exceeded`); we truncate
+  // the draw list to the largest complete entity prefix whose cumulative
+  // material slots fit `degradedToSlotCount` (graceful degradation per
+  // plan-strategy D-2): render the subset that fits, discard overflow, no
+  // black frame. The helper is idempotent across same-frame re-calls (AC-09)
+  // and short-circuits on length=0 / length<=slotCount (boundary table).
+  //
+  // bug-20260609: feat-20260608 M5 amend made the material UBO indexed by
+  // cumulative *material-slot* count (one slot per submesh material),
+  // which is >= entity count once any entity carries `materials.length>1`.
+  // The mesh + material buffer pair share `slotCount` (single allocator),
+  // so we size against the larger of the two requirements: entity count
+  // (mesh-SSBO consumer) vs cumulative material-slot count (material-UBO
+  // consumer). Sprite entities collapse to 1 slot in the material table,
+  // mirroring the same rule (sprite per-submesh OOS-1;
+  // post-w13 judgement key migrated to materialShaderId).
+  //
+  // feat-20260624 M1' / t7: sprite-lit treated identically to sprite
+  // for material-slot accounting (paramSchema mirror, t4).
+  const neededSlots = Math.max(validatedOrdered.length, materialSlotCount);
+  const meshSsboCapResult = ensureMeshSsboCapacity(internals, neededSlots);
+  if (!meshSsboCapResult.ok) {
+    // Graceful degradation: the controller reports slots, but this stage
+    // consumes entities. Find a complete prefix instead of slicing at the
+    // numeric slot count; a multi-material entity can consume several slots.
+    const degradedRenderableCount = findRenderablePrefixForSlotCapacity(
+      materialSlotIndices,
+      meshSsboCapResult.degradedToSlotCount,
+    );
+    materialSlotCount = materialSlotCountForPrefix(materialSlotIndices, degradedRenderableCount);
+    materialSlotIndices = materialSlotIndices.slice(0, degradedRenderableCount);
+    materialSlots = materialSlots.slice(0, materialSlotCount);
+    materialSlotOwners = materialSlotOwners.slice(0, materialSlotCount);
+    validatedOrdered = validatedOrdered.slice(0, degradedRenderableCount);
+  }
+
+  // feat-20260622-chunk-gpu-instancing-sprite-tilemap M1 / w4-record-swap
+  // (D-1): build the fold dispatch plan once `validatedOrdered` is final
+  // (post truncation by mesh-SSBO capacity gate). The plan re-keys each
+  // non-singleton bucket from `renderableIndex` to the validated-ordered
+  // index `i` consumed by the dispatch loops; the loops use it to skip
+  // non-head bucket members and emit one instanced drawIndexed per
+  // bucket head. Empty plan (no fold-eligible buckets) is a byte-
+  // identical no-op for the dispatch loops below (charter P3: silent
+  // pass-through, no error path).
+  let renderableToValidatedIdx: Map<number, number> | null = null;
+  let foldDispatchPlan: FoldDispatchPlan | null = null;
+  if (foldBuckets.length > 0) {
+    renderableToValidatedIdx = new Map<number, number>();
+    for (let i = 0; i < validatedOrdered.length; i++) {
+      const e = validatedOrdered[i];
+      if (e === undefined) continue;
+      renderableToValidatedIdx.set(e.renderableIndex, i);
+    }
+    foldDispatchPlan = buildFoldDispatchPlan(foldBuckets, renderableToValidatedIdx);
+
+    // feat-20260622 M2 / w11 (D-2 + D-9 + AC-05): WebGL2 uniform-fallback
+    // per-bucket instance-count cap. When caps.storageBuffer===false AND
+    // a fold bucket carries more than FOLD_UNIFORM_INSTANCE_CAP (128)
+    // instances, fire RhiError({code:'instancing-exceeds-uniform-cap'})
+    // AND remove the bucket from the dispatch plan so its members fall
+    // through to the per-entity drawIndexed exit (the same exit the
+    // mode-gate bypass uses — D-9 "shared fallback exit"). The frame
+    // stays visually correct (charter proposition 9 graceful
+    // degradation: no identity-collapse / black screen) while the cap
+    // event surfaces structurally for AI users (proposition 4 explicit
+    // failure on .code).
+    //
+    // Scope discrimination: tilemap-chunk-extract-system encodes
+    // Layer.value = (layerOrder<<20) | (chunkIndex & 0xfffff), so a
+    // bucket whose head entry carries non-zero low-20-bits is
+    // definitively a tilemap-chunk dispatch site. Plain sprite buckets
+    // use SPRITE_LAYER_VALUE = layerOrder<<20 (low-20 zero) by the
+    // documented convention (apps/hello/asi-world main.ts pattern).
+    // The chunkIndex===0 edge case maps to 'sprite' (the helper's
+    // default branch) — a one-bucket ambiguity per layerOrder that is
+    // acceptable for the AI-user affordance level (the error semantics
+    // — "this bucket exceeded the cap" — is the actionable signal;
+    // scope=sprite vs tilemap-chunk only refines the recovery hint).
+    if (foldDispatchPlan.headBuckets.size > 0 && !internals.device.caps.storageBuffer) {
+      const filteredHeads = new Map<number, FoldBucket>(foldDispatchPlan.headBuckets);
+      const filteredSkips = new Set<number>(foldDispatchPlan.skipIndices);
+      let filteredCount = foldDispatchPlan.foldedBucketCount;
+      for (const [headIdx, bucket] of foldDispatchPlan.headBuckets) {
+        const scope: 'sprite' | 'tilemap-chunk' =
+          (bucket.layer & 0xfffff) !== 0 ? 'tilemap-chunk' : 'sprite';
+        const decision = evaluateFoldBucketUniformCap(bucket, internals.device.caps, scope);
+        if (decision.fallback && decision.error !== undefined) {
+          internals.errorRegistry.fire(decision.error);
+          filteredHeads.delete(headIdx);
+          filteredCount -= 1;
+          for (let j = 1; j < bucket.entries.length; j++) {
+            const memberEntry = bucket.entries[j];
+            if (memberEntry === undefined) continue;
+            const memberValidatedIdx = renderableToValidatedIdx.get(memberEntry.renderableIndex);
+            if (memberValidatedIdx !== undefined) {
+              filteredSkips.delete(memberValidatedIdx);
+            }
+          }
+        }
+      }
+      if (filteredCount !== foldDispatchPlan.foldedBucketCount) {
+        foldDispatchPlan = {
+          headBuckets: filteredHeads,
+          skipIndices: filteredSkips,
+          foldedBucketCount: filteredCount,
+        };
+      }
+    }
+
+    // feat-20260622-chunk-gpu-instancing-sprite-tilemap M3 / w13 (D-3 +
+    // AC-06): increment `render.instancing.foldedDraws` once per fold-
+    // eligible head bucket retained after the cap-fallback filter above.
+    // The metric tracks instanced drawIndexed call count for this frame
+    // — cap-overrun buckets routed through the per-entity fallback exit
+    // are removed from `foldDispatchPlan` and therefore not counted, by
+    // construction (M2 / w11 cap-fallback + plan-strategy D-3 semantics).
+    // Singleton buckets (mode-bypass under D-5, or non-foldable under
+    // mode 0) carry `bucketSize === 1` and never enter `headBuckets`, so
+    // the per-entity drawIndexed path correctly does not count.
+    // SSOT helper lives in `render-system-fold.ts` — engine code never
+    // hardcodes the metric key string.
+    incrementFoldedDrawsMetric(foldDispatchPlan, internals.metrics);
+  }
+
+  return {
+    validatedOrdered,
+    foldDispatchPlan,
+    materialSlotIndices,
+    materialSlots,
+    materialSlotOwners,
+    materialSlotCount,
+  };
+}
+
+/**
+ * feat-20260704 M3/w18: per-frame cache clean-up (despawn eviction), extracted
+ * verbatim from `recordFrame`.
+ *
+ * feat-20260531-per-frame-bind-group-cache M4 / w14 (D-5): drop per-entity BG
+ * cache entries (materialBgPerEntity / instancesBgPerEntity) + instance buffers
+ * whose outer-Map entityKey (packed Entity u32) is absent from the current
+ * validated set, preventing unbounded growth after entity despawn. view + mesh
+ * caches are frame-shared (keyed by GPU resource handle objects, WeakMap chains
+ * naturally bounded) and are not touched. feat-20260619 M4 / F11: destroy the
+ * GPU instance buffer before Map.delete (D-6 symmetric release); failure fires
+ * errorRegistry + continues the sweep.
+ *
+ * @internal
+ */
+function cleanPerFrameCaches(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  validated: readonly ValidatedRenderable[],
+  retainedEntityKeys: ReadonlySet<number> = new Set<number>(),
+): void {
+  if (frameState.transientInstanceBuffers !== undefined) {
+    disposeTransientInstanceBuffers(frameState.transientInstanceBuffers, internals.errorRegistry);
+  }
+  // Build a Set<number> of worldEntityKey composites from the validated
+  // renderables. D-1a #4: validatedEntityKeys are worldEntityKey(worldId, entityKey)
+  // composites matching the write-side keys of #1-#3 — cross-world false eviction
+  // is prevented because worldEntityKey(0, k) !== worldEntityKey(1, k).
+  const validatedEntityKeys = new Set<number>(retainedEntityKeys);
+  for (const v of validated) {
+    validatedEntityKeys.add(worldEntityKey(v.source.worldId, v.source.entityKey));
+  }
+
+  // Clean per-entity material BG cache: drop outer-Map entries whose
+  // entityKey is absent from the current validated set. The shared and
+  // singleton material caches have no entityKey and are not touched here.
+  cleanPerEntityCache(frameState.materialBgPerEntity, validatedEntityKeys);
+
+  // Clean per-entity instances BG cache.
+  cleanPerEntityCache(frameState.instancesBgPerEntity, validatedEntityKeys);
+
+  // D-5 retrofit: instanceBuffers clean-up. The instanceBuffers Map is
+  // keyed by cacheKey (packed Entity u32, same as entityKey on
+  // RenderableSnapshot). Drop entries whose key is no longer in the
+  // validated set (OQ-3 / R-4). feat-20260619 M4 / F11: destroy the GPU
+  // buffer before Map.delete so despawned entities release their
+  // instance-buffer backing memory symmetrically (D-6).
+  //
+  // D-1a #1: instanceBuffers keys on the positive half (>= 0) are
+  // worldEntityKey composites matching the write side. Negative half
+  // fold-bucket keys (< 0) are NOT worldEntityKey; they are
+  // material-handle-based and cross-world collision is semantically
+  // correct (same material renders in same fold bucket).
+  for (const [key, entry] of frameState.instanceBuffers.entries()) {
+    if (!validatedEntityKeys.has(key)) {
+      if (!entry.buffer.isDestroyed) {
+        const r = entry.buffer.destroy();
+        if (!r.ok) internals.errorRegistry.fire(r.error);
+      }
+      frameState.instanceBuffers.delete(key);
+    }
+  }
+}
+
+/**
+ * feat-20260704 M3/w18: record-stage fold operator linear scan, extracted
+ * verbatim from `recordFrame`.
+ *
+ * feat-20260622-chunk-gpu-instancing-sprite-tilemap M1 / w4 + w5 (D-1, D-5):
+ * groups transparent-sort-ordered dispatch entries with equal (Layer.value,
+ * sortKey, materialHandle) into fold buckets. Mode-gate (D-5 extended): modes 0
+ * (LAYER_Z) and 1 (LAYER_Y) fold using the pos z/y lanes; modes 2/3 bypass per-entity
+ * (each entry a singleton bucket). Records `frameState.lastFoldBucketCount` =
+ * fold-eligible buckets (bucketSize > 1) for the AC-06 metric. Empty dispatch
+ * short-circuits (test fixtures pass null world).
+ *
+ * @internal
+ */
+function computeFoldBuckets(
+  world: World,
+  frameState: RenderFrameState,
+  transparentDispatch: readonly DispatchEntry[],
+  renderables: readonly RenderableSnapshot[],
+): readonly FoldBucket[] {
+  if (transparentDispatch.length === 0) {
+    frameState.lastFoldBucketCount = 0;
+    return [];
+  }
+  const transparentSortCfg = getTransparentSortConfig(world);
+
+  // Only layer-Z / layer-Y modes can produce non-singleton fold buckets.
+  // The other modes make one inert singleton per entry, which is discarded by
+  // buildFoldDispatchPlan. Returning the same empty plan here avoids allocating
+  // a transform matrix for every renderable when folding is disabled by mode.
+  if (
+    transparentSortCfg.mode !== TRANSPARENT_SORT_MODE_LAYER_Z &&
+    transparentSortCfg.mode !== TRANSPARENT_SORT_MODE_LAYER_Y
+  ) {
+    frameState.lastFoldBucketCount = 0;
+    return [];
+  }
+
+  // `transparentDispatch` is the legacy name for the complete sorted dispatch
+  // list. Opaque entries can never participate in the transparent-only fold
+  // plan, yet foldDispatchBuckets must preserve its general helper contract and
+  // therefore materializes an inert singleton (including a Float32Array(16))
+  // for each one. Filter only at this private production call site so the fold
+  // helper keeps its testable semantics while record avoids work whose result
+  // is provably discarded.
+  let transparentCount = 0;
+  for (const entry of transparentDispatch) {
+    if (renderables[entry.renderableIndex]?.material.transparent === true) {
+      transparentCount += 1;
+    }
+  }
+  if (transparentCount === 0) {
+    frameState.lastFoldBucketCount = 0;
+    return [];
+  }
+  const foldCandidates =
+    transparentCount === transparentDispatch.length
+      ? transparentDispatch
+      : transparentDispatch.filter(
+          (entry) => renderables[entry.renderableIndex]?.material.transparent === true,
+        );
+  const foldBuckets = foldDispatchBuckets(foldCandidates, transparentSortCfg.mode, renderables);
+  // Count only fold-eligible buckets (bucketSize > 1) so the metric
+  // surfaces fold actually reducing draws — singleton buckets under
+  // mode bypass do not change draw count, so they do not contribute.
+  let foldEligibleCount = 0;
+  for (const b of foldBuckets) {
+    if (b.bucketSize > 1) foldEligibleCount += 1;
+  }
+  frameState.lastFoldBucketCount = foldEligibleCount;
+  return foldBuckets;
+}