@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

package/src/__tests__/animation-graph-nesting.unit.test.ts

@@ -0,0 +1,84 @@
+// feat-20260713-animation-state-machine-plugin M3 / w19 — nested DAG post-order
+// evaluation (AC-06).
+//
+// AC-06: a multi-layer DAG evaluates post-order so a nested subgraph's
+// normalized effective weight is correctly propagated down before its parent
+// combines it. This mirrors the AC-13 fox demo topology:
+//
+//   Add( Base=Blend(Survey, Loco=Blend(Walk, Run)), Overlay@0.5 )
+//
+// With all static/runtime weights 1 (Overlay static 0.5):
+//   - Loco normalizes Walk/Run to 0.5 each, then scales by the 0.5 it receives
+//     from Base's normalization -> Walk=0.25, Run=0.25.
+//   - Base normalizes Survey vs Loco to 0.5 each -> Survey=0.5, Loco subtree=0.5.
+//   - Overlay is additive on top at its static 0.5.
+// Derived slots (clip-node order): [Survey, Walk, Run, Overlay]
+//   = [0.5, 0.25, 0.25, 0.5]; base subtree sums to 1, total is 1.5.
+//
+// TDD red anchor: before w24 + w25 the file fails to compile; after them the
+// nested weights propagate as above.
+
+import {
+  AnimationPlayer,
+  defineAnimationGraph,
+  evaluateAnimationGraph,
+} from '@forgeax/engine-animation';
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function registerClip(world: World, duration: number) {
+  const clip: AnimationClip = { kind: 'animation-clip', duration, channels: [] };
+  return world.allocSharedRef('AnimationClip', clip);
+}
+
+const lookupClip = (_guid: string): AnimationClip => ({
+  kind: 'animation-clip',
+  duration: 10,
+  channels: [],
+});
+
+function readWeights(world: World, e: EntityHandle): Float32Array {
+  return (world.get(e, AnimationPlayer).unwrap() as unknown as { weights: Float32Array }).weights;
+}
+
+describe('evaluateAnimationGraph — nested DAG post-order (M3 / w19)', () => {
+  it('propagates a nested subgraph effective weight down through post-order eval', () => {
+    const world = new World();
+    registerClip(world, 10);
+    registerClip(world, 10);
+    registerClip(world, 10);
+    registerClip(world, 10);
+
+    const built = defineAnimationGraph((b) => {
+      const surveyNode = b.clip('test/animation-clip-survey'); // node 0
+      const walkNode = b.clip('test/animation-clip-walk'); // node 1
+      const runNode = b.clip('test/animation-clip-run'); // node 2
+      const loco = b.blend([walkNode, runNode]); // node 3
+      const base = b.blend([surveyNode, loco]); // node 4
+      const overlayNode = b.clip('test/animation-clip-overlay', 0.5); // node 5
+      return b.add(base, [overlayNode]); // node 6 (root)
+    });
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    const graphH = world.allocSharedRef('AnimationGraph', built.value);
+
+    const e = world
+      .spawn({ component: AnimationPlayer, data: { graph: graphH } })
+      .unwrap() as EntityHandle;
+
+    evaluateAnimationGraph(world, 0, lookupClip);
+
+    const weights = readWeights(world, e);
+    expect(weights.length).toBe(4); // Survey, Walk, Run, Overlay
+    expect(weights[0]).toBeCloseTo(0.5, 5); // Survey
+    expect(weights[1]).toBeCloseTo(0.25, 5); // Walk
+    expect(weights[2]).toBeCloseTo(0.25, 5); // Run
+    expect(weights[3]).toBeCloseTo(0.5, 5); // Overlay (additive)
+
+    // Base subtree (Survey + Walk + Run) normalizes to 1; Overlay adds 0.5.
+    const baseSubtree = (weights[0] ?? 0) + (weights[1] ?? 0) + (weights[2] ?? 0);
+    expect(baseSubtree).toBeCloseTo(1, 5);
+  });
+});

package/src/__tests__/animation-graph-orthogonal-weight.unit.test.ts

