@forgeax/engine-animation 0.1.2

package/src/__tests__/animation-target-source-boundary.unit.test.ts

@@ -0,0 +1,49 @@
+// @ts-expect-error Node built-in types are provided by the Vitest runner.
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+describe('animation target source boundary', () => {
+  it('registers animation target components before hello-skin writeback instantiates glTF', () => {
+    const source = readFileSync(
+      new URL('../../../../apps/hello/skin/scripts/smoke-writeback-dawn.mjs', import.meta.url),
+      'utf8',
+    );
+    const registration = source.indexOf("await import('@forgeax/engine-animation')");
+    const instantiate = source.indexOf('worldInstantiateScene(world, sceneHandle)');
+
+    expect(registration).toBeGreaterThanOrEqual(0);
+    expect(instantiate).toBeGreaterThan(registration);
+  });
+
+  it('does not discover animation targets through Skin, Name, or targetPath', () => {
+    const source = readFileSync(
+      new URL('../systems/advance-animation-player.ts', import.meta.url),
+      'utf8',
+    );
+    expect(source).not.toMatch(/\bSkin\b/);
+    expect(source).not.toMatch(/\bName\b/);
+    expect(source).not.toContain('targetPath');
+    expect(source).toContain('AnimationTargets');
+    expect(source).toContain('AnimationTargetId');
+  });
+
+  it('keeps Skin joints limited to palette and post-spawn joint wiring', () => {
+    const evaluator = readFileSync(
+      new URL('../systems/advance-animation-player.ts', import.meta.url),
+      'utf8',
+    );
+    const palette = readFileSync(
+      new URL('../../../render/src/systems/skin-palette-allocator.ts', import.meta.url),
+      'utf8',
+    );
+    const jointWiring = readFileSync(
+      new URL('../../../render/src/scene-instances/post-spawn-resolve-joints.ts', import.meta.url),
+      'utf8',
+    );
+
+    expect(evaluator).not.toMatch(/\bSkin\.joints\b|world\.get\([^)]*,\s*Skin\b/);
+    expect(palette).toContain('Skin.joints');
+    expect(jointWiring).toContain('Skin');
+    expect(jointWiring).toContain('joints');
+  });
+});

package/src/__tests__/bind-animation-targets.unit.test.ts

