heygen-com/css-animations

Que fait css-animations ?

Patrons d'adaptation d'animations CSS pour HyperFrames. À utiliser lors de la création d'images clés CSS, de temporisations basées sur animation-delay, d'animation-fill-mode, d'animation-play-state, ou de mouvements purement CSS qu'HyperFrames doit parcourir de manière déterministe lors de l'aperçu et du rendu.

Aperçu

Ce skill définit une série de modèles (patterns) permettant d'adapter les animations CSS standard pour qu'elles fonctionnent de manière fiable dans l'environnement HyperFrames. HyperFrames exige que les animations soient entièrement déterministes – c'est-à-dire qu'elles puissent être avancées ou reculées à n'importe quel point dans le temps sans perdre leur cohérence visuelle. Les animations CSS classiques, basées sur le temps réel, ne répondent pas naturellement à cette exigence.

Pourquoi c'est important

• Déterministe : Les animations CSS natives sont pilotées par le temps réel du navigateur. HyperFrames a besoin de pouvoir chercher (seek) une animation à un instant précis. Ce skill fournit les abstractions nécessaires pour découpler le temps réel du temps de l'animation.
• Gestion des délais : animation-delay est souvent utilisé pour créer des séquences. Ces délais doivent être convertis en décalages purs (offsets) dans le système de temporisation d'HyperFrames.
• Modes de remplissage : animation-fill-mode (forwards, backwards, both) doit être interprété correctement lorsque l'animation est parcourue hors de son cycle normal.
• État de lecture : animation-play-state (running, paused) doit être reflété dans l'état interne d'HyperFrames pour permettre la mise en pause et la reprise.

Modèles d'adaptation

1. Conversion des keyframes

Convertir les blocs @keyframes en une structure lisible par HyperFrames. Exemple :

/* CSS classique */
@keyframes slide-in {
  from { transform: translateX(-100%); }
  to   { transform: translateX(0); }
}

devient une structure de données déterministe :

{
  "timeline": [
    { "offset": 0, "properties": { "transform": "translateX(-100%)" } },
    { "offset": 1, "properties": { "transform": "translateX(0)" } }
  ]
}

2. Gestion d'animation-delay

Les délais (animation-delay: 2s) doivent être traités comme des décalages de début. Dans HyperFrames, cela devient :

// Au lieu d'attendre 2 secondes réelles, on décale le point de départ
const animationConfig = {
  keyframes: slideInKeyframes,
  startOffset: 2, // en secondes
};

3. Interprétation d'animation-fill-mode

Pour que HyperFrames puisse chercher (seek) avant le début ou après la fin de l'animation, il faut appliquer les propriétés correspondantes :

• forwards : appliquer les propriétés finales après la fin
• backwards : appliquer les propriétés initiales avant le début
• both : combiner les deux

switch (fillMode) {
  case 'forwards':
    // Conserver les propriétés finales en dehors de la plage
    break;
  case 'backwards':
    // Conserver les propriétés initiales en dehors de la plage
    break;
  case 'both':
    // Conserver les deux
    break;
}

4. Synchronisation d'animation-play-state

L'état de lecture (running/paused) doit être reflété dans l'état HyperFrames. Par exemple :

const playbackState = {
  isPaused: true // correspond à animation-play-state: paused
};

Intégration

1. Importez le module : import { createAnimationAdapter } from '@heygen/css-animations';
2. Définissez vos animations en utilisant les modèles ci-dessus.
3. Enregistrez-les dans le contexte HyperFrames de votre application.
4. Utilisez les contrôles de chronologie (seek, play, pause) fournis par HyperFrames pour interagir avec les animations.

Exemple complet

import { createAnimationAdapter } from '@heygen/css-animations';

const fadeInAdapter = createAnimationAdapter({
  keyframes: [
    { offset: 0, opacity: 0 },
    { offset: 1, opacity: 1 }
  ],
  duration: 1,
  delay: 0.5,
  fillMode: 'both'
});

// Usage dans HyperFrames
hyperframes.seek(0.3); // Va chercher à 0.3s → affiche 30% de l'animation

Dépannage

• Problème : L'animation ne se comporte pas comme prévu lors du seek.
  • Solution : Vérifiez que tous les keyframes sont correctement convertis, et que le fillMode est bien défini.
• Problème : Les délais ne sont pas respectés.
  • Solution : Assurez-vous que animation-delay est bien converti en startOffset dans le modèle.
• Problème : L'état paused n'est pas conservé.
  • Solution : Vérifiez que animation-play-state est bien synchronisé avec l'état HyperFrames.

Références

• Documentation CSS @keyframes
• Guide HyperFrames sur les animations
• Spécification CSS Animations

Licence

MIT