@@ -0,0 +1,98 @@
+// feat-20260713-animation-state-machine-plugin M3 / w20 — orthogonal product
+// weight (AC-07).
+//
+// AC-07: a node's effective weight = runtime weight (AnimationPlayer.nodeWeights,
+// indexed by node) x graph static weight (the node's declared weight). The two
+// factors are orthogonal: changing either one scales the effective weight by the
+// product. The canonical check is 0.5 x 0.4 = 0.2.
+//
+// TDD red anchor: before w24 (nodeWeights field) + w25 the file fails to
+// compile; after them the effective weight tracks the product.
+
+import {
+  AnimationPlayer,
+  defineAnimationGraph,
+  evaluateAnimationGraph,
+} from '@forgeax/engine-animation';
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function registerClip(world: World, duration: number) {
+  const clip: AnimationClip = { kind: 'animation-clip', duration, channels: [] };
+  return world.allocSharedRef('AnimationClip', clip);
+}
+
+const lookupClip = (_guid: string): AnimationClip => ({
+  kind: 'animation-clip',
+  duration: 10,
+  channels: [],
+});
+
+function readWeight0(world: World, e: EntityHandle): number {
+  const weights = (world.get(e, AnimationPlayer).unwrap() as unknown as { weights: Float32Array })
+    .weights;
+  return weights[0] ?? Number.NaN;
+}
+
+describe('evaluateAnimationGraph — orthogonal product weight (M3 / w20)', () => {
+  it('effective weight = runtime x static (0.5 x 0.4 = 0.2)', () => {
+    const world = new World();
+    registerClip(world, 10);
+
+    // Single clip node with STATIC weight 0.4.
+    const built = defineAnimationGraph((b) => b.clip('test/animation-clip-h', 0.4));
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    const graphH = world.allocSharedRef('AnimationGraph', built.value);
+
+    // Runtime weight 0.5 on node 0.
+    const e = world
+      .spawn({
+        component: AnimationPlayer,
+        data: { graph: graphH, nodeWeights: new Float32Array([0.5]) },
+      })
+      .unwrap() as EntityHandle;
+
+    evaluateAnimationGraph(world, 0, lookupClip);
+    expect(readWeight0(world, e)).toBeCloseTo(0.2, 5); // 0.5 x 0.4
+
+    // Change ONLY the runtime factor to 1.0 -> effective tracks the product 0.4.
+    world.set(e, AnimationPlayer, { nodeWeights: new Float32Array([1]) });
+    evaluateAnimationGraph(world, 0, lookupClip);
+    expect(readWeight0(world, e)).toBeCloseTo(0.4, 5); // 1.0 x 0.4
+  });
+
+  it('changing ONLY the static factor scales the effective weight by the product', () => {
+    const world = new World();
+    registerClip(world, 10);
+    registerClip(world, 10);
+
+    // Two graphs differing only in the static weight (0.4 vs 0.8).
+    const gA = defineAnimationGraph((b) => b.clip('test/animation-clip-a', 0.4));
+    const gB = defineAnimationGraph((b) => b.clip('test/animation-clip-b', 0.8));
+    expect(gA.ok && gB.ok).toBe(true);
+    if (!gA.ok || !gB.ok) return;
+    const hA = world.allocSharedRef('AnimationGraph', gA.value);
+    const hB = world.allocSharedRef('AnimationGraph', gB.value);
+
+    // Same runtime factor 0.5 on both.
+    const eA = world
+      .spawn({
+        component: AnimationPlayer,
+        data: { graph: hA, nodeWeights: new Float32Array([0.5]) },
+      })
+      .unwrap() as EntityHandle;
+    const eB = world
+      .spawn({
+        component: AnimationPlayer,
+        data: { graph: hB, nodeWeights: new Float32Array([0.5]) },
+      })
+      .unwrap() as EntityHandle;
+
+    evaluateAnimationGraph(world, 0, lookupClip);
+    expect(readWeight0(world, eA)).toBeCloseTo(0.2, 5); // 0.5 x 0.4
+    expect(readWeight0(world, eB)).toBeCloseTo(0.4, 5); // 0.5 x 0.8
+  });
+});

package/src/__tests__/animation-graph-serialize.unit.test.ts