@@ -0,0 +1,167 @@
+import { type EntityHandle, World } from '@forgeax/engine-ecs';
+import { ChildOf, Name, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { AnimationPlayer } from '../animation-player';
+import {
+  AnimatedBy,
+  AnimationTargetId,
+  AnimationTargets,
+  bindAnimationTargets,
+} from '../animation-target';
+import { deriveAnimationTargetId } from '../target-id';
+
+function spawnPlayer(world: World, withMirror = true) {
+  if (!withMirror) {
+    return world
+      .spawn(
+        { component: AnimationPlayer, data: {} },
+        { component: Transform, data: {} },
+        { component: Name, data: { value: 'Root' } },
+      )
+      .unwrap();
+  }
+  return world
+    .spawn(
+      { component: AnimationPlayer, data: {} },
+      { component: Transform, data: {} },
+      { component: Name, data: { value: 'Root' } },
+      { component: AnimationTargets, data: {} },
+    )
+    .unwrap();
+}
+
+function spawnTarget(world: World, player: EntityHandle, name = 'Target') {
+  return world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: Name, data: { value: name } },
+      { component: ChildOf, data: { parent: player } },
+    )
+    .unwrap();
+}
+
+function expectBindCode(result: ReturnType<typeof bindAnimationTargets>, code: string) {
+  expect(result.ok).toBe(false);
+  if (result.ok) return;
+  expect(result.error.code).toBe(code);
+  expect(result.error.hint.length).toBeGreaterThan(0);
+  expect(result.error.detail).toBeDefined();
+}
+
+describe('bindAnimationTargets', () => {
+  it('derives missing IDs, preserves existing IDs, and is idempotent', () => {
+    const world = new World();
+    const player = spawnPlayer(world);
+    const derived = spawnTarget(world, player, 'Hip');
+    const existing = spawnTarget(world, player, 'Hand');
+    const existingId = deriveAnimationTargetId(['authored', 'hand']);
+    world
+      .addComponent(existing, { component: AnimationTargetId, data: { value: existingId } })
+      .unwrap();
+    world.removeComponent(existing, Name).unwrap();
+
+    expect(bindAnimationTargets(world, player, [derived, existing]).ok).toBe(true);
+    expect(world.get(derived, AnimationTargetId).unwrap().value).toBe(
+      deriveAnimationTargetId(['Root', 'Hip']),
+    );
+    expect(world.get(existing, AnimationTargetId).unwrap().value).toBe(existingId);
+    expect(world.get(derived, AnimatedBy).unwrap().player).toBe(player);
+    expect(world.get(existing, AnimatedBy).unwrap().player).toBe(player);
+    expect([...world.get(player, AnimationTargets).unwrap().targets]).toEqual([derived, existing]);
+
+    expect(bindAnimationTargets(world, player, [existing, derived, existing]).ok).toBe(true);
+    expect([...world.get(player, AnimationTargets).unwrap().targets]).toEqual([derived, existing]);
+  });
+
+  it('creates a missing mirror and replaces a stale owner', () => {
+    const world = new World();
+    const player = spawnPlayer(world, false);
+    const staleOwner = spawnPlayer(world);
+    const target = spawnTarget(world, player);
+    world.addComponent(target, { component: AnimatedBy, data: { player: staleOwner } }).unwrap();
+    world.despawn(staleOwner).unwrap();
+
+    expect(bindAnimationTargets(world, player, [target]).ok).toBe(true);
+    expect(world.get(target, AnimatedBy).unwrap().player).toBe(player);
+    expect([...world.get(player, AnimationTargets).unwrap().targets]).toEqual([target]);
+  });
+
+  it('reports invalid player, target, hierarchy, and missing-name failures', () => {
+    const world = new World();
+    const player = spawnPlayer(world);
+    const invalidPlayer = world.spawn({ component: Transform, data: {} }).unwrap();
+    const outside = world
+      .spawn({ component: Transform, data: {} }, { component: Name, data: { value: 'Outside' } })
+      .unwrap();
+    const noName = world
+      .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent: player } })
+      .unwrap();
+    const stale = spawnTarget(world, player);
+    world.despawn(stale).unwrap();
+
+    expectBindCode(
+      bindAnimationTargets(world, invalidPlayer, []),
+      'animation-target-player-invalid',
+    );
+    expectBindCode(bindAnimationTargets(world, player, [stale]), 'animation-target-invalid');
+    expectBindCode(
+      bindAnimationTargets(world, player, [outside]),
+      'animation-target-outside-player-root',
+    );
+    expectBindCode(bindAnimationTargets(world, player, [noName]), 'animation-target-name-missing');
+  });
+
+  it('reports duplicate IDs, owner conflicts, and invalid ID wires', () => {
+    const world = new World();
+    const player = spawnPlayer(world);
+    const otherPlayer = spawnPlayer(world);
+    const first = spawnTarget(world, player, 'First');
+    const second = spawnTarget(world, player, 'Second');
+    const duplicate = deriveAnimationTargetId(['duplicate']);
+    world
+      .addComponent(first, { component: AnimationTargetId, data: { value: duplicate } })
+      .unwrap();
+    world
+      .addComponent(second, { component: AnimationTargetId, data: { value: duplicate } })
+      .unwrap();
+    expectBindCode(
+      bindAnimationTargets(world, player, [first, second]),
+      'animation-target-id-duplicate',
+    );
+
+    world.removeComponent(second, AnimationTargetId).unwrap();
+    world.addComponent(second, { component: AnimatedBy, data: { player: otherPlayer } }).unwrap();
+    expectBindCode(
+      bindAnimationTargets(world, player, [second]),
+      'animation-target-player-conflict',
+    );
+
+    world.removeComponent(second, AnimatedBy).unwrap();
+    world
+      .addComponent(second, { component: AnimationTargetId, data: { value: 'not-a-target-id' } })
+      .unwrap();
+    expectBindCode(bindAnimationTargets(world, player, [second]), 'animation-target-id-invalid');
+  });
+
+  it('rejects an ID already bound to another live target without changing the world', () => {
+    const world = new World();
+    const player = spawnPlayer(world);
+    const first = spawnTarget(world, player, 'First');
+    const second = spawnTarget(world, player, 'Second');
+    const duplicate = deriveAnimationTargetId(['duplicate']);
+    world
+      .addComponent(first, { component: AnimationTargetId, data: { value: duplicate } })
+      .unwrap();
+    world
+      .addComponent(second, { component: AnimationTargetId, data: { value: duplicate } })
+      .unwrap();
+    expect(bindAnimationTargets(world, player, [first]).ok).toBe(true);
+    const beforeTargets = [...world.get(player, AnimationTargets).unwrap().targets];
+
+    expectBindCode(bindAnimationTargets(world, player, [second]), 'animation-target-id-duplicate');
+
+    expect(world.get(first, AnimatedBy).unwrap().player).toBe(player);
+    expect(world.get(second, AnimatedBy).ok).toBe(false);
+    expect([...world.get(player, AnimationTargets).unwrap().targets]).toEqual(beforeTargets);
+  });
+});

