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

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

@@ -0,0 +1,237 @@
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { createWorldContext, World } from '@forgeax/engine-ecs';
+import { Transform } from '@forgeax/engine-scene';
+import type { AnimationClip, AnimationTargetIdValue, Handle } from '@forgeax/engine-types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { subscribeAnimationDiagnostics } from '../animation-diagnostic';
+import { AnimationPlayer } from '../animation-player';
+import { AnimatedBy, AnimationTargetId, AnimationTargets } from '../animation-target';
+import { animationPlugin } from '../plugin';
+import { _resetAnimationWarnsForTests } from '../systems/advance-animation-player';
+
+const TARGET_ID = 'a95da0ec669189f98273e8f86d8ad9f2' as AnimationTargetIdValue;
+
+function clip(targetId = TARGET_ID): AnimationClip {
+  return {
+    kind: 'animation-clip',
+    duration: 1,
+    channels: [
+      {
+        targetId,
+        property: 'translation',
+        sampler: {
+          input: new Float32Array([0, 1]),
+          output: new Float32Array([0, 0, 0, 1, 1, 1]),
+          interpolation: 'LINEAR',
+        },
+      },
+    ],
+  };
+}
+
+async function playerWithClip(world: World, animationClip = clip()): Promise<EntityHandle> {
+  await createWorldContext(world, [animationPlugin()]);
+  const handle = world.allocSharedRef('AnimationClip', animationClip);
+  return world
+    .spawn({
+      component: AnimationPlayer,
+      data: { clips: [handle], times: [0], weights: [1], speeds: [1] },
+    })
+    .unwrap() as EntityHandle;
+}
+
+function diagnostics(spy: ReturnType<typeof vi.spyOn>) {
+  return spy.mock.calls.map((call: unknown[]) => call[0]);
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('animation runtime diagnostics', () => {
+  it('projects unique channels to subscribers while preserving per-channel console facts', async () => {
+    const world = new World();
+    const singleChannel = clip();
+    const firstChannel = singleChannel.channels[0];
+    if (firstChannel === undefined) throw new Error('fixture requires one animation channel');
+    const twoChannels: AnimationClip = {
+      ...singleChannel,
+      channels: [...singleChannel.channels, { ...firstChannel, property: 'rotation' }],
+    };
+    const player = await playerWithClip(world, twoChannels);
+    const observed: unknown[] = [];
+    const unsubscribe = subscribeAnimationDiagnostics((source, diagnostic) => {
+      if (source === world) observed.push(diagnostic);
+    });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+    world.update(0.25);
+    world.update(0.25);
+    unsubscribe();
+
+    expect(warn).toHaveBeenCalledTimes(2);
+    expect(observed).toHaveLength(2);
+    expect(observed).toEqual([
+      expect.objectContaining({
+        detail: expect.objectContaining({
+          player: player as number,
+          channel: 0,
+          targetId: TARGET_ID,
+        }),
+      }),
+      expect.objectContaining({
+        detail: expect.objectContaining({
+          player: player as number,
+          channel: 1,
+          targetId: TARGET_ID,
+        }),
+      }),
+    ]);
+  });
+
+  it('emits a readonly structured missing-target diagnostic once per full tuple and World', async () => {
+    const first = new World();
+    const second = new World();
+    const firstPlayer = await playerWithClip(first);
+    await playerWithClip(second);
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+    first.update(0.25);
+    first.update(0.25);
+    second.update(0.25);
+
+    expect(diagnostics(warn)).toHaveLength(2);
+    expect(diagnostics(warn)[0]).toEqual({
+      code: 'animation-target-missing',
+      hint: expect.any(String),
+      detail: {
+        player: firstPlayer as number,
+        clip: expect.any(Number),
+        channel: 0,
+        targetId: TARGET_ID,
+        reason: 'target-missing',
+      },
+    });
+    expect(Object.isFrozen(diagnostics(warn)[0])).toBe(true);
+
+    _resetAnimationWarnsForTests(first);
+    first.update(0.25);
+    expect(diagnostics(warn)).toHaveLength(3);
+  });
+
+  it('reuses stable target bindings until relationship inputs change', async () => {
+    const world = new World();
+    const player = await playerWithClip(world);
+    const target = world.spawn({ component: Transform, data: {} }).unwrap() as EntityHandle;
+    world
+      .addComponent(target, { component: AnimationTargetId, data: { value: TARGET_ID } })
+      .unwrap();
+    world.addComponent(target, { component: AnimatedBy, data: { player } }).unwrap();
+    const get = vi.spyOn(world, 'get');
+
+    world.update(0.25);
+    const bindingReadsAfterFirstUpdate = get.mock.calls.filter(
+      ([, component]) => component === AnimationTargets || component === AnimationTargetId,
+    ).length;
+    world.update(0.25);
+    const bindingReadsAfterStableUpdate = get.mock.calls.filter(
+      ([, component]) => component === AnimationTargets || component === AnimationTargetId,
+    ).length;
+
+    expect(bindingReadsAfterFirstUpdate).toBeGreaterThan(0);
+    expect(bindingReadsAfterStableUpdate).toBe(bindingReadsAfterFirstUpdate);
+
+    world.removeComponent(target, Transform).unwrap();
+    world.update(0.25);
+    const bindingReadsAfterStructuralChange = get.mock.calls.filter(
+      ([, component]) => component === AnimationTargets || component === AnimationTargetId,
+    ).length;
+    expect(bindingReadsAfterStructuralChange).toBe(bindingReadsAfterStableUpdate);
+
+    world.addComponent(target, { component: Transform, data: {} }).unwrap();
+    world.set(target, AnimationTargetId, { value: 'b'.repeat(32) }).unwrap();
+    world.update(0.25);
+    const bindingReadsAfterIdChange = get.mock.calls.filter(
+      ([, component]) => component === AnimationTargets || component === AnimationTargetId,
+    ).length;
+    expect(bindingReadsAfterIdChange).toBeGreaterThan(bindingReadsAfterStructuralChange);
+  });
+
+  it('emits structured diagnostics for missing Transform, duplicate IDs, and missing channels', async () => {
+    const world = new World();
+    const player = await playerWithClip(world);
+    const target = world.spawn({ component: Transform, data: {} }).unwrap() as EntityHandle;
+    world
+      .addComponent(target, { component: AnimationTargetId, data: { value: TARGET_ID } })
+      .unwrap();
+    world.addComponent(target, { component: AnimatedBy, data: { player } }).unwrap();
+    world.removeComponent(target, Transform).unwrap();
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+    world.update(0.25);
+
+    expect(diagnostics(warn)).toContainEqual(
+      expect.objectContaining({
+        code: 'animation-target-transform-missing',
+        detail: expect.objectContaining({ reason: 'transform-missing', targetId: TARGET_ID }),
+      }),
+    );
+
+    world.addComponent(target, { component: Transform, data: {} }).unwrap();
+    const duplicate = world.spawn({ component: Transform, data: {} }).unwrap() as EntityHandle;
+    world
+      .addComponent(duplicate, { component: AnimationTargetId, data: { value: TARGET_ID } })
+      .unwrap();
+    world.addComponent(duplicate, { component: AnimatedBy, data: { player } }).unwrap();
+    world.update(0.25);
+    expect(diagnostics(warn)).toContainEqual(
+      expect.objectContaining({
+        code: 'animation-target-id-duplicate',
+        detail: expect.objectContaining({ reason: 'target-id-duplicate', targetId: TARGET_ID }),
+      }),
+    );
+
+    world.despawn(duplicate).unwrap();
+    world.update(0.25);
+
+    const secondClip: AnimationClip = { kind: 'animation-clip', duration: 1, channels: [] };
+    const secondHandle = world.allocSharedRef('AnimationClip', secondClip);
+    world.set(player, AnimationPlayer, {
+      clips: [
+        world.get(player, AnimationPlayer).unwrap().clips[0] as unknown as Handle<
+          'AnimationClip',
+          'shared'
+        >,
+        secondHandle,
+      ],
+      times: [0, 0],
+      weights: [1, 1],
+      speeds: [1, 1],
+    });
+    world.update(0.25);
+    expect(diagnostics(warn)).toContainEqual(
+      expect.objectContaining({
+        code: 'animation-channel-missing',
+        detail: expect.objectContaining({ reason: 'channel-missing', targetId: TARGET_ID }),
+      }),
+    );
+  });
+
+  it('emits no diagnostic in production', async () => {
+    const proc = globalThis as { process?: { env: { NODE_ENV?: string } } };
+    const saved = proc.process?.env.NODE_ENV;
+    if (proc.process !== undefined) proc.process.env.NODE_ENV = 'production';
+    try {
+      const world = new World();
+      await playerWithClip(world);
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+      world.update(0.25);
+      expect(warn).not.toHaveBeenCalled();
+    } finally {
+      if (proc.process !== undefined) {
+        if (saved === undefined) delete proc.process.env.NODE_ENV;
+        else proc.process.env.NODE_ENV = saved;
+      }
+    }
+  });
+});

package/src/__tests__/animation-recovery.integration.test.ts

@@ -0,0 +1,125 @@
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { createWorldContext, World } from '@forgeax/engine-ecs';
+import { ChildOf, Name, scenePlugin, Transform } from '@forgeax/engine-scene';
+import type { AnimationClip, AnimationTargetIdValue } from '@forgeax/engine-types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { subscribeAnimationDiagnostics } from '../animation-diagnostic';
+import { AnimationPlayer } from '../animation-player';
+import { AnimationTargetId, bindAnimationTargets } from '../animation-target';
+import { animationPlugin } from '../plugin';
+
+const TARGET_ID = 'a95da0ec669189f98273e8f86d8ad9f2' as AnimationTargetIdValue;
+const INVALID_TARGET_ID = 'f'.repeat(32) as AnimationTargetIdValue;
+
+function clip(): AnimationClip {
+  return {
+    kind: 'animation-clip',
+    duration: 1,
+    channels: [
+      {
+        targetId: TARGET_ID,
+        property: 'translation',
+        sampler: {
+          input: new Float32Array([0, 1]),
+          output: new Float32Array([0, 0, 0, 4, 0, 0]),
+          interpolation: 'LINEAR',
+        },
+      },
+    ],
+  };
+}
+
+async function spawnAnimatedPair(world: World): Promise<{
+  brokenPlayer: EntityHandle;
+  brokenTarget: EntityHandle;
+  healthyTarget: EntityHandle;
+}> {
+  const handle = world.allocSharedRef('AnimationClip', clip());
+  const spawn = (name: string) => {
+    const player = world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: Name, data: { value: name } },
+        {
+          component: AnimationPlayer,
+          data: { clips: [handle], times: [0], weights: [1], speeds: [1] },
+        },
+      )
+      .unwrap() as EntityHandle;
+    const target = world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: Name, data: { value: 'Joint' } },
+        { component: ChildOf, data: { parent: player } },
+        { component: AnimationTargetId, data: { value: TARGET_ID } },
+      )
+      .unwrap() as EntityHandle;
+    expect(bindAnimationTargets(world, player, [target]).ok).toBe(true);
+    return { player, target };
+  };
+
+  const broken = spawn('Broken');
+  const healthy = spawn('Healthy');
+  return {
+    brokenPlayer: broken.player,
+    brokenTarget: broken.target,
+    healthyTarget: healthy.target,
+  };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function positionX(world: World, entity: EntityHandle): number {
+  return world.get(entity, Transform).unwrap().pos[0] ?? 0;
+}
+
+describe('same-world animation binding recovery', () => {
+  it('keeps healthy siblings alive and repairs a missing target binding without rebuilding the world', async () => {
+    const world = new World();
+    await createWorldContext(world, [scenePlugin()]);
+    await createWorldContext(world, [animationPlugin()]);
+    const { brokenPlayer, brokenTarget, healthyTarget } = await spawnAnimatedPair(world);
+    const diagnostics: unknown[] = [];
+    const unsubscribe = subscribeAnimationDiagnostics((source, diagnostic) => {
+      if (source === world) diagnostics.push(diagnostic);
+    });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+    world.update(0.2);
+    const healthyBeforeFault = positionX(world, healthyTarget);
+    const brokenBeforeFault = positionX(world, brokenTarget);
+
+    world.set(brokenTarget, AnimationTargetId, { value: INVALID_TARGET_ID }).unwrap();
+    world.update(0.2);
+
+    const healthyDuringFault = positionX(world, healthyTarget);
+    const brokenDuringFault = positionX(world, brokenTarget);
+    expect(healthyDuringFault).toBeGreaterThan(healthyBeforeFault);
+    expect(brokenDuringFault).toBeCloseTo(brokenBeforeFault);
+    expect(diagnostics).toContainEqual(
+      expect.objectContaining({
+        code: 'animation-target-missing',
+        detail: expect.objectContaining({
+          player: brokenPlayer as number,
+          targetId: TARGET_ID,
+          reason: 'target-missing',
+        }),
+      }),
+    );
+
+    const diagnosticCountAtFault = diagnostics.length;
+    world.set(brokenTarget, AnimationTargetId, { value: TARGET_ID }).unwrap();
+    world.update(0.2);
+
+    const brokenAfterRepair = positionX(world, brokenTarget);
+    expect(brokenAfterRepair).toBeGreaterThan(brokenDuringFault);
+    expect(diagnostics).toHaveLength(diagnosticCountAtFault);
+    expect(warn).toHaveBeenCalledTimes(diagnosticCountAtFault);
+
+    unsubscribe();
+    unsubscribe();
+    expect(world.despawn(brokenPlayer).ok).toBe(true);
+  });
+});

