@forgeax/engine-animation 0.1.2

package/src/__tests__/resolver-ownership.integration.test.ts

@@ -0,0 +1,99 @@
+import { createWorldContext, World } from '@forgeax/engine-ecs';
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { animationPlugin } from '../plugin';
+import { resolveAnimationAsset } from '../resolve-animation-asset';
+
+describe('animation resolver ownership', () => {
+  it('builds and ticks without a runtime-provided resolver resource', async () => {
+    const world = new World();
+    await createWorldContext(world, [animationPlugin()]);
+    expect(world.hasResource('AnimationAssetResolver')).toBe(false);
+    expect(() => world.update(1 / 60).unwrap()).not.toThrow();
+  });
+
+  it('projects one durable GUID separately into each World', () => {
+    const world = new World();
+    const clip: AnimationClip = {
+      kind: 'animation-clip',
+      duration: 1,
+      channels: [],
+    };
+    const first = resolveAnimationAsset(world, 'clip-guid', 'animation-clip', () => clip);
+    const secondWorld = new World();
+    const second = resolveAnimationAsset(secondWorld, 'clip-guid', 'animation-clip', () => clip);
+    expect(first.ok).toBe(true);
+    expect(second.ok).toBe(true);
+    if (first.ok && second.ok) {
+      expect(world.sharedRefs.resolve(first.value.handle).ok).toBe(true);
+      expect(secondWorld.sharedRefs.resolve(second.value.handle).ok).toBe(true);
+    }
+  });
+
+  it.each([
+    ['missing', undefined, 'animation-asset-not-found'],
+    ['wrong-kind', { kind: 'audio' }, 'animation-asset-kind-mismatch'],
+    ['stale', { code: 'stale' }, 'animation-asset-stale'],
+  ] as const)('reports %s at the animation owner boundary', (_name, payload, code) => {
+    const result = resolveAnimationAsset<AnimationClip>(
+      new World(),
+      'clip-guid',
+      'animation-clip',
+      () => payload as never,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe(code);
+  });
+
+  it('contains a throwing lookup before publication and retries on the same World', () => {
+    const world = new World();
+    const guid = 'clip-guid';
+    const clip: AnimationClip = {
+      kind: 'animation-clip',
+      duration: 1,
+      channels: [],
+    };
+    let repaired = false;
+    const lookup = vi.fn((_requestedGuid: string) => {
+      if (!repaired) throw new Error('controlled lookup sentinel');
+      return clip;
+    });
+    const internSharedRef = vi.spyOn(world, 'internSharedRef');
+
+    const first = (() => {
+      try {
+        return { result: resolveAnimationAsset(world, guid, 'animation-clip', lookup) };
+      } catch (thrown) {
+        return { result: undefined, thrown };
+      }
+    })();
+    expect(first.thrown).toBeUndefined();
+    expect(first.result?.ok).toBe(false);
+    if (first.result === undefined || first.result.ok) return;
+    expect(first.result.error.code).toBe('animation-asset-not-found');
+    expect(first.result.error.detail).toEqual({
+      guid,
+      expectedKind: 'animation-clip',
+      lookupCode: 'lookup-threw',
+    });
+    expect(first.result.error.message).not.toContain('controlled lookup sentinel');
+    expect(lookup).toHaveBeenCalledTimes(1);
+    expect(internSharedRef).not.toHaveBeenCalled();
+
+    repaired = true;
+    const retried = resolveAnimationAsset(world, guid, 'animation-clip', lookup);
+    expect(retried.ok).toBe(true);
+    if (!retried.ok) return;
+    expect(retried.value.asset).toBe(clip);
+    expect(lookup).toHaveBeenCalledTimes(2);
+    expect(internSharedRef).toHaveBeenCalledTimes(1);
+
+    const repeated = resolveAnimationAsset(world, guid, 'animation-clip', lookup);
+    expect(repeated.ok).toBe(true);
+    if (!repeated.ok) return;
+    expect(repeated.value.asset).toBe(clip);
+    expect(repeated.value.handle).toBe(retried.value.handle);
+    expect(lookup).toHaveBeenCalledTimes(3);
+    expect(internSharedRef).toHaveBeenCalledTimes(2);
+  });
+});

package/src/__tests__/root-surface.unit.test.ts

@@ -0,0 +1,10 @@
+// @perf-budget-skip: intentional public-root cold-import contract gate.
+
+import { describe, expect, it } from 'vitest';
+
+describe('animation graph registration stays plugin-owned', () => {
+  it('does not project the plugin-internal registration helper from the public root', async () => {
+    const root = (await import('../index')) as Record<string, unknown>;
+    expect(root).not.toHaveProperty('registerEvaluateAnimationGraph');
+  });
+});

package/src/__tests__/scene-instance-target-collection.integration.test.ts

@@ -0,0 +1,26 @@
+// @ts-expect-error Node built-in types are provided by the Vitest runner.
+import { readFileSync } from 'node:fs';
+import { ENTITY_NULL_RAW } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+
+const APP_SOURCES = [
+  '../../../../apps/hello/skin/src/main.ts',
+  '../../../../apps/hello/fbx-skin/src/main.ts',
+  '../../../../apps/hello/animation-graph/src/main.ts',
+  '../../../../apps/collectathon/src/spawn/spawn-player.ts',
+] as const;
+
+describe('SceneInstance animation target collection', () => {
+  it('keeps entity zero and skips only ENTITY_NULL_RAW', () => {
+    const mapping = new Uint32Array([0, 7, ENTITY_NULL_RAW]);
+    expect(Array.from(mapping).filter((raw) => raw !== ENTITY_NULL_RAW)).toEqual([0, 7]);
+  });
+
+  it.each(APP_SOURCES)('%s explicitly binds targets without treating zero as null', (path) => {
+    const source = readFileSync(new URL(path, import.meta.url), 'utf8');
+    expect(source).toContain('bindAnimationTargets');
+    expect(source).toContain('AnimationTargetId');
+    expect(source).toContain('ENTITY_NULL_RAW');
+    expect(source).not.toMatch(/(?:entRaw|raw)\s*===\s*0/);
+  });
+});

package/src/__tests__/scriptable-pack-consumer.test-d.ts

@@ -0,0 +1,8 @@
+import type { AnimationGraph } from '@forgeax/engine-types';
+import { expectTypeOf } from 'vitest';
+import { defineAnimationGraph } from '../graph/define-animation-graph';
+
+const graph = defineAnimationGraph((builder) =>
+  builder.clip('019ffa97-9000-7000-8000-000000000013'),
+);
+if (graph.ok) expectTypeOf(graph.value).toMatchTypeOf<AnimationGraph>();

package/src/__tests__/time-delta-regression.integration.test.ts

@@ -0,0 +1,79 @@
+// Regression test for a bug fixed 2026-07-27 (feedback:
+// advance-animation-player-hardcoded-fixed-dt-ignores-time-delta): the
+// `AdvanceAnimationPlayer` / `EvaluateAnimationGraph` system tokens used to call
+// their pure functions with a literal `1 / 60` instead of the World's real
+// `Time.delta`, so animation played back at the wrong speed whenever
+// `world.update(dt)` was driven at anything other than exactly 60Hz.
+//
+// These tests drive `world.update(dt)` at 30Hz / 60Hz / 120Hz through the real
+// default-plugin schedule (not by calling `advanceAnimationPlayer` /
+// `evaluateAnimationGraph` directly with an explicit `dt` — that would only
+// prove the pure functions are dt-aware, not that the systems wire the real
+// frame time into them) and assert the advanced time columns scale with the
+// driven `dt`, not with a fixed `1 / 60`.
+
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { createWorldContext, World } from '@forgeax/engine-ecs';
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { AnimationPlayer } from '../animation-player';
+import { defineAnimationGraph } from '../graph/define-animation-graph';
+import { animationPlugin } from '../plugin';
+
+function registerClip(world: World, duration: number) {
+  const clip: AnimationClip = { kind: 'animation-clip', duration, channels: [] };
+  return world.allocSharedRef('AnimationClip', clip);
+}
+
+const FRAME_RATES_HZ = [30, 60, 120] as const;
+
+describe('animation systems honor real Time.delta (regression: hardcoded 1/60)', () => {
+  it.each(
+    FRAME_RATES_HZ,
+  )('advanceAnimationPlayer advances times[0] by the real dt at %iHz, not a fixed 1/60', async (hz) => {
+    const dt = 1 / hz;
+    const world = new World();
+    await createWorldContext(world, [animationPlugin()]);
+
+    const clip = registerClip(world, 10);
+    const e = world
+      .spawn({
+        component: AnimationPlayer,
+        data: { clips: [clip], times: [0], weights: [1], speeds: [1] },
+      })
+      .unwrap() as EntityHandle;
+
+    world.update(dt);
+
+    const ap = world.get(e, AnimationPlayer).unwrap() as unknown as { times: Float32Array };
+    expect(ap.times[0]).toBeCloseTo(dt, 5);
+  });
+
+  it.each(
+    FRAME_RATES_HZ,
+  )('evaluateAnimationGraph advances nodeTimes[0] by the real dt at %iHz, not a fixed 1/60', async (hz) => {
+    const dt = 1 / hz;
+    const world = new World();
+    const clipPayload: AnimationClip = { kind: 'animation-clip', duration: 10, channels: [] };
+    await createWorldContext(world, [
+      animationPlugin((guid) => (guid === 'test/animation-clip-delta' ? clipPayload : undefined)),
+    ]);
+
+    registerClip(world, 10);
+    const built = defineAnimationGraph((b) => b.clip('test/animation-clip-delta'));
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    const graphH = world.allocSharedRef('AnimationGraph', built.value);
+
+    // `nodeSpeeds` defaults to 0 per node when unset (unlike `nodeWeights`,
+    // which defaults to 1) — must be explicit or the clip node never advances.
+    const e = world
+      .spawn({ component: AnimationPlayer, data: { graph: graphH, nodeSpeeds: [1] } })
+      .unwrap() as EntityHandle;
+
+    world.update(dt);
+
+    const ap = world.get(e, AnimationPlayer).unwrap() as unknown as { nodeTimes: Float32Array };
+    expect(ap.nodeTimes[0]).toBeCloseTo(dt, 5);
+  });
+});

package/src/__tests__/transform-target-playback.integration.test.ts

@@ -0,0 +1,198 @@
+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, Handle } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { AnimationPlayer } from '../animation-player';
+import { AnimationTargetId, bindAnimationTargets } from '../animation-target';
+import { defineAnimationGraph } from '../graph/define-animation-graph';
+import { animationPlugin } from '../plugin';
+
+const TARGET_ID = 'a95da0ec669189f98273e8f86d8ad9f2' as AnimationTargetIdValue;
+
+function transformClip(interpolation: 'LINEAR' | 'STEP' = 'LINEAR'): 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, 8, 12]),
+          interpolation,
+        },
+      },
+      {
+        targetId: TARGET_ID,
+        property: 'rotation',
+        sampler: {
+          input: new Float32Array([0, 1]),
+          output: new Float32Array([0, 0, 0, 1, 0, 0, 1, 0]),
+          interpolation,
+        },
+      },
+      {
+        targetId: TARGET_ID,
+        property: 'scale',
+        sampler: {
+          input: new Float32Array([0, 1]),
+          output: new Float32Array([1, 1, 1, 3, 5, 7]),
+          interpolation,
+        },
+      },
+    ],
+  };
+}
+
+async function setupPlayer(
+  clip: AnimationClip,
+  graph: boolean,
+): Promise<{ world: World; player: EntityHandle; target: EntityHandle }> {
+  const world = new World();
+  await createWorldContext(world, [scenePlugin()]);
+  await createWorldContext(world, [animationPlugin(graph ? () => clip : undefined)]);
+  const clipHandle = world.allocSharedRef('AnimationClip', clip);
+  const player = world
+    .spawn({ component: Transform, data: { pos: [10, 0, 0] } })
+    .unwrap() as EntityHandle;
+  world.addComponent(player, { component: Name, data: { value: 'Root' } }).unwrap();
+  if (graph) {
+    const built = defineAnimationGraph((builder) => builder.clip('test/animation-clip-target'));
+    expect(built.ok).toBe(true);
+    if (!built.ok) throw built.error;
+    const graphHandle = world.allocSharedRef('AnimationGraph', built.value);
+    world
+      .addComponent(player, {
+        component: AnimationPlayer,
+        data: {
+          graph: graphHandle,
+          nodeTimes: [0],
+          nodeWeights: [1],
+          nodeSpeeds: [0],
+          paused: true,
+          looping: false,
+        },
+      })
+      .unwrap();
+  } else {
+    world
+      .addComponent(player, {
+        component: AnimationPlayer,
+        data: {
+          clips: [clipHandle],
+          times: [0],
+          weights: [1],
+          speeds: [0],
+          paused: true,
+          looping: false,
+        },
+      })
+      .unwrap();
+  }
+  const target = world.spawn({ component: Transform, data: {} }).unwrap() as EntityHandle;
+  world.addComponent(target, { component: Name, data: { value: 'Hip' } }).unwrap();
+  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 { world, player, target };
+}
+
+function expectTrsAt(
+  world: World,
+  target: EntityHandle,
+  time: number,
+  interpolation: 'LINEAR' | 'STEP',
+) {
+  const transform = world.get(target, Transform).unwrap();
+  const alpha = interpolation === 'STEP' && time < 1 ? 0 : time;
+  expect([...transform.pos]).toEqual([
+    expect.closeTo(4 * alpha),
+    expect.closeTo(8 * alpha),
+    expect.closeTo(12 * alpha),
+  ]);
+  expect([...transform.scale]).toEqual([
+    expect.closeTo(1 + 2 * alpha),
+    expect.closeTo(1 + 4 * alpha),
+    expect.closeTo(1 + 6 * alpha),
+  ]);
+  expect(transform.quat[2]).toBeCloseTo(Math.sin((Math.PI / 2) * alpha), 4);
+  expect(transform.quat[3]).toBeCloseTo(Math.cos((Math.PI / 2) * alpha), 4);
+  expect(transform.world[12]).toBeCloseTo(10 + 4 * alpha, 4);
+}
+
+describe('generic Transform target playback', () => {
+  it.each([
+    'LINEAR',
+    'STEP',
+  ] as const)('samples direct translation, rotation, scale, and propagated world values with %s', async (interpolation) => {
+    const { world, player, target } = await setupPlayer(transformClip(interpolation), false);
+    for (const time of [0, 0.25, 0.5, 1]) {
+      world.set(player, AnimationPlayer, { times: [time] }).unwrap();
+      world.update(0);
+      expectTrsAt(world, target, time, interpolation);
+    }
+  });
+
+  it('drives the same Transform path from an AnimationGraph', async () => {
+    const { world, player, target } = await setupPlayer(transformClip(), true);
+    for (const time of [0, 0.25, 0.5, 1]) {
+      world.set(player, AnimationPlayer, { nodeTimes: [time] }).unwrap();
+      world.update(0);
+      expectTrsAt(world, target, time, 'LINEAR');
+    }
+  });
+
+  it('preserves pause, loop, replay, speed, blend, and non-positive weight semantics', async () => {
+    const { world, player, target } = await setupPlayer(transformClip(), false);
+    const clipHandle = world.get(player, AnimationPlayer).unwrap().clips[0] as unknown as Handle<
+      'AnimationClip',
+      'shared'
+    >;
+    world.set(player, AnimationPlayer, { paused: false, speeds: [2], times: [0] }).unwrap();
+    world.update(0.125);
+    expect(world.get(player, AnimationPlayer).unwrap().times[0]).toBeCloseTo(0.2);
+
+    world.set(player, AnimationPlayer, { looping: true, times: [0.95], speeds: [1] }).unwrap();
+    world.update(0.1);
+    expect(world.get(player, AnimationPlayer).unwrap().times[0]).toBeCloseTo(0.05);
+
+    world.set(player, AnimationPlayer, {
+      looping: false,
+      paused: true,
+      clips: [clipHandle, clipHandle],
+      times: [0, 1],
+      weights: [1, 1],
+      speeds: [0, 0],
+    });
+    world.update(0);
+    expect([...world.get(target, Transform).unwrap().pos]).toEqual([
+      expect.closeTo(2),
+      expect.closeTo(4),
+      expect.closeTo(6),
+    ]);
+
+    world.set(player, AnimationPlayer, { times: [1, 1], weights: [0, -1] }).unwrap();
+    world.update(0);
+    expect([...world.get(target, Transform).unwrap().pos]).toEqual([
+      expect.closeTo(2),
+      expect.closeTo(4),
+      expect.closeTo(6),
+    ]);
+
+    world.set(player, AnimationPlayer, {
+      clips: [clipHandle],
+      times: [0],
+      weights: [1],
+      speeds: [0],
+    });
+    world.update(0);
+    expect([...world.get(target, Transform).unwrap().pos]).toEqual([0, 0, 0]);
+  });
+});