package/src/__tests__/documentation-contract.unit.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+// @ts-expect-error Vite provides raw text imports to the test runner.
+import readme from '../../README.md?raw';
+import type { BindAnimationTargetsErrorCode } from '../animation-target';
+
+const BIND_ERROR_CODES = [
+  'animation-target-player-invalid',
+  'animation-target-invalid',
+  'animation-target-outside-player-root',
+  'animation-target-name-missing',
+  'animation-target-id-invalid',
+  'animation-target-id-duplicate',
+  'animation-target-player-conflict',
+  'animation-target-capacity-reserve-failed',
+  'animation-target-bind-failed',
+] as const satisfies readonly BindAnimationTargetsErrorCode[];
+
+describe('animation target documentation contract', () => {
+  it('puts a self-contained direct playback flow first', () => {
+    const quickStart = readme.indexOf('## Quick start');
+    expect(quickStart).toBeGreaterThan(0);
+    expect(quickStart).toBeLessThan(readme.indexOf('## Identity and ownership'));
+    const firstSection = readme.slice(quickStart, readme.indexOf('## Identity and ownership'));
+    for (const literal of [
+      "import { createWorldContext, World } from '@forgeax/engine-ecs'",
+      "import { ChildOf, Name, Transform } from '@forgeax/engine-scene'",
+      "import type { AnimationClip } from '@forgeax/engine-types'",
+      'AnimationTargetId',
+      'bindAnimationTargets',
+      'AnimationPlayer',
+      'const world = new World()',
+      'const player =',
+      'const target =',
+      'const clip =',
+      'const clipHandle =',
+      'const slots =',
+    ]) {
+      expect(firstSection).toContain(literal);
+    }
+    for (const externalName of [
+      'sceneInstance',
+      'repair',
+      'directSlots',
+      'clipHandle)',
+      'defineAnimationGraph',
+    ]) {
+      expect(firstSection).not.toContain(externalName);
+    }
+  });
+
+  it('documents wire, structured recovery, demo, and explicit boundaries', () => {
+    for (const literal of [
+      '32 lowercase hexadecimal',
+      'BLAKE3',
+      'UUID v8',
+      'from the player through the',
+      'asset root through each target',
+      'synthetic runtime controller',
+      'error.code',
+      'error.hint',
+      'error.detail',
+      'animation-target-outside-player-root',
+      'animation-target-name-missing',
+      'animation-target-id-duplicate',
+      'animation-target-player-conflict',
+      'apps/bevy/animated-transform',
+      'arbitrary component properties',
+      'animation FSM',
+      'editor UI',
+      'targetId',
+      'targetPath',
+    ]) {
+      expect(readme).toContain(literal);
+    }
+
+    const errorRecovery = readme.slice(
+      readme.indexOf('## Error recovery'),
+      readme.indexOf('## Example and boundaries'),
+    );
+    const documentedCodes = [...errorRecovery.matchAll(/\| `(animation-target-[a-z-]+)` \|/g)].map(
+      (match) => match[1],
+    );
+    expect(documentedCodes).toEqual(BIND_ERROR_CODES);
+
+    // Rejected review-round-1 spellings stay here only as negative contract fixtures.
+    for (const staleCode of [
+      'animation-player-invalid',
+      'animation-target-outside-root',
+      'animation-target-owner-conflict',
+    ]) {
+      expect(readme).not.toContain(staleCode);
+    }
+  });
+});