package/src/__tests__/animation-target-id.browser.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { deriveAnimationTargetId, isAnimationTargetId } from '../target-id';
+
+const VECTORS = [
+  [['Root', 'Hip'], 'a95da0ec669189f98273e8f86d8ad9f2'],
+  [['ab'], 'f9435481ae45880387567b7a1b26b41c'],
+  [['a', 'b'], '2a4725924b1c84a5adf2f7933aa10c63'],
+  [['Root', 'A/B'], '72262f23f7148acaaf24c50e22924ca7'],
+  [['\u6839', '\u9aa8'], '06749e3fb5a88f3a8945fb13c1d7a6b1'],
+] as const;
+
+describe('animation target id browser vectors', () => {
+  it.each(VECTORS)('derives %j', (path, expected) => {
+    const actual = deriveAnimationTargetId(path);
+    expect(actual).toBe(expected);
+    expect(isAnimationTargetId(actual)).toBe(true);
+  });
+
+  it('preserves segment boundaries in the browser', () => {
+    expect(deriveAnimationTargetId(['ab'])).not.toBe(deriveAnimationTargetId(['a', 'b']));
+  });
+});

package/src/__tests__/animation-target-id.unit.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { deriveAnimationTargetId, isAnimationTargetId } from '../target-id';
+
+const VECTORS = [
+  [['Root', 'Hip'], 'a95da0ec669189f98273e8f86d8ad9f2'],
+  [['ab'], 'f9435481ae45880387567b7a1b26b41c'],
+  [['a', 'b'], '2a4725924b1c84a5adf2f7933aa10c63'],
+  [['Root', 'A/B'], '72262f23f7148acaaf24c50e22924ca7'],
+  [['\u6839', '\u9aa8'], '06749e3fb5a88f3a8945fb13c1d7a6b1'],
+] as const;
+
+describe('animation target id', () => {
+  it.each(VECTORS)('derives %j', (path, expected) => {
+    const actual = deriveAnimationTargetId(path);
+    expect(actual).toBe(expected);
+    expect(actual[12]).toBe('8');
+    expect(Number.parseInt(actual[16] ?? '', 16) & 0xc).toBe(0x8);
+  });
+
+  it('preserves segment, slash, and UTF-8 boundaries', () => {
+    expect(deriveAnimationTargetId(['ab'])).not.toBe(deriveAnimationTargetId(['a', 'b']));
+    expect(deriveAnimationTargetId(['Root', 'A/B'])).not.toBe(
+      deriveAnimationTargetId(['Root', 'A', 'B']),
+    );
+    expect(deriveAnimationTargetId(['\u6839', '\u9aa8'])).toBe(VECTORS[4][1]);
+  });
+
+  it.each([
+    '',
+    'a'.repeat(31),
+    'a'.repeat(33),
+    'A95da0ec669159f98273e8f86d8ad9f',
+    'g95da0ec669159f98273e8f86d8ad9f',
+  ])('rejects invalid wire %j', (wire) => {
+    expect(isAnimationTargetId(wire)).toBe(false);
+  });
+
+  it('accepts a 32-character lowercase hexadecimal wire', () => {
+    expect(isAnimationTargetId(VECTORS[0][1])).toBe(true);
+  });
+});

