@forgeax/engine-runtime 0.1.2

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

@@ -0,0 +1,100 @@
+// feat-20260713-animation-state-machine-plugin M2 / w9 — legal graph build +
+// shared handle multi-entity rc (AC-02).
+//
+// AC-02: a legal Clip/Blend/Add/nested graph constructs without error via
+// defineAnimationGraph; the resulting POD is minted into a GUID-addressable
+// shared<AnimationGraph> handle; two entities share the SAME handle and the
+// SharedRefStore refcount retains/releases correctly as entities spawn/despawn
+// (multi-entity sharing). The evaluation system is NOT landed in M2 — this test
+// only exercises the data model + carrier (plan-strategy §7 M2 boundary).
+//
+// TDD red anchor: before w13 (types POD) + w14 (builder), the imports below do
+// not resolve and defineAnimationGraph does not exist — the file fails to
+// compile. After w13/w14 the legal graph constructs and the rc assertions pass.
+
+import { defineAnimationGraph } from '@forgeax/engine-animation';
+import { defineComponent, World } from '@forgeax/engine-ecs';
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+// A test-only component carrying a single shared<AnimationGraph> handle. M2 does
+// NOT extend AnimationPlayer with a graph field (that is M3 / w24), so this
+// minimal holder is the authentic ECS path for exercising the write-barrier
+// retain/release across multiple entities without touching the M2-frozen
+// AnimationPlayer schema.
+const GraphHolder = defineComponent('AnimationGraphHolderW9', {
+  graph: 'shared<AnimationGraph>',
+});
+
+function clipGuid(id: number) {
+  return `test/animation-clip-${id}`;
+}
+
+describe('AnimationGraph — legal build + multi-entity rc (M2 / w9)', () => {
+  it('constructs a nested Clip/Blend/Add graph without error', () => {
+    const walk = clipGuid(1);
+    const run = clipGuid(2);
+    const survey = clipGuid(3);
+    const overlay = clipGuid(4);
+
+    const result = defineAnimationGraph((b) => {
+      const walkNode = b.clip(walk);
+      const runNode = b.clip(run);
+      const surveyNode = b.clip(survey);
+      const loco = b.blend([walkNode, runNode]);
+      const base = b.blend([surveyNode, loco]);
+      const overlayNode = b.clip(overlay, 0.3);
+      return b.add(base, [overlayNode]);
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const graph = result.value;
+    expect(graph.kind).toBe('animation-graph');
+    // 4 clip nodes + 2 blend nodes + 1 add node = 7 nodes; root is the add.
+    expect(graph.nodes.length).toBe(7);
+    expect(graph.nodes[graph.root]?.type).toBe('add');
+  });
+
+  it('mints a GUID-addressable shared handle with rc=1 (alloc grant)', () => {
+    const world = new World();
+    const result = defineAnimationGraph((b) => b.clip(clipGuid(1)));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const handle = world.allocSharedRef('AnimationGraph', result.value);
+    expect(handle).toBeGreaterThan(0);
+    expect(world.sharedRefs.refcount(handle)).toBe(1);
+  });
+
+  it('shares one handle across two entities; rc tracks retain/release', () => {
+    const world = new World();
+    const clipMap = new Map<number, AnimationClip>();
+    clipMap.set(1, { kind: 'animation-clip', duration: 10, channels: [] });
+
+    const result = defineAnimationGraph((b) => {
+      const a = b.clip(clipGuid(1));
+      const c = b.clip(clipGuid(1));
+      return b.blend([a, c]);
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const handle = world.allocSharedRef('AnimationGraph', result.value);
+    // alloc grant = 1.
+    expect(world.sharedRefs.refcount(handle)).toBe(1);
+
+    // Two entities hold the SAME handle — each spawn retains via the write
+    // barrier, so rc climbs to 3 (1 grant + 2 holders).
+    const e0 = world.spawn({ component: GraphHolder, data: { graph: handle } }).unwrap();
+    const e1 = world.spawn({ component: GraphHolder, data: { graph: handle } }).unwrap();
+    expect(world.sharedRefs.refcount(handle)).toBe(3);
+
+    // Despawning one holder releases exactly one ref (independent per entity).
+    world.despawn(e0).unwrap();
+    expect(world.sharedRefs.refcount(handle)).toBe(2);
+
+    world.despawn(e1).unwrap();
+    expect(world.sharedRefs.refcount(handle)).toBe(1);
+  });
+});

package/src/__tests__/animation-graph-clip-missing.unit.test.ts

@@ -0,0 +1,62 @@
+// feat-20260713-animation-state-machine-plugin M3 / w22 — clip-missing
+// structured error (AC-11).
+//
+// AC-11 (clip-missing branch): when a graph node references a shared<AnimationClip>
+// whose handle does not resolve (never registered, or rc released), evaluation
+// fails with a structured `animation-graph-clip-missing` error carrying a
+// machine-readable `.code` / `.hint` — and it must NOT leave a dirty pose (the
+// derived slot columns stay untouched). AI users self-repair by property access,
+// not string parsing (charter P3).
+//
+// TDD red anchor: before w24 + w25 the file fails to compile; after them a
+// dangling clip handle throws the structured error before any slot is written.
+
+import {
+  AnimationPlayer,
+  defineAnimationGraph,
+  evaluateAnimationGraph,
+} from '@forgeax/engine-animation';
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+
+interface StructuredError {
+  code?: unknown;
+  hint?: unknown;
+}
+
+describe('evaluateAnimationGraph — clip-missing structured error (M3 / w22)', () => {
+  it('throws animation-asset-not-found and writes no dirty pose', () => {
+    const world = new World();
+
+    // A durable clip GUID that was never loaded. Construction only validates
+    // topology, so a single-clip graph with a dangling GUID is a
+    // well-formed DAG that fails at evaluation, not at build.
+    const danglingClip = 'test/dangling-animation-clip';
+    const built = defineAnimationGraph((b) => b.clip(danglingClip));
+    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;
+
+    let caught: StructuredError | undefined;
+    try {
+      evaluateAnimationGraph(world, 0);
+    } catch (err) {
+      caught = err as StructuredError;
+    }
+
+    expect(caught).toBeDefined();
+    expect(caught?.code).toBe('animation-asset-not-found');
+    expect(typeof caught?.hint).toBe('string');
+    expect((caught?.hint as string).length).toBeGreaterThan(0);
+
+    // No dirty pose: eval resolves every clip BEFORE writing, so the derived
+    // slot columns were never touched (still empty from the spawn default).
+    const ap = world.get(e, AnimationPlayer).unwrap() as unknown as { weights: Float32Array };
+    expect(ap.weights.length).toBe(0);
+  });
+});

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

@@ -0,0 +1,77 @@
+// feat-20260713-animation-state-machine-plugin M3 / w16 — Clip node sampling
+// (AC-03).
+//
+// AC-03: a single-Clip graph samples its shared<AnimationClip> at the node's
+// seek-time and evaluation outputs ONE slot carrying that clip at full effective
+// weight (runtime weight x static weight = 1 x 1 = 1). evaluateAnimationGraph
+// fills the AnimationPlayer's derived N-slot columns; the slot fill (clip handle
+// + effective weight + resolved time) is the machine-checkable evidence of the
+// Clip node semantics (downstream advanceAnimationPlayer does the actual pose
+// blend, covered by animation-nslot.unit.test.ts).
+//
+// TDD red anchor: before w24 (AnimationPlayer.graph field) + w25
+// (evaluateAnimationGraph), the imports below do not resolve and the file fails
+// to compile. After w24/w25 the single-clip graph fills one slot at weight 1.
+
+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: [],
+});
+
+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 — Clip node sampling (M3 / w16)', () => {
+  it('fills one slot at full effective weight for a single-Clip graph', () => {
+    const world = new World();
+    registerClip(world, 10);
+
+    const built = defineAnimationGraph((b) => b.clip('test/animation-clip-single'));
+    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);
+    // Exactly one clip node -> one derived slot.
+    expect(ap.clips.length).toBe(1);
+    expect(ap.weights.length).toBe(1);
+    expect(ap.times.length).toBe(1);
+    expect(ap.speeds.length).toBe(1);
+    // The slot carries the clip handle at full effective weight (1 x 1 = 1).
+    expect(ap.clips[0]).toBeGreaterThan(0);
+    expect(ap.weights[0]).toBeCloseTo(1, 5);
+    // Derived path writes speeds[]=0 so advance does not re-advance the time
+    // (D-7: eval owns the seek-time, advance must not double-drive it).
+    expect(ap.speeds[0]).toBe(0);
+  });
+});