package/src/__tests__/ecs-consumer.integration.test.ts

@@ -0,0 +1,10 @@
+import { createWorldContext, World } from '@forgeax/engine-ecs';
+import { describe, it } from 'vitest';
+import { animationPlugin } from '../plugin';
+
+describe('animation ECS consumer', () => {
+  it('accepts the plugin build callback from a real World', async () => {
+    const world = new World();
+    await createWorldContext(world, [animationPlugin()]);
+  });
+});

package/src/__tests__/errors.unit.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { AnimationGraphClipMissingError } from '../errors';
+import { AnimationPlayerSlotLengthMismatchError } from '../player-errors';
+
+describe('animation errors', () => {
+  it('exposes structured codes and details', () => {
+    const graph = new AnimationGraphClipMissingError({ node: 1, clip: 2 });
+    const player = new AnimationPlayerSlotLengthMismatchError({
+      entity: 1,
+      clips: 1,
+      times: 0,
+      weights: 1,
+      speeds: 1,
+    });
+    expect(graph.code).toBe('animation-graph-clip-missing');
+    expect(graph.detail.node).toBe(1);
+    expect(player.code).toBe('animation-player-slot-length-mismatch');
+  });
+});

package/src/__tests__/graph-player.integration.test.ts

@@ -0,0 +1,22 @@
+import { createWorldContext, Update, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { defineAnimationGraph } from '../graph/define-animation-graph';
+import { animationPlugin } from '../index';
+
+describe('animation graph World chain', () => {
+  it('registers systems on a real World schedule', async () => {
+    const world = new World();
+    await createWorldContext(world, [animationPlugin()]);
+    expect(() => world.update(1 / 60)).not.toThrow();
+    void Update;
+  });
+
+  it('keeps durable clip identity across graph rebuild and evaluation', () => {
+    const guid = '019e2cc6-0c86-79da-aa76-b0984c86d45c';
+    const graph = defineAnimationGraph((builder) => builder.clip(guid));
+
+    expect(graph.ok).toBe(true);
+    if (!graph.ok) return;
+    expect(graph.value.nodes[0]).toMatchObject({ type: 'clip', clip: guid });
+  });
+});

package/src/__tests__/graph-player.unit.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+import { defineAnimationGraph, describeAnimationGraph, serializeAnimationGraph } from '../index';
+
+describe('animation graph public behavior', () => {
+  it('defines, describes, and serializes a graph', () => {
+    const built = defineAnimationGraph((builder) => builder.clip('test/animation-clip'));
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    expect(describeAnimationGraph(built.value).nodes).toHaveLength(1);
+    expect(serializeAnimationGraph(built.value, () => 'clip')).toBeDefined();
+  });
+});

package/src/__tests__/handle-errors.unit.test.ts

@@ -0,0 +1,17 @@
+import { World } from '@forgeax/engine-ecs';
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { resolveAnimationAsset } from '../resolve-animation-asset';
+
+describe('animation handle failures', () => {
+  it('rejects an empty durable GUID at the consumer boundary', () => {
+    const result = resolveAnimationAsset<AnimationClip>(
+      new World(),
+      '',
+      'animation-clip',
+      () => undefined,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('animation-asset-not-found');
+  });
+});

package/src/__tests__/loader-boundary.unit.test.ts

@@ -0,0 +1,66 @@
+import { expect, it } from 'vitest';
+import { animationGraphContribution } from '../assets/animation-decoder';
+import { serializeAnimationGraph } from '../graph/serialize-animation-graph';
+
+it('keeps graph payload decoding in the animation owner', () => {
+  expect(animationGraphContribution.kind.kind).toBe('animation-graph');
+});
+
+it('serializes a durable clip GUID without a World handle or resolver cast', () => {
+  const guid = '019e2cc6-0c86-79da-aa76-b0984c86d45c';
+  const graph = {
+    kind: 'animation-graph',
+    nodes: [{ type: 'clip', clip: guid, weight: 1 }],
+    root: 0,
+  } as never;
+
+  const result = serializeAnimationGraph(graph, (clip) => clip);
+
+  expect(result).toEqual({
+    payload: {
+      nodes: [{ type: 'clip', clip: 0, weight: 1 }],
+      root: 0,
+    },
+    refs: [guid],
+  });
+  expect(JSON.stringify(result?.payload)).not.toContain('shared');
+});
+
+it('rejects a missing durable clip GUID instead of inventing a handle', () => {
+  const graph = {
+    kind: 'animation-graph',
+    nodes: [{ type: 'clip', clip: '', weight: 1 }],
+    root: 0,
+  } as never;
+
+  expect(serializeAnimationGraph(graph, (clip) => clip || undefined)).toBeUndefined();
+});
+
+it('rejects the removed numeric clip-handle durable shape', () => {
+  const graph = {
+    kind: 'animation-graph',
+    nodes: [{ type: 'clip', clip: 7, weight: 1 }],
+    root: 0,
+  } as never;
+
+  expect(
+    serializeAnimationGraph(graph, (clip) => (typeof clip === 'string' ? clip : undefined)),
+  ).toBeUndefined();
+});
+
+it('keeps the animation owner consumer on durable GUID payloads', () => {
+  const graph = {
+    kind: 'animation-graph',
+    nodes: [{ type: 'clip', clip: '019e2cc6-0c86-79da-aa76-b0984c86d45c', weight: 1 }],
+    root: 0,
+  } as never;
+
+  expect(serializeAnimationGraph(graph, (clip) => clip)).toMatchObject({
+    refs: ['019e2cc6-0c86-79da-aa76-b0984c86d45c'],
+  });
+});
+
+it('exposes the graph owner contribution for the shared decoder map', () => {
+  expect(animationGraphContribution.kind.kind).toBe('animation-graph');
+  expect(animationGraphContribution.consumer).toBe('evaluateAnimationGraph');
+});

package/src/__tests__/morph-weights-playback.integration.test.ts

@@ -0,0 +1,84 @@
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { createWorldContext, World } from '@forgeax/engine-ecs';
+import { ChildOf, MorphWeights, Name, scenePlugin, Transform } from '@forgeax/engine-scene';
+import type { AnimationClip, AnimationTargetIdValue } from '@forgeax/engine-types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { AnimationPlayer } from '../animation-player';
+import { AnimationTargetId, bindAnimationTargets } from '../animation-target';
+import { animationPlugin } from '../plugin';
+
+const TARGET_ID = 'b95da0ec669189f98273e8f86d8ad9f2' as AnimationTargetIdValue;
+
+function weightsClip(): AnimationClip {
+  return {
+    kind: 'animation-clip',
+    duration: 1,
+    channels: [
+      {
+        targetId: TARGET_ID,
+        property: 'weights',
+        sampler: {
+          input: new Float32Array([0, 1]),
+          output: new Float32Array([0, 0, 0, 0, 1, 2, 3, 4]),
+          interpolation: 'LINEAR',
+        },
+      },
+    ],
+  };
+}
+
+async function setupTarget(
+  withWeights: boolean,
+): Promise<{ world: World; player: EntityHandle; target: EntityHandle }> {
+  const world = new World();
+  await createWorldContext(world, [scenePlugin()]);
+  await createWorldContext(world, [animationPlugin()]);
+  const clip = world.allocSharedRef('AnimationClip', weightsClip());
+  const player = world.spawn({ component: Transform, data: {} }).unwrap() as EntityHandle;
+  world.addComponent(player, { component: Name, data: { value: 'Root' } }).unwrap();
+  world
+    .addComponent(player, {
+      component: AnimationPlayer,
+      data: { clips: [clip], times: [0], weights: [1], speeds: [0], paused: true },
+    })
+    .unwrap();
+  const target = world.spawn({ component: Transform, data: {} }).unwrap() as EntityHandle;
+  world.addComponent(target, { component: Name, data: { value: 'Morph' } }).unwrap();
+  world.addComponent(target, { component: ChildOf, data: { parent: player } }).unwrap();
+  world.addComponent(target, { component: AnimationTargetId, data: { value: TARGET_ID } }).unwrap();
+  if (withWeights) {
+    world
+      .addComponent(target, { component: MorphWeights, data: { weights: [0, 0, 0, 0] } })
+      .unwrap();
+  }
+  expect(bindAnimationTargets(world, player, [target]).ok).toBe(true);
+  return { world, player, target };
+}
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('morph weights animation contract', () => {
+  it.each([
+    0, 0.25, 0.5, 0.999,
+  ])('samples four morph elements per-element at t=%s, not quaternion interpolation', async (time) => {
+    const { world, player, target } = await setupTarget(true);
+    world.set(player, AnimationPlayer, { times: [time] }).unwrap();
+    world.update(0);
+    const expected = [time, time * 2, time * 3, time * 4];
+    expect([...world.get(target, MorphWeights).unwrap().weights]).toEqual(
+      expected.map((value) => expect.closeTo(value, 5)),
+    );
+  });
+
+  it('emits the exact missing MorphWeights diagnostic and does not draw a base substitute', async () => {
+    const { world } = await setupTarget(false);
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    world.update(0.25);
+    expect(warn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        code: 'animation-target-morph-weights-missing',
+        detail: expect.objectContaining({ property: 'weights', expectedWeightCount: 4 }),
+      }),
+    );
+  });
+});