@@ -0,0 +1,171 @@
+// feat-20260713-animation-state-machine-plugin M4 / w27 -- AnimationGraph
+// serialize -> deserialize pack round-trip (AC-14 part a).
+//
+// AC-14 (part a) metric: construct a nested graph -> serialize to a pack payload
+// -> deserialize (rebuild) and assert the graph topology (Clip/Blend/Add nodes +
+// child references), every node's static weight, the root, and every clip
+// reference are field-for-field equal to the original. Clip references round-trip
+// through the existing `refs` GUID mechanism (plan D-4): serialize rewrites each
+// clip leaf's `shared<AnimationClip>` handle to a GUID (indexed into `refs`), and
+// the loader resolves each `refs` index back to its GUID string (the same "GUID
+// verbatim at load, resolve to a handle at use time" contract materialLoader
+// uses, asset-registry D-19).
+//
+// TDD red anchor: before w29 (serializeAnimationGraph) + w30 (animationGraphLoader)
+// the two imports below do not resolve, so the file fails to compile. w29 lands
+// serialize (payload + refs); w30 lands the loader; the round-trip goes green
+// once both halves exist (a round-trip test spans both impl seams by nature).
+
+import { defineAnimationGraph, serializeAnimationGraph } from '@forgeax/engine-animation';
+import { AssetRegistry, animationGraphLoader } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { AnimationClip, AnimationGraph, Handle, LoadContext } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+// Register a clip payload under `guidStr` in BOTH the registry catalog (so
+// `_guidForAsset` resolves payload -> GUID) and the world's shared-ref store (so
+// `resolveAssetHandle` resolves handle -> payload). The SAME payload object is
+// used for both so the identity-based `_guidForAsset` scan matches.
+function registerClip(
+  world: World,
+  reg: AssetRegistry,
+  guidStr: string,
+  duration: number,
+): { handle: Handle<'AnimationClip', 'shared'>; guid: string } {
+  const parsed = AssetGuid.parse(guidStr);
+  if (!parsed.ok) throw new Error(`bad test GUID ${guidStr}`);
+  const clip: AnimationClip = { kind: 'animation-clip', duration, channels: [] };
+  reg.catalog(parsed.value, clip);
+  const handle = world.allocSharedRef('AnimationClip', clip) as Handle<'AnimationClip', 'shared'>;
+  return { handle, guid: AssetGuid.format(parsed.value) };
+}
+
+// Resolver used by serialize: clip handle -> catalogued GUID string, via the two
+// production seams (resolveAssetHandle on the world + _guidForAsset on the
+// registry). Mirrors how a scene-serialize caller resolves an asset handle.
+function makeClipGuidResolver() {
+  return (clip: string): string | undefined => clip;
+}
+
+const G1 = 'a1000000-0000-4000-8000-000000000001';
+const G2 = 'a1000000-0000-4000-8000-000000000002';
+const G3 = 'a1000000-0000-4000-8000-000000000003';
+
+// Minimal LoadContext stub -- the animation-graph loader is a pure payload/refs
+// transform and reads nothing off the context (no fetch / device / shader).
+const stubCtx = {} as LoadContext;
+
+describe('AnimationGraph serialize -> deserialize round-trip (M4 / w27, AC-14 part a)', () => {
+  it('serialize produces a pack payload with deduped refs of clip GUIDs', () => {
+    const world = new World();
+    const reg = makeRegistry();
+    const walk = registerClip(world, reg, G1, 10);
+    const run = registerClip(world, reg, G2, 20);
+
+    // overlay reuses the walk clip handle -> serialize must dedupe it to a
+    // single refs entry (mirrors material/scene refs dedup).
+    const built = defineAnimationGraph((b) => {
+      const w = b.clip(walk.guid);
+      const r = b.clip(run.guid);
+      const loco = b.blend([w, r]);
+      const overlay = b.clip(walk.guid, 0.3);
+      return b.add(loco, [overlay]);
+    });
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+
+    const out = serializeAnimationGraph(built.value, makeClipGuidResolver());
+    expect(out).not.toBeUndefined();
+    if (out === undefined) return;
+
+    // Two unique clip GUIDs despite three clip nodes (walk referenced twice).
+    expect([...out.refs].sort()).toEqual([walk.guid, run.guid].sort());
+    const payloadNodes = (out.payload.nodes as Array<Record<string, unknown>>) ?? [];
+    expect(payloadNodes).toHaveLength(5);
+    // Every clip node's `clip` in the payload is a refs index, not a handle.
+    for (const node of payloadNodes) {
+      if (node.type === 'clip') {
+        expect(typeof node.clip).toBe('number');
+        expect(node.clip as number).toBeGreaterThanOrEqual(0);
+        expect(node.clip as number).toBeLessThan(out.refs.length);
+      }
+    }
+  });
+
+  it('deserialize rebuilds the graph field-for-field equal to the original', () => {
+    const world = new World();
+    const reg = makeRegistry();
+    const walk = registerClip(world, reg, G1, 10);
+    const run = registerClip(world, reg, G2, 20);
+    const survey = registerClip(world, reg, G3, 30);
+
+    // Nested DAG: Add(base=Blend(survey@0.5, Blend(walk, run))@0.8, additive=[overlay@0.3]).
+    const built = defineAnimationGraph((b) => {
+      const w = b.clip(walk.guid);
+      const r = b.clip(run.guid);
+      const s = b.clip(survey.guid, 0.5);
+      const loco = b.blend([w, r]);
+      const base = b.blend([s, loco], 0.8);
+      const overlay = b.clip(survey.guid, 0.3);
+      return b.add(base, [overlay]);
+    });
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    const original = built.value;
+
+    const out = serializeAnimationGraph(original, makeClipGuidResolver());
+    expect(out).not.toBeUndefined();
+    if (out === undefined) return;
+
+    const parsed = animationGraphLoader.load(out.payload, out.refs, stubCtx);
+    expect(parsed).not.toBeUndefined();
+    if (parsed === undefined || typeof parsed !== 'object' || 'ok' in parsed) {
+      throw new Error('animationGraphLoader returned a non-asset result');
+    }
+    const rebuilt = parsed as AnimationGraph;
+
+    // kind + root + node count are structurally identical.
+    expect(rebuilt.kind).toBe('animation-graph');
+    expect(rebuilt.root).toBe(original.root);
+    expect(rebuilt.nodes).toHaveLength(original.nodes.length);
+
+    // Field-for-field per node: type, static weight, child references identical;
+    // clip references equal at the GUID level (the persistent form).
+    for (let i = 0; i < original.nodes.length; i++) {
+      const o = original.nodes[i];
+      const d = rebuilt.nodes[i];
+      if (o === undefined || d === undefined) throw new Error(`missing node ${i}`);
+      expect(d.type).toBe(o.type);
+      expect(d.weight).toBe(o.weight);
+      if (o.type === 'clip' && d.type === 'clip') {
+        expect(d.clip).toBe(o.clip);
+      } else if (o.type === 'blend' && d.type === 'blend') {
+        expect([...d.children]).toEqual([...o.children]);
+      } else if (o.type === 'add' && d.type === 'add') {
+        expect(d.base).toBe(o.base);
+        expect([...d.additive]).toEqual([...o.additive]);
+      }
+    }
+  });
+
+  it('deserialize rejects a malformed payload with undefined (asset-parse-failed upstream)', () => {
+    // clip node whose refs index is out of range -> loader returns undefined so
+    // the load-by-guid path surfaces the existing `asset-parse-failed` code.
+    const badPayload: Record<string, unknown> = {
+      nodes: [{ type: 'clip', clip: 5, weight: 1 }],
+      root: 0,
+    };
+    const parsed = animationGraphLoader.load(
+      badPayload,
+      ['a1000000-0000-4000-8000-000000000009'],
+      stubCtx,
+    );
+    expect(parsed).toBeUndefined();
+  });
+});