package/src/animation-diagnostic.ts

@@ -0,0 +1,88 @@
+import type { World } from '@forgeax/engine-ecs';
+
+export type AnimationDiagnosticCode =
+  | 'animation-target-missing'
+  | 'animation-target-transform-missing'
+  | 'animation-target-id-duplicate'
+  | 'animation-target-owner-stale'
+  | 'animation-channel-missing'
+  | 'animation-target-morph-weights-missing'
+  | 'animation-morph-weight-count-mismatch';
+
+export interface AnimationDiagnosticDetail {
+  readonly player: number;
+  readonly clip: number;
+  readonly channel: number;
+  readonly targetId: string;
+  readonly reason:
+    | 'target-missing'
+    | 'transform-missing'
+    | 'target-id-duplicate'
+    | 'target-stale'
+    | 'channel-missing'
+    | 'morph-weights-missing'
+    | 'morph-weight-count-mismatch';
+  readonly target?: number;
+  readonly property?: 'translation' | 'rotation' | 'scale' | 'weights';
+  readonly expectedWeightCount?: number;
+  readonly actualWeightCount?: number;
+}
+
+export interface AnimationDiagnostic {
+  readonly code: AnimationDiagnosticCode;
+  readonly hint: string;
+  readonly detail: Readonly<AnimationDiagnosticDetail>;
+}
+
+export type AnimationDiagnosticListener = (
+  world: World,
+  diagnostic: Readonly<AnimationDiagnostic>,
+) => void;
+
+const emittedKeysByWorld = new WeakMap<World, Set<string>>();
+const listeners = new Set<AnimationDiagnosticListener>();
+
+/** Observe unique channel-level diagnostic facts for editor/runtime projection. */
+export function subscribeAnimationDiagnostics(listener: AnimationDiagnosticListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** @internal */
+export function isAnimationDevMode(): boolean {
+  const proc = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process;
+  if (proc?.env?.NODE_ENV === 'production') return false;
+  return Boolean((import.meta as { env?: { DEV?: unknown } }).env?.DEV) || proc !== undefined;
+}
+
+export function emitAnimationDiagnostic(world: World, diagnostic: AnimationDiagnostic): void {
+  if (!isAnimationDevMode()) return;
+  let emitted = emittedKeysByWorld.get(world);
+  if (emitted === undefined) {
+    emitted = new Set();
+    emittedKeysByWorld.set(world, emitted);
+  }
+  const { player, clip, channel, targetId, reason } = diagnostic.detail;
+  const emittedKey = `${player}|${clip}|${channel}|${targetId}|${reason}`;
+  if (emitted.has(emittedKey)) return;
+  emitted.add(emittedKey);
+
+  const frozen = Object.freeze({
+    ...diagnostic,
+    detail: Object.freeze({ ...diagnostic.detail }),
+  });
+  for (const listener of listeners) {
+    try {
+      listener(world, frozen);
+    } catch {
+      // Diagnostics must never break animation evaluation.
+    }
+  }
+
+  console.warn(frozen);
+}
+
+/** @internal */
+export function _resetAnimationWarnsForTests(world: World): void {
+  emittedKeysByWorld.delete(world);
+}

package/src/animation-player.ts

@@ -0,0 +1,84 @@
+// @forgeax/engine-animation - AnimationPlayer component (variable N-way SoA slots).
+//
+// Schema (10 fields, SoA variable arrays):
+//   clips:   'array<shared<AnimationClip>>'   (simulation-transient asset binding)
+//   times:   'array<f32>'                      (layer-3 zero — empty Float32Array)
+//   weights: 'array<f32>'                      (layer-3 zero — empty Float32Array)
+//   speeds:  'array<f32>'                      (layer-3 zero — empty Float32Array)
+//   graph:       'shared<AnimationGraph>'      (layer-3 zero — 0, no graph)
+//   nodeWeights: 'array<f32>'                  (layer-3 zero — empty Float32Array)
+//   nodeTimes:   'array<f32>'                  (layer-3 zero — empty Float32Array)
+//   nodeSpeeds:  'array<f32>'                  (layer-3 zero — empty Float32Array)
+//   paused:  'bool'                                (layer-2 false)
+//   looping: 'bool'                                (layer-2 true)
+//
+// The four parallel columns support up to N concurrent clips for crossfade
+// blending — the fixed 4-slot cap is retired (feat-20260713 M1 / w4). Slot i is
+// active when clips[i] != 0 (invalid handle = id=0). advanceAnimationPlayer
+// skips slot i when clips[i]=0.
+//
+// Graph mode (feat-20260713 M3 / w24, plan D-3): a SINGLE component surface hosts
+// both direct-write and graph-driven playback — no second peer component (the
+// requirements forbid a parallel component that splits the evaluation path). The
+// `graph` scalar carries a `shared<AnimationGraph>` handle; the three node-*
+// columns carry per-node runtime knobs (weight / seek-time / speed), indexed by
+// graph node index:
+//   - graph == 0 (no handle): clips[] / times[] / weights[] / speeds[] are the
+//     DIRECT-WRITE SSOT (the pre-M3 behaviour; consumers own the slots).
+//   - graph != 0: evaluateAnimationGraph (a before-advance system) is the SOLE
+//     writer of clips[] / times[] / weights[] / speeds[] — they become DERIVED
+//     output of the post-order graph evaluation, and any caller-written slot
+//     values are overwritten each frame. The effective weight of a node is its
+//     runtime weight (nodeWeights, default 1 per node) x its graph static weight
+//     (AC-07 orthogonal product); eval owns the seek-time via nodeTimes/nodeSpeeds
+//     and parks speeds[]=0 so advance does not re-advance it (D-7).
+//
+// Parallel-length contract (D-5): clips / times / weights / speeds are variable
+// `array<T>` columns set field-by-field (release-then-alloc per field), so the
+// ECS layer cannot cross-check their lengths. Consumers MUST write all four
+// columns at the SAME length every time; advanceAnimationPlayer's evaluation
+// entry validates this once per row and rejects a mismatch with the structured
+// `animation-player-slot-length-mismatch` error (player-errors.ts).
+//
+// Default-fallback contract (engine-ecs three-layer SSOT):
+//   layer 1 (caller) — explicit raw, e.g. `data: { clips: [h], weights: [1] }`
+//   layer 2 (this file) — `default:` on the field descriptor (paused / looping)
+//   layer 3 (engine-ecs) — typeDefault(fieldType): bool->false, array<T>->[]
+//
+// Unlike the retired fixed schema, a variable column does not tail-pad a short
+// write: `clips: [h]` stores length 1, NOT [h, 0, 0, 0]. The minimal call to
+// play one clip on slot 0 writes all four columns length-synced:
+//   data: { clips: [h], times: [0], weights: [1], speeds: [1] }
+//
+// Naming: single-semantic component drops the 'Component' suffix
+// (AGENTS.md §Component naming rule #1). Field names mirror common game
+// engine convention (Unity Animator / Godot AnimationPlayer speed/paused
+// /looping idioms).
+//
+// Decision anchors:
+//   - requirements IS-1 (SoA arrays) + AC-01 (variable N-slot, 6 field set)
+//   - requirements OOS-6 (no ECS-layer change; reuse the existing variable
+//     array<T> / array<shared<T>> vocab, mirroring MeshRenderer.materials)
+//   - feat-20260713 M1 plan D-1 (variable columns) / D-6 (speeds default [])
+//   - feat-20260713 M3 plan D-3 (graph handle + per-node runtime knobs extend
+//     the existing component; no second peer component) / D-7 (eval owns time)
+//   - charter P4 (consistent abstraction: single component surface)
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+export const AnimationPlayer = defineComponent('AnimationPlayer', {
+  // The render/animation owner re-resolves clip assets in the target World;
+  // playback clocks and weights remain portable simulation state.
+  clips: { type: 'array<shared<AnimationClip>>' },
+  times: { type: 'array<f32>' },
+  weights: { type: 'array<f32>' },
+  speeds: { type: 'array<f32>' },
+  // The graph evaluator owns this compiled runtime binding; portable playback
+  // controls and derived slots remain available to the simulation record.
+  graph: { type: 'shared<AnimationGraph>' },
+  nodeWeights: { type: 'array<f32>' },
+  nodeTimes: { type: 'array<f32>' },
+  nodeSpeeds: { type: 'array<f32>' },
+  paused: { type: 'bool', default: false },
+  looping: { type: 'bool', default: true },
+});