package/src/__tests__/morph-weights.unit.test.ts

@@ -0,0 +1,26 @@
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+describe('morph weight animation contract', () => {
+  it('exposes a runtime MorphWeights component and preserves frame-major channels', async () => {
+    const scene = await import('@forgeax/engine-scene');
+    expect(scene.MorphWeights).toBeDefined();
+    const clip = {
+      kind: 'animation-clip',
+      duration: 1,
+      channels: [
+        {
+          targetId: 'b95da0ec669189f98273e8f86d8ad9f2',
+          property: 'weights',
+          sampler: {
+            input: new Float32Array([0, 1]),
+            output: new Float32Array([0, 0, 0, 0, 1, 2, 3, 4]),
+            interpolation: 'LINEAR',
+          },
+        },
+      ],
+    } as unknown as AnimationClip;
+    expect(clip.channels[0]?.property).toBe('weights');
+    expect(clip.channels[0]?.sampler.output.length).toBe(8);
+  });
+});

package/src/__tests__/public-animation-target-api.test-d.ts

@@ -0,0 +1,47 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { ENTITY_NULL_RAW } from '@forgeax/engine-ecs';
+import { expectTypeOf } from 'vitest';
+import type { BindAnimationTargetsErrorCode } from '../index';
+import {
+  AnimatedBy,
+  AnimationPlayer,
+  AnimationTargetId,
+  AnimationTargets,
+  bindAnimationTargets,
+  defineAnimationGraph,
+  deriveAnimationTargetId,
+  isAnimationTargetId,
+} from '../index';
+
+expectTypeOf(deriveAnimationTargetId).parameter(0).toEqualTypeOf<readonly string[]>();
+expectTypeOf(isAnimationTargetId).returns.toEqualTypeOf<boolean>();
+expectTypeOf(AnimationTargetId).toBeObject();
+expectTypeOf(AnimatedBy).toBeObject();
+expectTypeOf(AnimationTargets).toBeObject();
+expectTypeOf(AnimationPlayer).toBeObject();
+expectTypeOf(defineAnimationGraph).toBeFunction();
+expectTypeOf<BindAnimationTargetsErrorCode>().toEqualTypeOf<
+  | 'animation-target-player-invalid'
+  | 'animation-target-invalid'
+  | 'animation-target-outside-player-root'
+  | 'animation-target-name-missing'
+  | 'animation-target-id-invalid'
+  | 'animation-target-id-duplicate'
+  | 'animation-target-player-conflict'
+  | 'animation-target-capacity-reserve-failed'
+  | 'animation-target-bind-failed'
+>();
+
+function collectAndBind(
+  world: World,
+  player: EntityHandle,
+  scene: { readonly mapping: ArrayLike<number> },
+): ReturnType<typeof bindAnimationTargets> {
+  const targets = Array.from(scene.mapping)
+    .filter((raw) => raw !== ENTITY_NULL_RAW)
+    .map((raw) => raw as EntityHandle)
+    .filter((entity) => world.get(entity, AnimationTargetId).ok);
+  return bindAnimationTargets(world, player, targets);
+}
+
+expectTypeOf(collectAndBind).returns.toEqualTypeOf<ReturnType<typeof bindAnimationTargets>>();