Installation du plugin : Avant les commandes de configuration ou d'actualisation, suivez les règles d'exécution du plugin lorsque ce skill se trouve à l'intérieur d'un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.
HyperFrames Keyframes
Les keyframes sont un contrat de pose : états visibles, identité continue du sujet, runtime 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 gèrent le mouvement visuel, pas l'assemblage de clips. Les coupes franches par plage source, le rognage, l'épissage et le réordonnancement 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 forment une coupe franche. Un fondu enchaîné utilise des clips qui se chevauchent 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 translation x/y ou en pourcentage sur un wrapper visuel/recadrage non temporel à l'intérieur du clip. Utilisez un tween court et net pour un punch dur et un tween pour un mouvement fluide. |
| Zoom fluide multi-état ou recadrage | Gardez un wrapper sujet vivant et créez plusieurs états de zoom/recadrage sous forme d'échelle de poses avec un easing par segment. |
| Pan, recadrage ou mouvement de caméra Ken Burns | Animez la translation du wrapper plus l'échelle. La géométrie est créée ; ce n'est pas du suivi de visage ou du recadrage sémantique automatique. |
| Mouvements de caméra enchaînés | Enchaînez les battements de transformation étiquetés sur une timeline seek-safe enregistrée. |
| Match cut ou whip pan | /hyperframes-animation possède la transition visuelle ; /hyperframes-registry fournit les primitives ; les keyframes préservent la géométrie, la direction et la vitesse créées. Il n'y a pas de découverte automatique de cadre correspondant. |
| Recadrage et masque | Interpolez clip-path ou un masque sur un wrapper visuel interne pour recadrer/recentrer sans changer le temps source. Les keyframes polygonales peuvent former une transition polygone/masque. |
| Wipe directionnel ou iris/révélation | Animez une limite de masque/clip sur des clips visuels qui se chevauchent ; /hyperframes-animation possède la chorégraphie de transition. |
| Transition split-screen | Gardez les deux clips visuels placés par le core, puis créez des keyframes sur leurs wrappers de recadrage/masque internes et la géométrie du séparateur. |
| Ralenti/accéléré constant de la source | /hyperframes-core possède le data-playback-rate normalisé (0.1..10) pour une image et un son préservant la hauteur, sûrs pour le rendu. 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 sur image | Une pose visuelle, une image source finale ou une sous-composition terminée peut être maintenue. Le gel arbitraire au milieu de la source n'est pas supporté ; prétraitez un segment fixe/dérivé, placez-le comme son propre clip, puis reprenez avec une autre plage source. |
Lors de l'édition de l'image et du son ensemble, chargez /hyperframes-core, ce skill pour le mouvement visuel, et /hyperframes-audio pour les fondus, fondus enchaînés, automation de volume, ducking/carve, ou 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 animent uniquement la transition ou le recadrage visible 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.
- Choisissez le plus petit mécanisme qui prouve la demande. 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. Enregistrez l'instance runtime uniquement après la fin de la construction ; il est acceptable de construire à l'intérieur de
document.fonts.ready. - Vérifiez avec
hyperframes check(il exécute lint),hyperframes keyframes, un--shotciblé, et des snapshots aux moments de preuve. - Si la preuve échoue, corrigez les keyframes source et relancez le plus petit diagnostic échoué 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.
- Keyframe les canaux visibles, pas l'état caché des helpers.
- Préservez l'identité de l'objet lorsque la continuité est importante.
- Faites un fondu enchaîné uniquement lorsque le mouvement prévu est un remplacement ou une dissolution.
- Maintenez les états lisibles ou sémantiques assez longtemps pour être vus.
- La dernière image fait partie de l'animation, pas du nettoyage.
- Ne réinitialisez pas au repos sauf si demandé.
- Ne terminez pas sur du noir sauf si demandé.
- Si vous éditez une scène de démarrage, préservez la disposition, la copie, les assets, les couleurs et l'état final, sauf si une refonte est demandée.
Règles Runtime
GSAP :
- construire au chargement de la page ou à l'intérieur de
document.fonts.ready, et enregistrer uniquement après la fin de la construction - utiliser
gsap.timeline({ paused: true }) - enregistrer comme
window.__timelines[compositionId] - la clé du registre 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 finie et nombre d'itérations
- 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 dans
window.__hfAnime
WAAPI :
durationfiniefill: "both"- construction déterministe
- la surface de texte ne liste pas WAAPI ; vérifiez avec
--shot(il cherche WAAPI) et des snapshots
Ne jamais utiliser pour un mouvement critique pour le rendu :
Date.now()performance.now()Math.random()non ensemencé- déclencheurs hover/scroll
- timers
- 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 labels 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 en 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 étape porte son propre easing.easeEachlorsque chaque segment doit partager la même sensation.
Ne copiez pas les distances numériques ou les timings 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 continu ou FLIP. Divisez x/y/scale en plusieurs keyframes avec easing uniquement lorsque le spectateur doit ressentir des battements distincts ; chaque segment change de vitesse 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 disposition/cycle de vie : top/left/right/bottom, width/height, margin/padding, display, visibility, création DOM tardive, overlays helpers faisant le mouvement du sujet.
Pour les changements de visibilité, utilisez autoAlpha sur la timeline GSAP seekable enregistrée, 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 faites jamais de tween de durée sur la visibility brute, et ne faites jamais de tween sur display.
Choix du Mécanisme
Choisissez le plus petit mécanisme qui prouve la demande :
| Besoin | Mécanisme |
|---|---|
| Le même sujet change de boîte ou de hiérarchie | élément partagé / FLIP |
| Le sujet parcourt une route visible | path travel |
| Un trait pousse ou trace | stroke draw |
| Une forme devient une autre forme | shape interpolation |
| La limite de révélation est visible | clip, mask, ou shader uniform |
| Plusieurs éléments bougent avec ordre | stagger / indexed delay |
| Le texte lui-même bouge | line, word, character, ou band subdivision |
| La surface se plie, s'étire ou recadre | parent/child counter-transform |
| L'interface a des états | machine d'état explicite |
| La scène a de la profondeur | DOM 3D, Three.js, ou WebGL camera/object keyframes |
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 maximale montre le mécanisme de manière indubitable.
- Le suivi (follow-through) vend l'énergie et la direction.
- Le dépassement (overshoot) uniquement lorsque le sujet doit sembler élastique ou tactile.
- Un déplacement à vitesse constante sur un chemin nécessite généralement
ease: "none". - Les états d'interface discrets nécessitent généralement un ease-out prononcé.
- Les éléments répétés ont besoin de décalages ordonnés, pas d'un timing identique.
- Les verrouillages finaux nécessitent des maintiens plus longs que les poses de transition.
- La fluidité signifie une vitesse continue sur le même sujet.
- Ne chevauchez pas les tweens qui écrivent la même propriété de transformation, sauf si le chevauchement est intentionnel et vérifié.
- É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 ligne, l'espacement des mots, la lisibilité et l'ajustement final. Si le texte se déplace en interne, déplacez les glyphes ou les bandes masquées, pas seulement les décorations autour du texte. Prenez des snapshots d'images 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 déplacement 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 la preuve en angle ne montre pas de croisement de profondeur, améliorez z/caméra/occlusion.
Canvas / WebGL
Keyframe 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 à partir du 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 "<file>" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<file>" --ghost --angle <angle>
npx hyperframes snapshot . --at <times>
Choisissez <selector> pour le vrai sujet animé. Choisissez <times> pour la première image, les poses de preuve, la finale moins le 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 composé parent/enfant, arrêts CSS, enregistrement Anime |
--shot | fantômes, forme de la route, espacement temporel, projection DOM 3D, preuve de sélecteur ciblé |
--layout strip | mouvement sur place, chevauchements, contact, échelle/opacité subtile, vagues de texte |
--ghost | canvas, WebGL, mouvement de shader, 3D rendu |
snapshot --at | masques |
…
[tronqué pour la traduction]