package/src/__tests__/animation-target-isolation.integration.test.ts

@@ -0,0 +1,179 @@
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { createWorldContext, Entity, World } from '@forgeax/engine-ecs';
+import { ChildOf, scenePlugin, Transform } from '@forgeax/engine-scene';
+import type { AnimationClip, AnimationTargetIdValue, Handle } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { AnimationPlayer } from '../animation-player';
+import {
+  AnimatedBy,
+  AnimationTargetId,
+  AnimationTargets,
+  bindAnimationTargets,
+} from '../animation-target';
+import { animationPlugin } from '../plugin';
+
+const TARGET_ID = 'a95da0ec669189f98273e8f86d8ad9f2' as AnimationTargetIdValue;
+
+function clip(targetId = TARGET_ID): AnimationClip {
+  return {
+    kind: 'animation-clip',
+    duration: 1,
+    channels: [
+      {
+        targetId,
+        property: 'translation',
+        sampler: {
+          input: new Float32Array([0, 1]),
+          output: new Float32Array([0, 0, 0, 10, 0, 0]),
+          interpolation: 'LINEAR',
+        },
+      },
+    ],
+  };
+}
+
+async function spawnPair(world: World, clipHandle: Handle<'AnimationClip', 'shared'>) {
+  const player = world
+    .spawn({
+      component: Transform,
+      data: {},
+    })
+    .unwrap() as EntityHandle;
+  world
+    .addComponent(player, {
+      component: AnimationPlayer,
+      data: { clips: [clipHandle], times: [0], weights: [1], speeds: [1], looping: false },
+    })
+    .unwrap();
+  const target = world.spawn({ component: Transform, data: {} }).unwrap() as EntityHandle;
+  world.addComponent(target, { component: ChildOf, data: { parent: player } }).unwrap();
+  world.addComponent(target, { component: AnimationTargetId, data: { value: TARGET_ID } }).unwrap();
+  expect(bindAnimationTargets(world, player, [target]).ok).toBe(true);
+  return { player, target };
+}
+
+describe('animation target isolation and lifecycle', () => {
+  it('skips five malformed targets or channels while a valid sibling player continues', async () => {
+    const world = new World();
+    await createWorldContext(world, [animationPlugin()]);
+    const clipHandle = world.allocSharedRef('AnimationClip', clip());
+    const valid = await spawnPair(world, clipHandle);
+
+    await spawnPair(
+      world,
+      world.allocSharedRef('AnimationClip', clip('00000000000000000000000000000000' as never)),
+    );
+
+    const noTransform = await spawnPair(world, clipHandle);
+    world.removeComponent(noTransform.target, Transform).unwrap();
+
+    const duplicate = await spawnPair(world, clipHandle);
+    const duplicateTarget = world
+      .spawn({ component: Transform, data: {} })
+      .unwrap() as EntityHandle;
+    world
+      .addComponent(duplicateTarget, { component: AnimationTargetId, data: { value: TARGET_ID } })
+      .unwrap();
+    world
+      .addComponent(duplicateTarget, { component: AnimatedBy, data: { player: duplicate.player } })
+      .unwrap();
+
+    const stale = await spawnPair(world, clipHandle);
+    const staleRaw = stale.target;
+    world.despawn(staleRaw).unwrap();
+
+    const emptyClip = world.allocSharedRef('AnimationClip', {
+      kind: 'animation-clip',
+      duration: 1,
+      channels: [],
+    } satisfies AnimationClip);
+    const missingChannel = await spawnPair(world, clipHandle);
+    world.set(missingChannel.player, AnimationPlayer, {
+      clips: [clipHandle, emptyClip],
+      times: [0, 0],
+      weights: [1, 1],
+      speeds: [1, 1],
+    });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+    world.update(0.1);
+
+    expect(world.get(valid.target, Transform).unwrap().pos[0]).toBeCloseTo(1);
+    expect(new Set(warn.mock.calls.map(([value]) => (value as { code?: string }).code))).toEqual(
+      new Set([
+        'animation-target-missing',
+        'animation-target-transform-missing',
+        'animation-target-id-duplicate',
+        'animation-channel-missing',
+      ]),
+    );
+  });
+
+  it('isolates two players sharing one Clip and TargetId while pause ownership swaps', async () => {
+    const world = new World();
+    await createWorldContext(world, [scenePlugin()]);
+    await createWorldContext(world, [animationPlugin()]);
+    const clipHandle = world.allocSharedRef('AnimationClip', clip());
+    const a = await spawnPair(world, clipHandle);
+    const b = await spawnPair(world, clipHandle);
+    world.set(a.player, AnimationPlayer, { paused: true }).unwrap();
+
+    world.update(0.1);
+    expect(world.get(a.target, Transform).unwrap().pos[0]).toBe(0);
+    expect(world.get(b.target, Transform).unwrap().pos[0]).toBeCloseTo(1);
+
+    world.set(a.player, AnimationPlayer, { paused: false }).unwrap();
+    world.set(b.player, AnimationPlayer, { paused: true }).unwrap();
+    world.update(0.1);
+    expect(world.get(a.target, Transform).unwrap().pos[0]).toBeCloseTo(1);
+    expect(world.get(b.target, Transform).unwrap().pos[0]).toBeCloseTo(1);
+  });
+
+  it('performs at most one final Transform set per target per update', async () => {
+    const world = new World();
+    await createWorldContext(world, [animationPlugin()]);
+    const clipHandle = world.allocSharedRef('AnimationClip', clip());
+    const { target } = await spawnPair(world, clipHandle);
+    const set = vi.spyOn(world, 'set');
+
+    world.update(0.1);
+
+    const targetSets = set.mock.calls.filter(
+      ([entity, component]) => entity === target && component === Transform,
+    );
+    expect(targetSets).toHaveLength(1);
+  });
+
+  it('keeps targets alive after player despawn and permits stale-owner recovery', async () => {
+    const world = new World();
+    await createWorldContext(world, [animationPlugin()]);
+    const clipHandle = world.allocSharedRef('AnimationClip', clip());
+    const first = await spawnPair(world, clipHandle);
+    world.removeComponent(first.target, ChildOf).unwrap();
+    world.despawn(first.player).unwrap();
+    expect(world.get(first.target, Entity).ok).toBe(true);
+    expect(world.get(first.target, AnimatedBy).unwrap().player).toBe(first.player);
+
+    const replacement = world
+      .spawn({
+        component: AnimationPlayer,
+        data: { clips: [clipHandle], times: [0], weights: [1], speeds: [1] },
+      })
+      .unwrap() as EntityHandle;
+    world
+      .addComponent(first.target, { component: ChildOf, data: { parent: replacement } })
+      .unwrap();
+    expect(bindAnimationTargets(world, replacement, [first.target]).ok).toBe(true);
+    expect(world.get(first.target, AnimatedBy).unwrap().player).toBe(replacement);
+    expect([...world.get(replacement, AnimationTargets).unwrap().targets]).toEqual([first.target]);
+  });
+
+  it.each([30, 60, 120])('reaches the same target pose after one second at %iHz', async (hz) => {
+    const world = new World();
+    await createWorldContext(world, [animationPlugin()]);
+    const clipHandle = world.allocSharedRef('AnimationClip', clip());
+    const { target } = await spawnPair(world, clipHandle);
+    for (let frame = 0; frame < hz; frame++) world.update(1 / hz);
+    expect(world.get(target, Transform).unwrap().pos[0]).toBeCloseTo(10, 4);
+  });
+});

