@forgeax/engine-animation 0.1.2

package/src/systems/advance-animation-player.ts

@@ -0,0 +1,971 @@
+import { Time, Update } from '@forgeax/engine-ecs';
+// @forgeax/engine-animation — advanceAnimationPlayer system (variable N-way blend).
+//
+// Per-tick: scans the variable-length SoA columns on each AnimationPlayer; for
+// each active slot (clips[i] != 0), advances times[i] += dt * speeds[i] (paused
+// gates the whole entity), samples the AnimationClip channels, and accumulates a
+// weighted pose into per-joint TRS accumulators. Once all slots are
+// folded in, each joint receives a single `world.set(joint, Transform,
+// fullPose)` (research F-2 / F-7 / F-8 — single write per joint per tick).
+//
+// Variable N-slot (feat-20260713 M1 / w5): the fixed 4-slot cap is retired. The
+// four parallel columns (clips / times / weights / speeds) are variable
+// `array<T>` columns, so row queries expose them through each entity's resolved
+// component value; the flat-SoA row window used by the retired fixed schema no
+// longer applies. Each entity's columns are read back as
+// resolved TypedArrays via `world.get(entity, AnimationPlayer)` and the advanced
+// `times` column is written back via `world.set` (D-7: weights are never written
+// back; clamping is read-time only). The blend math (translation linear / scale
+// linear / rotation nlerp, per-channel sumW) is byte-for-byte unchanged from the
+// fixed schema — only the loop bound moved from a hard 4 to the column length.
+//
+// Blend math (plan-strategy D-1):
+//   - translation / scale: linear average — accumulator += w_i * v_i, then
+//     accumulator /= Σw_i (per-channel sumW).
+//   - rotation: nlerp — first valid quat fixes the sign reference; later
+//     quats negated when dot < 0 to take the short arc; accumulator += w * q;
+//     finalize = normalize(accumulator). nlerp (not slerp) per D-1 (research
+//     F-7: Three.js Normal-mode mathematical form).
+//   - per-channel sumW: a joint receiving translation from 2 slots and rotation
+//     from 1 slot normalizes each channel by its own sum. Slot weights need not
+//     be partitioned-by-1 (research F-2).
+//
+// Best-effort failure modes (AC-05, plan-strategy D-7 / D-9):
+//   - clips[i] == 0          : skip slot, no resolver call (AC-04)
+//   - resolver miss          : skip slot
+//   - weights[i] < 0         : clamped via max(0, w); not written back (D-7)
+//   - duration mismatch      : per-slot modulo on its own duration
+//   - channel target missing : skip channel
+//   - channel missing on slot: per-channel normalize covers it
+//
+// w5 layers a dev-mode warn pass on top of these silent skips
+// (channel-target-missing / channel-missing-on-some-slot, once per
+// (entity, channelKey, reason)).
+//
+// Decision anchors:
+//   - requirements IS-2 / AC-03 / AC-04 / AC-05 (best-effort N-way blend)
+//   - plan-strategy D-1 (TRS accumulators + nlerp), D-3 (public Query, no
+//     query-backed lookup), D-7 (clamp without write-back), D-9 (negative speed
+//     natural reverse)
+//   - charter P4 (single Transform write per joint per tick)
+
+import type { EntityHandle, SystemHandle, World } from '@forgeax/engine-ecs';
+import { defineSystem, defineSystemSet, ENTITY_NULL_RAW } from '@forgeax/engine-ecs';
+import { createWorldProjection, type WorldProjection } from '@forgeax/engine-ecs/projection';
+import { MorphWeights, Transform } from '@forgeax/engine-scene';
+import type { AnimationChannel, AnimationClip, AnimationSampler } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import {
+  emitAnimationDiagnostic,
+  isAnimationDevMode,
+  _resetAnimationWarnsForTests as resetAnimationDiagnosticsForTests,
+} from '../animation-diagnostic';
+import { AnimationPlayer } from '../animation-player';
+import { AnimationTargetId, AnimationTargets } from '../animation-target';
+import { AnimationPlayerSlotLengthMismatchError } from '../player-errors';
+
+/**
+ * System name used when `registerAdvanceAnimationPlayer` installs the system
+ * into the ECS schedule. External consumers can reference this constant to
+ * declare `after: [ADVANCE_ANIMATION_PLAYER_SYSTEM]` on dependent systems.
+ */
+export const ADVANCE_ANIMATION_PLAYER_SYSTEM = 'advanceAnimationPlayer' as const;
+export const AnimationSet = defineSystemSet({ name: 'animation' });
+
+export function _resetAnimationWarnsForTests(world: World): void {
+  resetAnimationDiagnosticsForTests(world);
+  targetMapCacheByWorld.delete(world);
+}
+
+/**
+ * Advance all AnimationPlayer components by dt, blend the N active clips per
+ * entity, and write one Transform per joint per tick. Returns void.
+ *
+ * Iteration walks every matching row through the injected Query (D-3). Variable
+ * SoA columns are read through the row facade, so entity handles are collected first, then each
+ * entity's columns are resolved to TypedArrays via `world.get` and the advanced
+ * `times` written back via `world.set` (mutating the query bundle mid-walk would
+ * be a compile error against the reader shape).
+ */
+export function advanceAnimationPlayer(world: World, dt: number): void {
+  const query = world.query({ with: [AnimationPlayer] }).unwrap();
+
+  // Collect entity handles inside the walk (the Entity.self view is transient),
+  // then resolve + mutate each player outside it.
+  const entities: EntityHandle[] = [];
+  for (const row of query) entities.push(row.entity);
+
+  for (const entityRaw of entities) {
+    advanceOnePlayer(world, entityRaw, dt);
+  }
+}
+
+/**
+ * Resolved per-entity AnimationPlayer columns (a `world.get` snapshot). Variable
+ * columns alias the BufferPool slot bytes; the advanced `times` is written back
+ * via `world.set`, never in place, so the snapshot is treated read-only here.
+ */
+interface PlayerColumns {
+  readonly clips: Uint32Array;
+  readonly times: Float32Array;
+  readonly weights: Float32Array;
+  readonly speeds: Float32Array;
+  readonly paused: boolean;
+  readonly looping: boolean;
+}
+
+/**
+ * Advance one entity's AnimationPlayer: validate the four parallel column
+ * lengths at the evaluation entry (the single length chokepoint, D-5), walk the
+ * N slots to collect the active set + advanced times, write the advanced `times`
+ * column back, and fold the active slots into the joint pose.
+ *
+ * Length guard (AC-11 / D-5): variable columns are set field-by-field, so a
+ * consumer that desyncs their lengths is rejected here with the structured
+ * `animation-player-slot-length-mismatch` error rather than silently padded or
+ * truncated.
+ */
+function advanceOnePlayer(world: World, entityRaw: number, dt: number): void {
+  const entity = entityRaw as EntityHandle;
+  const apRes = world.get(entity, AnimationPlayer);
+  if (!apRes.ok) return;
+  const ap = apRes.value as unknown as PlayerColumns;
+
+  const count = ap.clips.length;
+  if (ap.times.length !== count || ap.weights.length !== count || ap.speeds.length !== count) {
+    throw new AnimationPlayerSlotLengthMismatchError({
+      entity: entityRaw,
+      clips: count,
+      times: ap.times.length,
+      weights: ap.weights.length,
+      speeds: ap.speeds.length,
+    });
+  }
+  if (count === 0) return;
+
+  const newTimes = new Float32Array(ap.times);
+  const activeSlots = collectActiveSlotsAndAdvanceTimes(world, ap, newTimes, dt);
+
+  // Persist the advanced times column (D-7: weights are never written back —
+  // negative-weight clamping is read-time only). Only `times` is set, so the
+  // clips / weights / speeds slots are left untouched.
+  world.set(entity, AnimationPlayer, { times: newTimes });
+
+  if (activeSlots.length === 0) return;
+  tickEntityTargets(world, entity, entityRaw, activeSlots);
+}
+
+/**
+ * Walk the N SoA slots for one entity: skip `clips[i]==0` (AC-04, no resolver
+ * call), skip resolver miss, advance `times[i] += speeds[i]*dt` (paused gates
+ * the entity per AC-05) into `newTimes`, wrap / clamp by clip duration based on
+ * `looping`, and keep the slot if `max(0, weights[i]) > 0` (D-7 clamp without
+ * write-back).
+ *
+ * The negative-speed reverse case (D-9) falls out naturally — `newTime`
+ * goes negative, the looping branch's `+= duration` re-anchors it; the
+ * looping=false branch clamps to 0.
+ */
+function collectActiveSlotsAndAdvanceTimes(
+  world: World,
+  ap: PlayerColumns,
+  newTimes: Float32Array,
+  dt: number,
+): ActiveSlot[] {
+  const paused = ap.paused;
+  const looping = ap.looping;
+  const count = ap.clips.length;
+  const activeSlots: ActiveSlot[] = [];
+
+  for (let i = 0; i < count; i++) {
+    const clipHandleRaw = ap.clips[i] ?? 0;
+    if (clipHandleRaw === 0) continue;
+    const clipLookup = world.sharedRefs.resolve<'AnimationClip', AnimationClip>(
+      toShared<'AnimationClip'>(clipHandleRaw),
+    );
+    if (!clipLookup.ok) throw clipLookup.error;
+    const clip = clipLookup.value;
+
+    const speed = ap.speeds[i] ?? 0;
+    let newTime = paused ? (ap.times[i] ?? 0) : (ap.times[i] ?? 0) + speed * dt;
+    const duration = clip.duration;
+    if (duration > 0) {
+      if (looping) {
+        newTime = newTime % duration;
+        if (newTime < 0) newTime += duration;
+      } else if (newTime > duration) {
+        newTime = duration;
+      } else if (newTime < 0) {
+        newTime = 0;
+      }
+    }
+    newTimes[i] = newTime;
+
+    const wRaw = ap.weights[i] ?? 0;
+    const w = wRaw > 0 ? wRaw : 0;
+    if (w === 0) continue;
+
+    activeSlots.push({ clip, clipHandleRaw, weight: w, time: newTime, slotIdx: i });
+  }
+
+  return activeSlots;
+}
+
+/**
+ * Target-write pass for one player: resolves its explicit target mirror and
+ * folds every active-slot channel into a per-target TRS accumulator (linear
+ * for translation/scale, nlerp with sign-fixed reference for rotation),
+ * then writes one `world.set(joint, Transform, ...)` per touched joint.
+ *
+ * Dev-mode warns (D-2):
+ *   - channel-target-missing: a clip channel ID does not resolve in this
+ *     player's explicit target set. Once per (entityId, clip, chIdx).
+ *   - channel-missing-on-some-slot: a (joint, kind) tuple is covered by
+ *     some slot but missing on another. The warn is emitted once per
+ *     (entityId, the-covering-slot's-clip, that-slot's-chIdx) so users
+ *     find the authoring point that has the channel; per-channel sumW
+ *     normalize covers the runtime gap regardless.
+ */
+interface TargetMap {
+  readonly entities: ReadonlyMap<string, EntityHandle>;
+  readonly missingTransforms: ReadonlyMap<string, EntityHandle>;
+  readonly duplicateIds: ReadonlySet<string>;
+  readonly hasStaleTarget: boolean;
+  readonly resolvedClips: WeakMap<AnimationClip, readonly (EntityHandle | undefined)[]>;
+}
+
+interface WorldTargetMapCache {
+  readonly projection: WorldProjection;
+  readonly players: Map<number, TargetMap>;
+}
+
+const targetMapCacheByWorld = new WeakMap<World, WorldTargetMapCache>();
+
+function targetMapForPlayer(world: World, player: EntityHandle): TargetMap {
+  let cache = targetMapCacheByWorld.get(world);
+  if (cache === undefined) {
+    cache = {
+      projection: createWorldProjection(world, {
+        components: [AnimationTargets, AnimationTargetId],
+      }),
+      players: new Map(),
+    };
+    targetMapCacheByWorld.set(world, cache);
+  } else {
+    const changes = cache.projection.poll();
+    if (changes.status === 'rebuild' || changes.changes.length > 0) {
+      cache = {
+        projection: createWorldProjection(world, {
+          components: [AnimationTargets, AnimationTargetId],
+        }),
+        players: new Map(),
+      };
+      targetMapCacheByWorld.set(world, cache);
+    }
+  }
+
+  const cached = cache.players.get(player as number);
+  if (cached !== undefined) return cached;
+  const built = buildTargetMap(world, player);
+  cache.players.set(player as number, built);
+  return built;
+}
+
+function buildTargetMap(world: World, player: EntityHandle): TargetMap {
+  const targets = world.get(player, AnimationTargets);
+  if (!targets.ok) {
+    return {
+      entities: new Map(),
+      missingTransforms: new Map(),
+      duplicateIds: new Set(),
+      hasStaleTarget: false,
+      resolvedClips: new WeakMap(),
+    };
+  }
+  const result = new Map<string, EntityHandle>();
+  const missingTransforms = new Map<string, EntityHandle>();
+  const seen = new Set<string>();
+  const ambiguous = new Set<string>();
+  let hasStaleTarget = false;
+  for (const raw of targets.value.targets) {
+    if (raw === ENTITY_NULL_RAW) continue;
+    const target = raw as EntityHandle;
+    const id = world.get(target, AnimationTargetId);
+    if (!id.ok) {
+      hasStaleTarget = true;
+      continue;
+    }
+    const targetId = id.value.value;
+    if (ambiguous.has(targetId)) continue;
+    if (seen.has(targetId)) {
+      result.delete(targetId);
+      missingTransforms.delete(targetId);
+      ambiguous.add(targetId);
+      continue;
+    }
+    seen.add(targetId);
+    if (world.get(target, Transform).ok) result.set(targetId, target);
+    else missingTransforms.set(targetId, target);
+  }
+  return {
+    entities: result,
+    missingTransforms,
+    duplicateIds: ambiguous,
+    hasStaleTarget,
+    resolvedClips: new WeakMap(),
+  };
+}
+
+function tickEntityTargets(
+  world: World,
+  entity: EntityHandle,
+  entityRaw: number,
+  activeSlots: ActiveSlot[],
+): void {
+  const targetMap = targetMapForPlayer(world, entity);
+
+  // Per-joint accumulator: lazily allocated when first channel writes.
+  // A Map keyed by jointIndex keeps the typical case (a few animated
+  // joints out of 20+) sparse rather than allocating for every joint.
+  const accumulators: Map<number, JointAccumulator> = new Map();
+  const morphAccumulators: Map<number, MorphWeightAccumulator> = new Map();
+  // Per-slot signature of (joint, channel-kind) coverage — used to detect
+  // channel-missing-on-some-slot once at the end of the channel walk. Lazy
+  // build only when there are 2+ active slots and dev-mode is on (warn pass
+  // is skipped in production by the shared diagnostics mode gate).
+  const slotCoverage: SlotCoverage[] = [];
+  const wantsCoverage = activeSlots.length >= 2 && isAnimationDevMode();
+  if (wantsCoverage) {
+    for (let i = 0; i < activeSlots.length; i++) slotCoverage.push(new Map());
+  }
+
+  for (let slotIdx = 0; slotIdx < activeSlots.length; slotIdx++) {
+    // biome-ignore lint/style/noNonNullAssertion: bounded by activeSlots.length
+    const slot = activeSlots[slotIdx]!;
+    const resolvedTargets = resolveClipTargets(world, entityRaw, slot, targetMap);
+    for (let chIdx = 0; chIdx < slot.clip.channels.length; chIdx++) {
+      // biome-ignore lint/style/noNonNullAssertion: bounded by channels.length
+      const channel = slot.clip.channels[chIdx]!;
+      const sampled = sampleChannel(channel.sampler, slot.time, channel.property);
+      if (sampled === undefined) continue;
+      const target =
+        channel.property === 'weights'
+          ? resolveChannelTarget(
+              world,
+              entityRaw,
+              slot.clipHandleRaw,
+              chIdx,
+              channel.targetId,
+              channel.property,
+              sampled.length,
+              targetMap,
+            )
+          : resolvedTargets[chIdx];
+      if (target === undefined) continue;
+      const targetRaw = target as number;
+
+      if (channel.property === 'weights') {
+        let weights = morphAccumulators.get(targetRaw);
+        if (weights === undefined) {
+          weights = { values: new Float32Array(sampled.length), sumW: 0 };
+          morphAccumulators.set(targetRaw, weights);
+        }
+        if (weights.values.length !== sampled.length) continue;
+        for (let i = 0; i < sampled.length; i++) {
+          weights.values[i] = (weights.values[i] ?? 0) + slot.weight * (sampled[i] ?? 0);
+        }
+        weights.sumW += slot.weight;
+        if (wantsCoverage) {
+          const coverage = slotCoverage[slotIdx];
+          if (coverage !== undefined) {
+            recordSlotCoverage(coverage, channel.targetId, channel.property, chIdx);
+          }
+        }
+        continue;
+      }
+
+      let acc = accumulators.get(targetRaw);
+      if (acc === undefined) {
+        acc = createAccumulator();
+        accumulators.set(targetRaw, acc);
+      }
+
+      foldChannelIntoAccumulator(acc, channel.property, sampled, slot.weight);
+
+      if (wantsCoverage) {
+        // biome-ignore lint/style/noNonNullAssertion: parallel to activeSlots
+        recordSlotCoverage(slotCoverage[slotIdx]!, channel.targetId, channel.property, chIdx);
+      }
+    }
+  }
+
+  if (wantsCoverage) {
+    emitMissingOnSomeSlotWarns(world, entityRaw, activeSlots, slotCoverage);
+  }
+
+  for (const [targetRaw, acc] of accumulators) {
+    const target = targetRaw as EntityHandle;
+    const partial = finalizeAccumulator(acc);
+    if (Object.keys(partial).length > 0) {
+      world.set(target, Transform as never, partial as never);
+    }
+  }
+  for (const [targetRaw, acc] of morphAccumulators) {
+    if (acc.sumW <= 0) continue;
+    const target = targetRaw as EntityHandle;
+    const weights = world.get(target, MorphWeights);
+    if (weights.ok && weights.value.weights.length === acc.values.length) {
+      const next = new Float32Array(acc.values.length);
+      for (let i = 0; i < next.length; i++) next[i] = (acc.values[i] ?? 0) / acc.sumW;
+      world.set(target, MorphWeights, { weights: next });
+    }
+  }
+}
+
+function resolveClipTargets(
+  world: World,
+  player: number,
+  slot: ActiveSlot,
+  targetMap: TargetMap,
+): readonly (EntityHandle | undefined)[] {
+  const cached = targetMap.resolvedClips.get(slot.clip);
+  if (cached !== undefined) return cached;
+
+  const targets = slot.clip.channels.map((channel, channelIndex) =>
+    channel.property === 'weights'
+      ? undefined
+      : resolveChannelTarget(
+          world,
+          player,
+          slot.clipHandleRaw,
+          channelIndex,
+          channel.targetId,
+          channel.property,
+          undefined,
+          targetMap,
+        ),
+  );
+  targetMap.resolvedClips.set(slot.clip, targets);
+  return targets;
+}
+
+function resolveChannelTarget(
+  world: World,
+  player: number,
+  clip: number,
+  channel: number,
+  targetId: string,
+  property: ChannelKind,
+  expectedWeightCount: number | undefined,
+  targetMap: TargetMap,
+): EntityHandle | undefined {
+  if (targetMap.duplicateIds.has(targetId)) {
+    emitTargetDiagnostic(
+      world,
+      player,
+      clip,
+      channel,
+      targetId,
+      'animation-target-id-duplicate',
+      'target-id-duplicate',
+      'assign a unique AnimationTargetId to each target owned by this player',
+    );
+    return undefined;
+  }
+  const target = targetMap.entities.get(targetId);
+  if (target === undefined) {
+    const transformMissingTarget = targetMap.missingTransforms.get(targetId);
+    if (transformMissingTarget !== undefined) {
+      emitTargetDiagnostic(
+        world,
+        player,
+        clip,
+        channel,
+        targetId,
+        'animation-target-transform-missing',
+        'transform-missing',
+        'attach Transform to the bound animation target',
+        transformMissingTarget as number,
+      );
+      return undefined;
+    }
+    emitTargetDiagnostic(
+      world,
+      player,
+      clip,
+      channel,
+      targetId,
+      targetMap.hasStaleTarget ? 'animation-target-owner-stale' : 'animation-target-missing',
+      targetMap.hasStaleTarget ? 'target-stale' : 'target-missing',
+      targetMap.hasStaleTarget
+        ? 'remove the stale target relation or bind a live replacement'
+        : 'bind the matching AnimationTargetId to this player',
+    );
+    return undefined;
+  }
+  if (property === 'weights') {
+    const weights = world.get(target, MorphWeights);
+    if (!weights.ok) {
+      emitAnimationDiagnostic(world, {
+        code: 'animation-target-morph-weights-missing',
+        hint: 'attach MorphWeights to the morph target entity before playing a weights channel',
+        detail: {
+          player,
+          clip,
+          channel,
+          targetId,
+          reason: 'morph-weights-missing',
+          target: target as number,
+          property,
+          ...(expectedWeightCount === undefined ? {} : { expectedWeightCount }),
+        },
+      });
+      return undefined;
+    }
+    if (expectedWeightCount !== undefined && weights.value.weights.length !== expectedWeightCount) {
+      emitAnimationDiagnostic(world, {
+        code: 'animation-morph-weight-count-mismatch',
+        hint: 'make MorphWeights.length equal the animation channel output width',
+        detail: {
+          player,
+          clip,
+          channel,
+          targetId,
+          reason: 'morph-weight-count-mismatch',
+          target: target as number,
+          property,
+          expectedWeightCount,
+          actualWeightCount: weights.value.weights.length,
+        },
+      });
+      return undefined;
+    }
+    return target;
+  }
+  if (!world.get(target, Transform).ok) {
+    emitTargetDiagnostic(
+      world,
+      player,
+      clip,
+      channel,
+      targetId,
+      'animation-target-transform-missing',
+      'transform-missing',
+      'attach Transform to the bound animation target',
+      target as number,
+    );
+    return undefined;
+  }
+  return target;
+}
+
+/**
+ * Per-slot (joint -> covered kinds) signature. The `chIdxByKind` field
+ * remembers which channel index of the slot's clip first covered the
+ * (joint, kind) pair — used as the channelKey when emitting a
+ * channel-missing-on-some-slot warn so the user can locate the
+ * authoring channel that exposed the asymmetry.
+ */
+type ChannelKind = AnimationChannel['property'];
+type SlotCoverage = Map<string, Map<ChannelKind, number>>;
+
+function recordSlotCoverage(
+  cov: SlotCoverage,
+  targetId: string,
+  kind: ChannelKind,
+  chIdx: number,
+): void {
+  let perTarget = cov.get(targetId);
+  if (perTarget === undefined) {
+    perTarget = new Map();
+    cov.set(targetId, perTarget);
+  }
+  if (!perTarget.has(kind)) perTarget.set(kind, chIdx);
+}
+
+function emitTargetDiagnostic(
+  world: World,
+  entityRaw: number,
+  clipHandleRaw: number,
+  chIdx: number,
+  targetId: string,
+  code:
+    | 'animation-target-missing'
+    | 'animation-target-transform-missing'
+    | 'animation-target-id-duplicate'
+    | 'animation-target-owner-stale',
+  reason: 'target-missing' | 'transform-missing' | 'target-id-duplicate' | 'target-stale',
+  hint: string,
+  target?: number,
+): void {
+  emitAnimationDiagnostic(world, {
+    code,
+    hint,
+    detail: {
+      player: entityRaw,
+      clip: clipHandleRaw,
+      channel: chIdx,
+      targetId,
+      reason,
+      ...(target === undefined ? {} : { target }),
+    },
+  });
+}
+
+/**
+ * Reconcile per-slot coverage against the union: for any (joint, kind)
+ * tuple covered by ≥ 1 slot but missing on another, emit the warn once per
+ * (entityId, the-covering-slot's-clip, that-slot's-chIdx, reason). Each
+ * covering slot may emit its own warn pointing at its own channel index —
+ * authoring tools can land on any of them.
+ */
+function emitMissingOnSomeSlotWarns(
+  world: World,
+  entityRaw: number,
+  activeSlots: ActiveSlot[],
+  slotCoverage: SlotCoverage[],
+): void {
+  // Union over all slots: jointIndex -> Set<ChannelKind>.
+  const union: Map<string, Set<ChannelKind>> = new Map();
+  for (const cov of slotCoverage) {
+    for (const [targetId, kindMap] of cov) {
+      let set = union.get(targetId);
+      if (set === undefined) {
+        set = new Set();
+        union.set(targetId, set);
+      }
+      for (const kind of kindMap.keys()) set.add(kind);
+    }
+  }
+
+  for (const [targetId, unionKinds] of union) {
+    for (let slotIdx = 0; slotIdx < activeSlots.length; slotIdx++) {
+      // biome-ignore lint/style/noNonNullAssertion: parallel arrays
+      const cov = slotCoverage[slotIdx]!;
+      const slotKinds = cov.get(targetId);
+      for (const kind of unionKinds) {
+        if (slotKinds?.has(kind)) continue;
+        // This slot is missing `kind` on jointIndex. Find the slot that
+        // does cover (joint, kind) and use ITS chIdx as the warn anchor.
+        for (let coveringIdx = 0; coveringIdx < activeSlots.length; coveringIdx++) {
+          if (coveringIdx === slotIdx) continue;
+          // biome-ignore lint/style/noNonNullAssertion: parallel arrays
+          const coveringCov = slotCoverage[coveringIdx]!;
+          const coveringKinds = coveringCov.get(targetId);
+          if (coveringKinds === undefined) continue;
+          const chIdx = coveringKinds.get(kind);
+          if (chIdx === undefined) continue;
+          // biome-ignore lint/style/noNonNullAssertion: parallel arrays
+          const coveringSlot = activeSlots[coveringIdx]!;
+          emitAnimationDiagnostic(world, {
+            code: 'animation-channel-missing',
+            hint: `author the missing ${kind} channel on the slot whose clip lacks it`,
+            detail: {
+              player: entityRaw,
+              clip: coveringSlot.clipHandleRaw,
+              channel: chIdx,
+              targetId,
+              reason: 'channel-missing',
+              property: kind,
+            },
+          });
+          break;
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Add a sampled (translation / rotation / scale) channel to the per-joint
+ * accumulator, weighted by the slot's weight. Quat handling sign-fixes
+ * against the first quat seen so the nlerp picks the short arc (research
+ * F-7); per-channel sumW lets translation / rotation / scale normalize
+ * independently when slot coverage differs (research F-2 / AC-05(b)).
+ */
+function foldChannelIntoAccumulator(
+  acc: JointAccumulator,
+  property: ChannelKind,
+  sampled: number[],
+  weight: number,
+): void {
+  if (property === 'weights') return;
+  if (property === 'translation' && sampled.length >= 3) {
+    acc.posX += weight * (sampled[0] ?? 0);
+    acc.posY += weight * (sampled[1] ?? 0);
+    acc.posZ += weight * (sampled[2] ?? 0);
+    acc.sumWPos += weight;
+    acc.hasPos = true;
+    return;
+  }
+  if (property === 'rotation' && sampled.length >= 4) {
+    const qx = sampled[0] ?? 0;
+    const qy = sampled[1] ?? 0;
+    const qz = sampled[2] ?? 0;
+    const qw = sampled[3] ?? 1;
+    if (!acc.hasQuat) {
+      acc.refQX = qx;
+      acc.refQY = qy;
+      acc.refQZ = qz;
+      acc.refQW = qw;
+      acc.quatX = weight * qx;
+      acc.quatY = weight * qy;
+      acc.quatZ = weight * qz;
+      acc.quatW = weight * qw;
+      acc.hasQuat = true;
+    } else {
+      const dot = acc.refQX * qx + acc.refQY * qy + acc.refQZ * qz + acc.refQW * qw;
+      const sign = dot < 0 ? -1 : 1;
+      acc.quatX += weight * sign * qx;
+      acc.quatY += weight * sign * qy;
+      acc.quatZ += weight * sign * qz;
+      acc.quatW += weight * sign * qw;
+    }
+    acc.sumWQuat += weight;
+    return;
+  }
+  if (property === 'scale' && sampled.length >= 3) {
+    acc.scaleX += weight * (sampled[0] ?? 1);
+    acc.scaleY += weight * (sampled[1] ?? 1);
+    acc.scaleZ += weight * (sampled[2] ?? 1);
+    acc.sumWScale += weight;
+    acc.hasScale = true;
+  }
+}
+
+/**
+ * Per-channel normalize: divide by per-channel sumW. Quat finalize
+ * normalizes the resulting vec4 (nlerp). A channel with sumW=0 is silently
+ * absent from the partial — `world.set` with a partial leaves untouched
+ * fields at their existing values (AC-05(b) per-channel fallback). Channel
+ * granularity maps 1:1 onto the Transform array columns (feat-20260709 M2):
+ * an animated channel always covers its whole pos/quat/scale vector, so the
+ * per-field partial write semantics are unchanged by the column migration.
+ */
+function finalizeAccumulator(acc: JointAccumulator): Record<string, number[]> {
+  const partial: Record<string, number[]> = {};
+  if (acc.hasPos && acc.sumWPos > 0) {
+    partial.pos = [acc.posX / acc.sumWPos, acc.posY / acc.sumWPos, acc.posZ / acc.sumWPos];
+  }
+  if (acc.hasQuat && acc.sumWQuat > 0) {
+    const qx = acc.quatX / acc.sumWQuat;
+    const qy = acc.quatY / acc.sumWQuat;
+    const qz = acc.quatZ / acc.sumWQuat;
+    const qw = acc.quatW / acc.sumWQuat;
+    const len = Math.sqrt(qx * qx + qy * qy + qz * qz + qw * qw);
+    if (len > 0) {
+      // Component order [x, y, z, w] (E6).
+      partial.quat = [qx / len, qy / len, qz / len, qw / len];
+    }
+  }
+  if (acc.hasScale && acc.sumWScale > 0) {
+    partial.scale = [
+      acc.scaleX / acc.sumWScale,
+      acc.scaleY / acc.sumWScale,
+      acc.scaleZ / acc.sumWScale,
+    ];
+  }
+  return partial;
+}
+
+/**
+ * Per-active-slot snapshot folded into the per-entity accumulator pass:
+ * the resolved clip + the (advanced) sample time + the clamped weight, so
+ * the channel loop never has to re-read the SoA columns.
+ */
+interface ActiveSlot {
+  readonly clip: AnimationClip;
+  readonly clipHandleRaw: number;
+  readonly weight: number;
+  readonly time: number;
+  readonly slotIdx: number;
+}
+
+interface JointAccumulator {
+  posX: number;
+  posY: number;
+  posZ: number;
+  sumWPos: number;
+  hasPos: boolean;
+  // Quat reference + accumulator. refQ* is the first sampled quat (sign-fixed)
+  // so subsequent quats with dot<0 are negated for short-arc nlerp.
+  refQX: number;
+  refQY: number;
+  refQZ: number;
+  refQW: number;
+  quatX: number;
+  quatY: number;
+  quatZ: number;
+  quatW: number;
+  sumWQuat: number;
+  hasQuat: boolean;
+  scaleX: number;
+  scaleY: number;
+  scaleZ: number;
+  sumWScale: number;
+  hasScale: boolean;
+}
+
+interface MorphWeightAccumulator {
+  readonly values: Float32Array;
+  sumW: number;
+}
+
+function createAccumulator(): JointAccumulator {
+  return {
+    posX: 0,
+    posY: 0,
+    posZ: 0,
+    sumWPos: 0,
+    hasPos: false,
+    refQX: 0,
+    refQY: 0,
+    refQZ: 0,
+    refQW: 1,
+    quatX: 0,
+    quatY: 0,
+    quatZ: 0,
+    quatW: 0,
+    sumWQuat: 0,
+    hasQuat: false,
+    scaleX: 0,
+    scaleY: 0,
+    scaleZ: 0,
+    sumWScale: 0,
+    hasScale: false,
+  };
+}
+
+/**
+ * Sample an animation sampler at the given time.
+ *
+ * Returns an array of floats whose length matches the property element count:
+ *   - translation / scale: 3 floats (vec3)
+ *   - rotation: 4 floats (quat)
+ */
+function sampleChannel(
+  sampler: AnimationSampler,
+  time: number,
+  property: ChannelKind,
+): number[] | undefined {
+  const { input, output, interpolation } = sampler;
+  if (input.length === 0) return undefined;
+
+  const elementCount = output.length / input.length;
+
+  // Clamp if before first key.
+  if (time <= (input[0] as number)) {
+    return sliceOutput(output, 0, elementCount);
+  }
+
+  // Clamp if after last key.
+  const lastIdx = input.length - 1;
+  if (time >= (input[lastIdx] as number)) {
+    return sliceOutput(output, lastIdx, elementCount);
+  }
+
+  // Binary search for the bracket.
+  let lo = 0;
+  let hi = input.length - 1;
+  while (hi - lo > 1) {
+    const mid = (lo + hi) >> 1;
+    if ((input[mid] as number) <= time) {
+      lo = mid;
+    } else {
+      hi = mid;
+    }
+  }
+  const prev = lo;
+  const next = hi;
+
+  if (interpolation === 'STEP') {
+    return sliceOutput(output, prev, elementCount);
+  }
+
+  // LINEAR interpolation.
+  const t0 = input[prev] as number;
+  const t1 = input[next] as number;
+  const alpha = (time - t0) / (t1 - t0);
+
+  const prevValues = sliceOutput(output, prev, elementCount);
+  const nextValues = sliceOutput(output, next, elementCount);
+
+  if (property === 'rotation') {
+    // Per-sampler quat slerp at the bracket level — multi-slot blending is
+    // a separate stage (nlerp at the entity level, in advanceAnimationPlayer).
+    const px = prevValues[0] ?? 0;
+    const py = prevValues[1] ?? 0;
+    const pz = prevValues[2] ?? 0;
+    const pw = prevValues[3] ?? 1;
+    let nx = nextValues[0] ?? 0;
+    let ny = nextValues[1] ?? 0;
+    let nz = nextValues[2] ?? 0;
+    let nw = nextValues[3] ?? 1;
+    let dot = px * nx + py * ny + pz * nz + pw * nw;
+    if (dot < 0) {
+      nx = -nx;
+      ny = -ny;
+      nz = -nz;
+      nw = -nw;
+      dot = -dot;
+    }
+    if (dot > 0.9995) {
+      // Near-parallel — fall back to nlerp to avoid sin(theta) -> 0 blowup.
+      const lx = px + alpha * (nx - px);
+      const ly = py + alpha * (ny - py);
+      const lz = pz + alpha * (nz - pz);
+      const lw = pw + alpha * (nw - pw);
+      const len = Math.sqrt(lx * lx + ly * ly + lz * lz + lw * lw);
+      return len > 0 ? [lx / len, ly / len, lz / len, lw / len] : [0, 0, 0, 1];
+    }
+    const theta = Math.acos(dot);
+    const sinTheta = Math.sin(theta);
+    const sa = Math.sin((1 - alpha) * theta) / sinTheta;
+    const sb = Math.sin(alpha * theta) / sinTheta;
+    return [px * sa + nx * sb, py * sa + ny * sb, pz * sa + nz * sb, pw * sa + nw * sb];
+  }
+
+  return prevValues.map((value, index) => value + alpha * ((nextValues[index] ?? value) - value));
+}
+
+function sliceOutput(output: Float32Array, index: number, elementCount: number): number[] {
+  const result: number[] = [];
+  const base = index * elementCount;
+  for (let i = 0; i < elementCount; i++) {
+    result.push(output[base + i] as number);
+  }
+  return result;
+}
+
+/**
+ * The `advanceAnimationPlayer` system token.
+ *
+ * Module-level `defineSystem` with the real fn body — no closure and no
+ * feature-specific resolver resource. Handles resolve from the World passed
+ * to the system, so invalid clips become structured animation failures.
+ */
+export const AdvanceAnimationPlayer: SystemHandle<readonly []> = defineSystem({
+  name: ADVANCE_ANIMATION_PLAYER_SYSTEM,
+  queries: [],
+  before: ['propagateTransforms'],
+  fn: (world) => {
+    advanceAnimationPlayer(world, world.getResource(Time).delta);
+  },
+});
+
+/**
+ * Register `advanceAnimationPlayer` into the ECS schedule before
+ * `propagateTransforms`. Animation clip handles are resolved from the running
+ * World; callers only need to register the system once per World.
+ *
+ * @example Driver registers once per World:
+ *   const world = new World();
+ *   registerAdvanceAnimationPlayer(world);
+ *   // ...system will run each world.update() before propagateTransforms...
+ */
+export function registerAdvanceAnimationPlayer(world: World): () => void {
+  world.addSystems(Update, AnimationSet, [AdvanceAnimationPlayer]).unwrap();
+  return () => {
+    world.removeSystem(Update, ADVANCE_ANIMATION_PLAYER_SYSTEM);
+  };
+}