Installation des plugins : Avant les commandes de configuration ou de fraîcheur, suivez les règles d'exécution des plugins lorsque cette compétence se trouve à l'intérieur d'un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.
Keyframes HyperFrames
Les keyframes sont un contrat de pose : états visibles, identité de sujet continue, exécution seek-safe, pixels vérifiés.
Utilisez hyperframes-animation pour les recettes de scène larges. Utilisez hyperframes-cli pour la documentation complète des commandes. Utilisez references/keyframe-patterns.md uniquement lors du choix des mécanismes d'implémentation, pas du style visuel.
Limite d'édition du créateur
Les keyframes possèdent le mouvement visuel, pas l'assemblage de clips. Les coupes franches dans la plage source, le rognage, l'épissage et la réorganisation appartiennent à /hyperframes-core : créez un élément média par plage conservée, placez-le avec data-start et data-duration, et sélectionnez son décalage source avec data-media-start. Les plages adjacentes créent une coupe franche. Un fondu enchaîné utilise des clips superposés sur différentes pistes plus des keyframes d'opacité visuelle ; les fondus sonores utilisent /hyperframes-audio.
| Demande du créateur | Mécanisme véridique |
|---|---|
| Punch-in / punch-out | Keyframe scale avec x/y ou translation en pourcentage sur un wrapper visuel/de recadrage non temporisé à l'intérieur du clip. Utilisez un tween court/rapide pour un punch dur et un tween pour un mouvement fluide. |
| Zoom ou recadrage multi-état fluide | Gardez un wrapper de sujet actif et créez plusieurs états de zoom/recadrage comme une échelle de poses avec un easing par segment. |
| Pan, recadrage ou mouvement de caméra Ken Burns | Animer la translation du wrapper plus l'échelle. La géométrie est créée ; ce n'est pas un suivi de visage ou un recadrage sémantique automatique. |
| Mouvements de caméra enchaînés | Enchaînez des battements de transformation étiquetés sur une seule timeline seek-safe enregistrée. |
| Match cut ou whip pan | /hyperframes-animation possède le transfert visuel ; /hyperframes-registry fournit les primitives ; les keyframes préservent la géométrie, la direction et la vélocité créées. Il n'y a pas de découverte automatique de trame de correspondance. |
| Recadrage par rognage et masque | Interpolez clip-path ou un masque sur un wrapper visuel intérieur pour recadrer/recadrer sans changer le temps source. Les keyframes de polygone peuvent former une transition polygone/masque. |
| Coupe par balayage directionnel ou iris/révélation | Animez une limite de masque/rognage à travers des clips visuels superposés ; /hyperframes-animation possède la chorégraphie du transfert. |
| Transfert d'écran partagé | Gardez les deux clips visuels placés par le noyau, puis keyframez leurs wrappers de recadrage/masque intérieurs et la géométrie du séparateur. |
| Retemporisation constante de la source | /hyperframes-core possède le data-playback-rate normalisé (0.1..10) pour une image rendue sûre et un son préservé en hauteur. Il est constant pour tout l'élément média. |
| Rampes de vitesse source | Une piste rate dans data-automation sur <video>/<audio> (t en secondes de clip, v 0.1..10, interpolation logarithmique) ; elle l'emporte sur le taux constant. |
| Gel / arrêt | Une pose visuelle, une trame source finale ou une sous-composition terminée peut être maintenue. Le gel arbitraire en milieu de source n'est pas pris en charge ; prétraitez une image fixe/un segment dérivé, placez-le comme son propre clip, puis reprenez avec une autre plage source. |
Lors de l'édition conjointe de l'image et du son, chargez /hyperframes-core, cette compétence pour le mouvement visuel, et /hyperframes-audio pour les fondus, fondus enchaînés, l'automatisation du volume, le ducking/creusage, ou les effets sur les pistes placées.
Une transition visuelle ou un traitement de recadrage n'est pas un rognage temporel de la source ou un épissage. /hyperframes-core possède la timeline, le timing des clips et les plages source ; les keyframes n'animent que le transfert visible ou le recadrage sur les wrappers à l'intérieur de ces clips. Pour des recettes combinées image/son copiables, utilisez /hyperframes-core → references/creator-editing-recipes.md.
Procédure
- Identifiez le sujet animé, les états visibles, l'état final et la durée d'exécution.
- Choisissez le plus petit mécanisme qui prouve l'invite. Lisez
references/keyframe-patterns.mduniquement si le mécanisme n'est pas clair. - Créez des keyframes seek-safe dans la durée déclarée. N'enregistrez l'instance d'exécution qu'après la fin de la construction ; la construction à l'intérieur de
document.fonts.readyest acceptable. - Vérifiez avec
hyperframes check(il exécute lint),hyperframes keyframes, un--shotciblé, et des instantanés aux temps de preuve. - Si la preuve échoue, corrigez les keyframes source et réexécutez le plus petit diagnostic défaillant avant de rendre.
Contrat
- Nommez le sujet en mouvement.
- Nommez les poses nécessaires pour prouver le mouvement prévu, y compris l'état final.
- Keyframez les canaux visibles, pas l'état d'aide caché.
- Préservez l'identité de l'objet lorsque la continuité est importante.
- Fondu enchaîné uniquement lorsque le mouvement prévu est un remplacement ou une dissolution.
- Maintenez les états lisibles ou sémantiques suffisamment longtemps pour être vus.
- La trame finale fait partie de l'animation, pas du nettoyage.
- Ne réinitialisez pas au repos sauf demande.
- Ne terminez pas sur du noir sauf demande.
- Si vous modifiez une scène de départ, préservez la mise en page, la copie, les assets, les couleurs et l'état final sauf si une refonte est demandée.
Règles d'exécution
GSAP :
- construire au chargement de la page ou à l'intérieur de
document.fonts.ready, et n'enregistrer qu'après la fin de la construction - utiliser
gsap.timeline({ paused: true }) - enregistrer en tant que
window.__timelines[compositionId] - la clé d'enregistrement doit correspondre à
data-composition-id - ne pas appeler
tl.play()pour un mouvement critique pour le rendu - garder les répétitions finies
CSS keyframes :
- durée et nombre d'itérations finis
- délai déterministe
animation-fill-mode: both- utiliser
data-startlorsque le timing appartient à un clip
Anime.js :
- créer de manière synchrone
autoplay: false- durée et boucles finies
- pousser chaque instance vers
window.__hfAnime
WAAPI :
durationfiniefill: "both"- construction déterministe
- la surface de texte ne liste pas WAAPI ; vérifier avec
--shot(il cherche WAAPI) et des instantanés
Ne jamais utiliser pour un mouvement critique pour le rendu :
Date.now()performance.now()Math.random()non seedé- déclencheurs de survol/défilement
- minuteurs
- une timeline enregistrée avant la fin de sa construction asynchrone
requestAnimationFramenon enregistré- boucles infinies
Squelette GSAP
const root = document.querySelector("[data-composition-id]");
const compositionId = root.dataset.compositionId;
const tl = gsap.timeline({ paused: true });
tl.addLabel("state-a", 0);
tl.to(".subject", {
keyframes: [
{ x: 0, opacity: 1, duration: 0.2 },
{ x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
{ x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
],
ease: "none",
});
window.__timelines = window.__timelines || {};
window.__timelines[compositionId] = tl;
Utilisez des étiquettes pour les états sémantiques. Utilisez des paramètres de position au lieu de délais enchaînés. Utilisez immediateRender: false pour les tweens from()/fromTo() ultérieurs touchant la même propriété.
Formes de keyframes
- Keyframes de tableau : échelle de poses avec durée/easing par étape.
- Keyframes en pourcentage : timing exact à l'intérieur d'un seul tween.
- Tableaux de propriétés : changements multi-étapes compacts.
ease: "none"sur le parent lorsque chaque arrêt a son propre easing.easeEachlorsque chaque segment doit partager la même sensation.
Ne copiez pas les distances numériques ou le timing des exemples. Dérivez-les de la géométrie et de la durée réelles de la composition.
Pour un sujet se déplaçant entre deux boîtes, préférez un seul tween de transformation continue ou FLIP. Divisez x/y/scale en plusieurs keyframes avec easing uniquement lorsque le spectateur doit ressentir des battements distincts ; chaque segment change de vélocité et peut être perçu comme un à-coup.
Canaux
Préférez les canaux compositeur/visuels : x/y/z, xPercent/yPercent, scale, rotationX/Y/Z, skew, transformOrigin, svgOrigin, opacity, autoAlpha, clip-path, masques, variables CSS, valeurs de chemin/dash SVG, transformations de caméra, uniforms de shader.
Évitez les canaux de mise en page/cycle de vie : top/left/right/bottom, width/height, margin/padding, display, visibility, création DOM tardive, superpositions d'aide effectuant le mouvement du sujet.
Pour les changements de visibilité, utilisez autoAlpha sur la timeline GSAP enregistrée et seekable, ou un tl.set() de durée nulle à une limite explicite. Ciblez uniquement un élément non-clip ou un wrapper à l'intérieur du clip ; ne ciblez jamais .clip lui-même. Ne tweenez jamais la visibility brute avec une durée, et ne tweenez jamais display.
Choix du mécanisme
Choisissez le plus petit mécanisme qui prouve l'invite :
| Besoin | Mécanisme |
|---|---|
| Même sujet change de boîte ou hiérarchie | élément partagé / FLIP |
| Le sujet parcourt un itinéraire visible | voyage sur chemin |
| Le trait grandit ou trace | dessin de trait |
| Une forme en devient une autre | interpolation de forme |
| La limite de révélation est visible | clip, masque, ou uniforme de shader |
| De nombreux éléments bougent avec ordre | stagger / délai indexé |
| Le texte lui-même bouge | subdivision de ligne, mot, caractère ou bande |
| La surface se plie, s'étire ou recadre | contre-transformation parent/enfant |
| L'interface a des états | machine d'état explicite |
| La scène a de la profondeur | DOM 3D, Three.js, ou keyframes de caméra/objet WebGL |
Les mécanismes peuvent se combiner, mais chacun doit clarifier l'idée. La décoration n'est pas une preuve.
Timing
- Anticipation uniquement lorsqu'elle clarifie la cause ou la direction.
- L'accélération quitte le repos.
- La preuve de pic montre le mécanisme de manière indubitable.
- Le suivi exprime l'énergie et la direction.
- Le dépassement uniquement lorsque le sujet doit sembler élastique ou tactile.
- Le voyage à vitesse constante sur un chemin nécessite généralement
ease: "none". - Les états d'interface discrets nécessitent généralement une sortie brusque.
- Les éléments répétés nécessitent des décalages ordonnés, pas un timing identique.
- Les verrouillages finaux nécessitent des maintiens plus longs que les poses de transition.
- La fluidité signifie une vélocité continue sur le même sujet.
- Ne superposez pas les tweens qui écrivent la même propriété de transformation, sauf si la superposition est intentionnelle et vérifiée.
- Évitez d'animer de grands changements de
clip-path/masque pendant que la même surface héroïque se met également à l'échelle ou se déplace ; utilisez des révélations imbriquées après que le mouvement principal s'est stabilisé.
Texte
Préservez les boîtes de lignes, l'espacement des mots, la lisibilité et l'ajustement final. Si le texte se déplace à l'intérieur, déplacez les glyphes ou les bandes masquées, pas seulement les décorations autour du texte. Prenez un instantané des trames lisibles.
SVG
Pour la croissance du trait, préférez DrawSVGPlugin, puis stroke-dasharray/stroke-dashoffset. Pour l'interpolation de forme, préférez MorphSVGPlugin ; convertissez les primitives en chemins si nécessaire et divisez les silhouettes complexes en parties plus simples.
3D
L'échelle seule est une fausse profondeur. Utilisez la perspective sur un parent stable, transform-style: preserve-3d, le voyage en z, la rotation, le mouvement de la caméra/du monde, l'occlusion et l'ordre des couches lorsque les objets se croisent.
Utilisez un ou deux angles de diagnostic qui exposent la relation de profondeur. Si une preuve inclinée ne montre aucun croisement de profondeur, améliorez le z/la caméra/l'occlusion.
Canvas / WebGL
Keyframez la position de la caméra, la cible de la caméra, la transformation de l'objet, l'opacité du matériau, les uniforms du shader et l'intensité du post-traitement via un état déterministe. Rendez depuis le temps HyperFrames. Utilisez --ghost car les boîtes de marqueur ne peuvent pas voir le mouvement interne du canvas.
Preuve CLI
npx hyperframes check
npx hyperframes keyframes .
npx hyperframes keyframes . --json
npx hyperframes keyframes . --runtime all
npx hyperframes keyframes . --selector "<selector>" --shot "<fichier>" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<fichier>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<fichier>" --ghost --angle <angle>
npx hyperframes snapshot . --at <times>
Choisissez <selector> pour le véritable sujet animé. Choisissez <times> pour la première trame, les poses de preuve, la finale-moins-maintien et la finale exacte. Choisissez <angle> uniquement lorsque la profondeur doit être prouvée.
| Outil | Prouve |
|---|---|
keyframes | cibles, arrêts explicites, chemins, traces, mouvement composite parent/enfant, arrêts CSS, enregistrement Anime |
--shot | fantômes, forme de l'itinéraire, espacement temporel, projection DOM 3D, preuve de sélecteur ciblé |
--layout strip | mouvement sur place, chevauchements, contact, échelle/opacité subtiles, vagues de texte |
--ghost | canvas, WebGL, mouvement de shader, 3D rendu |
snapshot --at | masques […] (tronqué pour la traduction) |