package/src/__tests__/animation-graph-default-path.integration.test.ts

@@ -0,0 +1,65 @@
+// feat-20260713-animation-state-machine-plugin M3 / w23 — default-path eval
+// integration (AC-09).
+//
+// AC-09: DAG evaluation is wired into the DEFAULT animationPlugin (not an opt-in
+// plugin). A host that lists the default animation capability gets automatic
+// per-frame evaluation for free: spawn an entity carrying an AnimationGraph
+// handle, drive a single world.update(), and read back the derived weights[] —
+// no manual evaluateAnimationGraph() call anywhere. This mirrors the assemble
+// form of createApp (a host-owned World running the default plugin set), the
+// harshest headless surface of the "default plugin set" contract, matching the
+// animationPlugin self-owns-resolver regression's approach.
+//
+// TDD red anchor: before w24 + w25 + w26 (plugin registers eval) the graph
+// carrier never gets evaluated, so weights[] stays empty; after them the default
+// plugin fills it automatically.
+
+import { AnimationPlayer, animationPlugin, defineAnimationGraph } from '@forgeax/engine-animation';
+import { createWorldContext, type EntityHandle, 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);
+}
+
+describe('DAG eval — default animationPlugin path (M3 / w23, AC-09)', () => {
+  it('auto-evaluates a graph carrier on world.update() with no opt-in', async () => {
+    const world = new World();
+
+    // Build the DEFAULT animation capability onto a bare host World (assemble
+    // form) — this is exactly what createApp's default plugin set does for the
+    // animation subsystem.
+    // Declare a normalizing Blend(Walk@1, Run@1) graph and register it + its
+    // clips as ordinary payloads retained by the host-owned lookup.
+    const clips = new Map<string, AnimationClip>([
+      ['test/animation-clip-walk', { kind: 'animation-clip', duration: 10, channels: [] }],
+      ['test/animation-clip-run', { kind: 'animation-clip', duration: 10, channels: [] }],
+    ]);
+    registerClip(world, 10);
+    registerClip(world, 10);
+    await createWorldContext(world, [animationPlugin((guid) => clips.get(guid))]);
+    const built = defineAnimationGraph((b) =>
+      b.blend([b.clip('test/animation-clip-walk'), b.clip('test/animation-clip-run')]),
+    );
+    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;
+
+    // Drive ONE frame through the default schedule. No manual eval call.
+    world.update();
+    expect(world.execution.health).toBe('healthy');
+
+    // The default plugin's evaluateAnimationGraph ran before advance and filled
+    // the derived weights[] with the normalized [0.5, 0.5] distribution.
+    const ap = world.get(e, AnimationPlayer).unwrap() as unknown as { weights: Float32Array };
+    expect(ap.weights.length).toBe(2);
+    expect(ap.weights[0]).toBeCloseTo(0.5, 5);
+    expect(ap.weights[1]).toBeCloseTo(0.5, 5);
+  });
+});

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

