suaveplan/openspec/changes/enterprise-gaming-r3f-animation/proposal.md

OpenSpec Change: enterprise-gaming-r3f-animation

• Change ID: enterprise-gaming-r3f-animation
• Package: @suaveplan/r3f-animation
• Category: gaming/character
• Target path: gaming/character/r3f-animation
• Status: PROPOSED
• Date: 2026-04-24
• Reference spec: /mnt/s/web/suaveplan/enterprise/r3f-animation.md

---

Summary

Deliver @suaveplan/r3f-animation on the genesis branch from scratch at enterprise quality. The package provides animation state machine, blend trees, and layers for React Three Fiber. An AnimationStateMachine manages named states with blend tree leaves and transition conditions; AnimationLayer enables masked additive/override layers (e.g. upper-body aim overlay); AnimationBlendTree interpolates between clips by blend parameters (speed, direction). @suaveplan/mixamo normalisation and @suaveplan/animation-events dispatch are integrated. Genesis adds structured errors, OTel blend-duration histogram, and 100% coverage.

---

Available workspace deps

@suaveplan/error, @suaveplan/types, @suaveplan/mixamo, @suaveplan/animation-events, @suaveplan/ik-solver, react, @react-three/fiber, @react-three/drei, three.

---

Public API surface

function AnimationController(props: AnimationControllerProps): JSX.Element
// stateMachine, blendParameters, layers, eventDispatcher

function useAnimation(): AnimationContext
// currentState, setParameter(), playAction(), crossFadeTo()

---

File layout

gaming/character/r3f-animation/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    core/
      state-machine/ (ts + md + types + test + index)
      blend-tree/ (ts + md + types + test + index)
      animation-layer/ (ts + md + types + test + index)
    context/animation-provider.tsx + md + test
    hooks/use-animation.ts + md + test
    components/
      AnimationController/ (tsx + md + test + stories + index)
  tests/integration.test.ts