package/src/__tests__/animation-graph-slot-fill.unit.test.ts

@@ -0,0 +1,95 @@
+// feat-20260713-animation-state-machine-plugin M3 / w21 — DAG eval fills the
+// variable N-slot columns (AC-08).
+//
+// AC-08: post-order DAG evaluation spreads each Clip leaf's effective weight
+// into the variable-length weights[] / clips[] columns; a single eval frame is
+// then a valid input to advanceAnimationPlayer's N-way blend. This test drives a
+// 5-child Blend (proving the retired 4-slot cap is gone) and asserts the derived
+// slot distribution equals the expected normalized shares, that clips[] carry
+// the source handles in leaf order, and that the derived columns feed advance
+// without a length fault.
+//
+// TDD red anchor: before w24 + w25 the file fails to compile; after them the
+// slots read back at the expected distribution.
+
+import {
+  AnimationPlayer,
+  advanceAnimationPlayer,
+  defineAnimationGraph,
+  evaluateAnimationGraph,
+} from '@forgeax/engine-animation';
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function registerClip(world: World, duration: number): number {
+  const clip: AnimationClip = { kind: 'animation-clip', duration, channels: [] };
+  return world.allocSharedRef('AnimationClip', clip) as unknown as number;
+}
+
+const lookupClip = (_guid: string): AnimationClip => ({
+  kind: 'animation-clip',
+  duration: 10,
+  channels: [],
+});
+
+function asClipGuid(raw: number): string {
+  return `test/animation-clip-${raw}`;
+}
+
+interface Slots {
+  clips: Uint32Array;
+  times: Float32Array;
+  weights: Float32Array;
+  speeds: Float32Array;
+}
+
+function readSlots(world: World, e: EntityHandle): Slots {
+  return world.get(e, AnimationPlayer).unwrap() as unknown as Slots;
+}
+
+describe('evaluateAnimationGraph — variable N-slot fill (M3 / w21)', () => {
+  it('spreads a 5-child Blend into 5 slots at the expected distribution', () => {
+    const world = new World();
+    const handles = [0, 1, 2, 3, 4].map(() => registerClip(world, 10));
+
+    // Blend of FIVE equal-weight clips -> normalized 0.2 each; 5 > 4 proves the
+    // fixed 4-slot cap is retired.
+    const built = defineAnimationGraph((b) => {
+      const leaves = handles.map((h) => b.clip(asClipGuid(h)));
+      return b.blend(leaves);
+    });
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    const graphH = world.allocSharedRef('AnimationGraph', built.value);
+
+    const e = world
+      .spawn({ component: AnimationPlayer, data: { graph: graphH } })
+      .unwrap() as EntityHandle;
+
+    evaluateAnimationGraph(world, 0, lookupClip);
+
+    const ap = readSlots(world, e);
+    expect(ap.clips.length).toBe(5);
+    expect(ap.weights.length).toBe(5);
+    expect(ap.times.length).toBe(5);
+    expect(ap.speeds.length).toBe(5);
+
+    for (let i = 0; i < 5; i++) {
+      // clips[] carry the leaf handles in construction (leaf) order.
+      expect(ap.clips[i]).toBeGreaterThan(0);
+      // Each of five equal leaves gets a normalized 0.2 share.
+      expect(ap.weights[i]).toBeCloseTo(0.2, 5);
+      // Derived path parks speeds[]=0 (eval owns the seek-time, D-7).
+      expect(ap.speeds[i]).toBe(0);
+    }
+
+    // The derived slots normalize to exactly 1 (Blend semantics).
+    const total = Array.from(ap.weights).reduce((a, w) => a + w, 0);
+    expect(total).toBeCloseTo(1, 5);
+
+    // The eval output is a valid input to advance's N-way blend (length-synced).
+    expect(() => advanceAnimationPlayer(world, 1 / 60)).not.toThrow();
+  });
+});

