Installation du plugin : Avant d'exécuter les commandes de configuration ou de fraîcheur, suivez les règles d'exécution du plugin lorsque cette compétence se trouve à l'intérieur d'un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.
Images clés HyperFrames
Les images clés sont un contrat de pose : états visibles, identité continue du sujet, exécution seek-safe, pixels vérifiés.
Utilisez hyperframes-animation pour les recettes de scène générales. 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, et non du style visuel.
Limite d'édition du créateur
Les images clés gèrent le mouvement visuel, pas l'assemblage de clips. Les coupures franches, les recadrages, les épissures et les réorganisations basées sur la source appartiennent à /hyperframes-core : un seul élément média par plage conservée, placé avec data-start et data-duration, et sélectionnez son décalage source avec data-media-start. Les plages adjacentes créent une coupure franche. Un fondu enchaîné utilise des clips qui se chevauchent sur différentes pistes plus des images clés d'opacité visuelle ; les fondus sonores utilisent /hyperframes-audio.
| Demande du créateur | Mécanisme réel |
|---|---|
| Punch-in / punch-out | Image clé scale avec translation x/y ou pourcentage sur un wrapper visuel/de recadrage non temporel à l'intérieur du clip. Utilisez un tween set/court pour un punch sec 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 | Animez la translation du wrapper plus l'échelle. La géométrie est créée ; il ne s'agit pas de suivi facial ou de recadrage sémantique automatique. |
| Mouvements de caméra enchaînés | Enchaînez des transformations étiquetées sur une seule timeline seek-safe enregistrée. |
| Coupe de raccord ou whip pan | /hyperframes-animation gère le transfert visuel ; /hyperframes-registry fournit les primitives ; les images clés préservent la géométrie, la direction et la vélocité 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/recadrer sans changer le temps source. Les images clés de polygone peuvent former une transition de polygone/masque. |
| Wipe directionnel ou coupure iris/révélation | Animez une limite de masque/clip sur des clips visuels qui se chevauchent ; /hyperframes-animation gère la chorégraphie du transfert. |
| Transfert d'écran partagé | Gardez les deux clips visuels placés par le core, puis créez des images clés pour leurs wrappers de recadrage/masque internes et la géométrie du séparateur. |
| Ralenti/accéléré source constant | /hyperframes-core gère data-playback-rate normalisé (0.1..10) pour une image sécurisée pour le rendu et un son avec préservation de la hauteur. Il est constant pour tout l'élément média. |
| Rampe de vitesse source | Une piste rate dans data-automation sur la <video>/<audio> (t en secondes de clip, v 0.1..10, interpolation log) ; elle l'emporte sur le taux constant. |
| Freeze / pause | Une pose visuelle, une image source finale ou une sous-composition terminée peut être maintenue. Le freeze arbitraire au milieu de la source n'est pas pris en charge ; prétraitez un segment fixe/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, croisements, automatisation du volume, ducking/carve, ou effets sur les pistes placées.
Une transition visuelle ou un traitement de recadrage n'est pas une coupe temporelle ou une épissure de source. /hyperframes-core gère la timeline, le timing des clips et les plages sources ; les images clés n'animent que le transfert visuel 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 mécanisme le plus petit qui prouve la demande. Lisez
references/keyframe-patterns.mduniquement si le mécanisme n'est pas clair. - Créez des images clés 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 images clés source et réexécutez le plus petit diagnostic d'échec 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.
- Image clé des canaux visibles, pas d'état d'assistance 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.
- L'image finale fait partie de l'animation, pas un nettoyage.
- Ne réinitialisez pas au repos sauf demande.
- Ne terminez pas sur le noir sauf demande.
- Si vous éditez une scène de départ, préservez la mise en page, le texte, les assets, les couleurs et l'état final, sauf demande de refonte.
Règles d'exécution
GSAP :
- Construisez au chargement de la page ou à l'intérieur de
document.fonts.ready, et enregistrez uniquement après la fin de la construction - utilisez
gsap.timeline({ paused: true }) - enregistrez comme
window.__timelines[compositionId] - la clé du registre doit correspondre à
data-composition-id - n'appelez pas
tl.play()pour un mouvement critique pour le rendu - gardez les répétitions finies
Images clés CSS :
- durée finie et nombre d'itérations
- délai déterministe
animation-fill-mode: both- utilisez
data-startlorsque le timing appartient à un clip
Anime.js :
- créez de manière synchrone
autoplay: false- durée et boucles finies
- poussez chaque instance vers
window.__hfAnime
WAAPI :
durationfiniefill: "both"- construction déterministe
- la surface textuelle ne liste pas WAAPI ; vérifiez avec
--shot(il cherche WAAPI) et des instantanés
N'utilisez jamais pour un mouvement critique pour le rendu :
Date.now()performance.now()Math.random()non initialisé- déclencheurs de survol/défilement
- minuteries
- 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 d'images clés
- Images clés de tableau : échelle de poses avec durée/easing par étape.
- Images clés en pourcentage : timing exact à l'intérieur d'un seul tween.
- Tableaux de propriétés : changements multi-états 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 continu ou FLIP. Divisez x/y/scale en plusieurs images clés avec easing uniquement lorsque le spectateur doit ressentir des battements distincts ; chaque segment change de vélocité et peut être perçu comme un accroc.
Canaux
Préférez les canaux compositeurs/visuels : x/y/z, xPercent/yPercent, scale, rotationX/Y/Z, skew, transformOrigin, svgOrigin, opacity, autoAlpha, clip-path, masques, variables CSS, valeurs de chemin SVG/dash, 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'assistance effectuant 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 mécanisme le plus petit 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 un itinéraire visible | voyage de chemin |
| Le trait grandit ou suit | dessin de trait |
| Une forme devient une autre forme | interpolation de forme |
| La limite de révélation est visible | clip, masque ou uniforme de shader |
| Plusieurs éléments se déplacent avec un ordre | stagger / délai indexé |
| Le texte lui-même se déplace | subdivision de ligne, mot, caractère ou bande |
| La surface se plie, s'étire ou recadre | contre-transformation parent/enfant |
| L'interface utilisateur a des états | machine d'état explicite |
| La scène a de la profondeur | DOM 3D, Three.js, ou images clés 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 maximale montre le mécanisme sans équivoque.
- Le suivi vend l'énergie et la direction.
- Le dépassement uniquement lorsque le sujet doit sembler élastique ou tactile.
- Le voyage à vitesse constante nécessite généralement
ease: "none". - Les états d'interface utilisateur discrets nécessitent généralement un ease-out net.
- 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 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 est également en train de redimensionner ou de voyager ; utilisez des révélations imbriquées après que le mouvement principal se soit 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 instantanés des 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 voyage en z, la rotation, le mouvement de la caméra/du monde, l'occlusion et l'ordre des calques 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 aucun croisement de profondeur, améliorez z/caméra/occlusion.
Canvas / WebGL
Image clé de la position de la caméra, de la cible de la caméra, de la transformation de l'objet, de l'opacité du matériau, des uniforms de shader et de l'intensité du post-traitement via un état déterministe. Rendez-vous à 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 "<sélecteur>" --shot "<fichier>" --samples <n>
npx hyperframes keyframes . --selector "<sélecteur>" --shot "<fichier>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<fichier>" --ghost --angle <angle>
npx hyperframes snapshot . --at <temps>
Choisissez <sélecteur> pour le sujet animé réel. Choisissez <temps> pour la première image, les poses de preuve, le maintien final moins, 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 l'itinéraire, 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]