package/src/__tests__/animation-target-relationship.unit.test.ts

@@ -0,0 +1,65 @@
+import { Entity, World } from '@forgeax/engine-ecs';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { AnimationPlayer } from '../animation-player';
+import { AnimatedBy, AnimationTargetId, AnimationTargets } from '../animation-target';
+
+function spawnPlayer(world: World) {
+  return world
+    .spawn(
+      { component: AnimationPlayer, data: {} },
+      { component: AnimationTargets, data: {} },
+      { component: Transform, data: {} },
+    )
+    .unwrap();
+}
+
+function spawnTarget(world: World) {
+  return world
+    .spawn(
+      { component: AnimationTargetId, data: { value: 'a'.repeat(32) } },
+      { component: Transform, data: {} },
+    )
+    .unwrap();
+}
+
+describe('animation target relationship', () => {
+  it('declares an exclusive non-linked relationship', () => {
+    expect(componentSchema(AnimationTargets).targets).toBe('array<entity>');
+    expect(componentSchema(AnimatedBy).player).toBe('entity');
+  });
+
+  it('keeps add, remove, rebind, and target despawn mirrors synchronized', () => {
+    const world = new World();
+    const first = spawnPlayer(world);
+    const second = spawnPlayer(world);
+    const target = spawnTarget(world);
+
+    world.addComponent(target, { component: AnimatedBy, data: { player: first } }).unwrap();
+    expect([...world.get(first, AnimationTargets).unwrap().targets]).toEqual([target]);
+
+    world.addComponent(target, { component: AnimatedBy, data: { player: second } }).unwrap();
+    expect([...world.get(first, AnimationTargets).unwrap().targets]).toEqual([]);
+    expect([...world.get(second, AnimationTargets).unwrap().targets]).toEqual([target]);
+
+    world.removeComponent(target, AnimatedBy).unwrap();
+    expect([...world.get(second, AnimationTargets).unwrap().targets]).toEqual([]);
+
+    world.addComponent(target, { component: AnimatedBy, data: { player: first } }).unwrap();
+    world.despawn(target).unwrap();
+    expect([...world.get(first, AnimationTargets).unwrap().targets]).toEqual([]);
+  });
+
+  it('does not despawn targets with the player and preserves a stale owner', () => {
+    const world = new World();
+    const player = spawnPlayer(world);
+    const target = spawnTarget(world);
+    world.addComponent(target, { component: AnimatedBy, data: { player } }).unwrap();
+
+    world.despawn(player).unwrap();
+
+    expect(world.get(target, Entity).ok).toBe(true);
+    expect(world.get(target, AnimatedBy).unwrap().player).toBe(player);
+  });
+});