package/src/__tests__/animation-nslot.unit.test.ts

@@ -0,0 +1,63 @@
+// feat-20260713-animation-state-machine-plugin M1 / w1 — variable N-slot lock.
+//
+// AC-01: AnimationPlayer.clips/times/weights/speeds drop the fixed 4-slot cap
+// and become variable `array<T>` columns. This test constructs an entity with
+// SIX concurrent slots, runs advanceAnimationPlayer for one frame, and asserts
+// the read-back arrays keep length 6 with no overflow / truncation / throw.
+//
+// TDD red anchor: before the schema migration (w4), `clips` is
+// `array<shared<AnimationClip>, 4>`; spawning a 6-element clips array trips the
+// ECS `FixedArrayOverflowError` and `.unwrap()` throws — the construction
+// itself fails. After w4 the variable schema accepts 6 slots and the frame
+// leaves all six weight columns intact.
+
+import { AnimationPlayer, advanceAnimationPlayer } from '@forgeax/engine-animation';
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function makeClip(duration: number): AnimationClip {
+  return { kind: 'animation-clip', duration, channels: [] };
+}
+
+describe('AnimationPlayer — variable N-slot (M1 / w1)', () => {
+  it('constructs and evaluates 6 concurrent slots without overflow / truncation', () => {
+    const world = new World();
+    const clips = Array.from({ length: 6 }, () =>
+      world.allocSharedRef('AnimationClip', makeClip(10)),
+    );
+    const e = world
+      .spawn({
+        component: AnimationPlayer,
+        data: {
+          clips,
+          times: new Float32Array([0, 0, 0, 0, 0, 0]),
+          weights: new Float32Array([0.1, 0.2, 0.3, 0.4, 0.5, 0.6]),
+          speeds: new Float32Array([1, 1, 1, 1, 1, 1]),
+        },
+      })
+      .unwrap() as EntityHandle;
+
+    expect(() => advanceAnimationPlayer(world, 0.5)).not.toThrow();
+
+    const ap = world.get(e, AnimationPlayer).unwrap() as unknown as {
+      clips: Uint32Array;
+      weights: Float32Array;
+    };
+    // No 4-slot truncation: all six slots survive one frame.
+    expect(ap.clips.length).toBe(6);
+    expect(ap.weights.length).toBe(6);
+    // advance never writes weights back (D-7); the six values read back verbatim.
+    expect(Array.from(ap.weights)).toEqual([
+      expect.closeTo(0.1, 5),
+      expect.closeTo(0.2, 5),
+      expect.closeTo(0.3, 5),
+      expect.closeTo(0.4, 5),
+      expect.closeTo(0.5, 5),
+      expect.closeTo(0.6, 5),
+    ]);
+    // The 6th clip handle is a real slot, not clamped away.
+    expect(ap.clips[5]).toBe(clips[5]);
+  });
+});