@@ -0,0 +1,68 @@
+// feat-20260713-animation-state-machine-plugin M2 / w11 — describeAnimationGraph
+// machine-readable introspection (AC-12).
+//
+// AC-12 + plan §8.4: describeAnimationGraph(g) enumerates the graph's nodes,
+// topology (per-node children), root, and per-node static weights so an AI user
+// discovers the graph structure WITHOUT reading implementation source (mirrors
+// the getRegisteredComponents reflection idiom, research Finding H). The
+// returned set must match the declared graph item-for-item.
+//
+// TDD red anchor: describeAnimationGraph does not exist before w15; the file
+// fails to compile. After w15 the introspection matches the declaration.
+
+import { defineAnimationGraph, describeAnimationGraph } from '@forgeax/engine-animation';
+import { describe, expect, it } from 'vitest';
+
+function clipGuid(id: number) {
+  return `test/animation-clip-${id}`;
+}
+
+describe('describeAnimationGraph — introspection (M2 / w11)', () => {
+  it('enumerates nodes, root, and static weights matching the declaration', () => {
+    const result = defineAnimationGraph((b) => {
+      const walk = b.clip(clipGuid(1), 1);
+      const run = b.clip(clipGuid(2), 1);
+      const loco = b.blend([walk, run], 0.4);
+      const overlay = b.clip(clipGuid(3), 0.3);
+      return b.add(loco, [overlay], 1);
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const desc = describeAnimationGraph(result.value);
+
+    // 3 clips + 1 blend + 1 add = 5 nodes; root is the add (index 4).
+    // Enumeration is CONSTRUCTION order (verbatim builder order), which is the
+    // same index space as the runtime AnimationPlayer.nodeWeights knobs — so an
+    // AI driving by desc.index writes the correct slot (V-1 fix: no reordering).
+    // Construction order: walk(0) run(1) loco/blend(2) overlay(3) add/root(4).
+    expect(desc.nodes.length).toBe(5);
+    expect(desc.root).toBe(4);
+
+    // Per-node type enumeration, construction order.
+    expect(desc.nodes.map((n) => n.type)).toEqual(['clip', 'clip', 'blend', 'clip', 'add']);
+
+    // Static weights read back item-for-item as declared, construction order.
+    expect(desc.staticWeights).toEqual([1, 1, 0.4, 0.3, 1]);
+    expect(desc.nodes.map((n) => n.weight)).toEqual([1, 1, 0.4, 0.3, 1]);
+
+    // desc.index equals the construction position for every node (== nodeWeights slot).
+    expect(desc.nodes.map((n) => n.index)).toEqual([0, 1, 2, 3, 4]);
+
+    // Topology: clips have no children; blend(2) lists its leaves [walk, run];
+    // add(4) lists [base=loco, ...additive=overlay].
+    expect(desc.nodes[0]?.children).toEqual([]);
+    expect(desc.nodes[2]?.children).toEqual([0, 1]);
+    expect(desc.nodes[4]?.children).toEqual([2, 3]);
+  });
+
+  it('exposes node index on each description entry', () => {
+    const result = defineAnimationGraph((b) => b.clip(clipGuid(1)));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const desc = describeAnimationGraph(result.value);
+    expect(desc.nodes[0]?.index).toBe(0);
+    expect(desc.root).toBe(0);
+  });
+});

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

@@ -0,0 +1,75 @@
+// feat-20260713-animation-state-machine-plugin M2 / w10 — illegal graph
+// construction structured errors (AC-11 graph-structure branches).
+//
+// AC-11 + plan D-5: defineAnimationGraph validates topology at CONSTRUCTION time
+// (before a GUID handle is minted) and returns Result.err with a structured
+// `.code` / `.hint` for each illegal shape:
+//   - node reference out of range  -> 'animation-graph-node-out-of-range'
+//   - cycle                        -> 'animation-graph-cycle'
+//   - node weight negative / NaN   -> 'animation-graph-node-weight-invalid'
+//   - empty graph                  -> 'animation-graph-empty'
+// AI users self-repair by property access — no string parsing (charter P3).
+//
+// TDD red anchor: defineAnimationGraph does not exist before w14; the file fails
+// to compile. After w14 each illegal graph returns the matching structured code.
+
+import { type AnimationGraphNodeRef, defineAnimationGraph } from '@forgeax/engine-animation';
+import { describe, expect, it } from 'vitest';
+
+function clipGuid(id: number) {
+  return `test/animation-clip-${id}`;
+}
+
+// Cast a raw index to a node ref — the illegal-graph tests deliberately forge
+// out-of-range / self-referential refs the well-behaved builder never emits.
+function forgeRef(index: number): AnimationGraphNodeRef {
+  return index as unknown as AnimationGraphNodeRef;
+}
+
+describe('AnimationGraph — illegal construction errors (M2 / w10)', () => {
+  it('empty graph -> animation-graph-empty', () => {
+    // The builder creates zero nodes; the returned root ref points nowhere.
+    const result = defineAnimationGraph(() => forgeRef(0));
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('animation-graph-empty');
+    expect(typeof result.error.hint).toBe('string');
+    expect(result.error.hint.length).toBeGreaterThan(0);
+  });
+
+  it('out-of-range child reference -> animation-graph-node-out-of-range', () => {
+    const result = defineAnimationGraph((b) => {
+      b.clip(clipGuid(1)); // node 0
+      // A blend that references index 99 (nonexistent).
+      return b.blend([forgeRef(99)]);
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('animation-graph-node-out-of-range');
+    expect(result.error.hint.length).toBeGreaterThan(0);
+  });
+
+  it('cycle -> animation-graph-cycle', () => {
+    // node 0 is a blend that references itself (index 0).
+    const result = defineAnimationGraph((b) => b.blend([forgeRef(0)]));
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('animation-graph-cycle');
+    expect(result.error.hint.length).toBeGreaterThan(0);
+  });
+
+  it('negative node weight -> animation-graph-node-weight-invalid', () => {
+    const result = defineAnimationGraph((b) => b.clip(clipGuid(1), -0.5));
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('animation-graph-node-weight-invalid');
+    expect(result.error.hint.length).toBeGreaterThan(0);
+  });
+
+  it('NaN node weight -> animation-graph-node-weight-invalid', () => {
+    const result = defineAnimationGraph((b) => b.clip(clipGuid(1), Number.NaN));
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('animation-graph-node-weight-invalid');
+  });
+});

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
+  });
+});