package/src/__tests__/animation-slot-length-guard.unit.test.ts

@@ -0,0 +1,81 @@
+// feat-20260713-animation-state-machine-plugin M1 / w2 — slot-length guard.
+//
+// AC-11 (parallel-array length-mismatch branch): the four AnimationPlayer SoA
+// columns (clips / times / weights / speeds) are variable `array<T>` columns
+// set field-by-field (release-then-alloc per field, D-5), so nothing at the ECS
+// layer cross-checks their lengths. A single evaluation-entry chokepoint in
+// advanceAnimationPlayer must reject a row whose four columns disagree in
+// length with a structured error `animation-player-slot-length-mismatch`
+// carrying `.code` + `.hint` — never silently zero-pad or truncate.
+//
+// TDD red anchor: before the schema migration (w4) the columns are fixed
+// `array<T, 4>`; a short write is tail-padded to length 4 so the four columns
+// are always equal-length and the guard cannot trip — advance never throws and
+// this test stays red. After w5 lands the entry guard the mismatch is caught.
+
+import { AnimationPlayer, advanceAnimationPlayer } from '@forgeax/engine-animation';
+import { World } from '@forgeax/engine-ecs';
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function makeClip(duration: number): AnimationClip {
+  return { kind: 'animation-clip', duration, channels: [] };
+}
+
+interface StructuredError {
+  code?: unknown;
+  hint?: unknown;
+}
+
+describe('AnimationPlayer — slot-length guard (M1 / w2)', () => {
+  it('rejects unequal parallel-array lengths with a structured error (no silent pad/truncate)', () => {
+    const world = new World();
+    const clipOne = world.allocSharedRef('AnimationClip', makeClip(10));
+    const clipTwo = world.allocSharedRef('AnimationClip', makeClip(10));
+
+    // clips/times/speeds carry two slots; weights carries only one — a
+    // consumer that forgot to keep the four columns length-synced.
+    world
+      .spawn({
+        component: AnimationPlayer,
+        data: {
+          clips: [clipOne, clipTwo],
+          times: new Float32Array([0, 0]),
+          weights: new Float32Array([1]),
+          speeds: new Float32Array([1, 1]),
+        },
+      })
+      .unwrap();
+
+    let caught: StructuredError | undefined;
+    try {
+      advanceAnimationPlayer(world, 0.5);
+    } catch (e) {
+      caught = e as StructuredError;
+    }
+
+    expect(caught).toBeDefined();
+    expect(caught?.code).toBe('animation-player-slot-length-mismatch');
+    expect(typeof caught?.hint).toBe('string');
+    expect((caught?.hint as string).length).toBeGreaterThan(0);
+  });
+
+  it('does not throw when the four columns are length-synced', () => {
+    const world = new World();
+    const clip = world.allocSharedRef('AnimationClip', makeClip(10));
+
+    world
+      .spawn({
+        component: AnimationPlayer,
+        data: {
+          clips: [clip],
+          times: new Float32Array([0]),
+          weights: new Float32Array([1]),
+          speeds: new Float32Array([1]),
+        },
+      })
+      .unwrap();
+
+    expect(() => advanceAnimationPlayer(world, 0.5)).not.toThrow();
+  });
+});