hyperframes-keyframes

HyperFrames Keyframes

Les keyframes sont un contrat de pose : états visibles, identité de sujet continue, exécution sécurisée avec seek, 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. N'utilisez references/keyframe-patterns.md qu'en cas de doute sur le mécanisme d'implémentation, et non pour le style visuel.

Limite de l'édition créateur

Les keyframes gèrent le mouvement visuel, pas l'assemblage des clips. Les coupes franches de plage source, le rognage, l'épissage et le réordonnancement appartiennent à /hyperframes-core : créez un élément multimé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 avec 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/crop non temporisé à l'intérieur du clip. Utilisez un tween court/set pour un punch sec et un tween pour un mouvement fluide.
Zoom ou recadrage fluide multi-état	Gardez un wrapper sujet actif et créez plusieurs états de zoom/recadrage comme une échelle de pose avec un easing par segment.
Panoramique, recadrage ou mouvement caméra Ken Burns	Animez la translation du wrapper ainsi que 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 beats de transformation étiquetés sur une timeline sécurisée avec seek.
Cut de raccord ou whip pan	/hyperframes-animation gère la transition visuelle ; /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 frames de raccord.
Recadrage et masque de reframe	Interpolez clip-path ou un masque sur un wrapper visuel intérieur pour recadrer/reframer sans changer le temps source. Les keyframes de polygone peuvent former une transition polygone/masque.
Cut de volet directionnel ou cut iris/révélation	Animez une limite de masque/clip sur des clips visuels qui se chevauchent ; /hyperframes-animation gère la chorégraphie de la transition.
Transition split-screen	Gardez les deux clips visuels placés par le core, puis keyframez leurs wrappers de crop/masque intérieurs et la géométrie du séparateur.
Retiming source constant	/hyperframes-core possède data-playback-rate normalisé (0.1..5) pour une image correcte à la sortie et un son avec préservation de la hauteur. Il est constant pour tout l'élément multimédia.
Rampes de vitesse source	Non pris en charge : il n'y a pas d'enveloppe de taux de lecture variable dans le temps. Prétraitez un actif multimédia dérivé, puis placez-le via le core.
Freeze / hold	Une pose visuelle, une frame 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, ce skill pour le mouvement visuel, et /hyperframes-audio pour les fondus, fondus enchaînés, l'automatisation du volume, le ducking/carve, ou les effets sur les pistes placées.

Un traitement de transition visuelle ou de recadrage n'est pas un rognage temporel ou un épissage de source. /hyperframes-core gère la timeline, le timing des clips et les plages source ; les keyframes ne font qu'animer la transition visible ou le recadrage sur les wrappers à l'intérieur de ces clips. Pour les recettes copiables combinant image et son, utilisez /hyperframes-core → references/creator-editing-recipes.md.

Procédure

1. Identifiez le sujet animé, les états visibles, l'état final et la durée d'exécution.
2. Choisissez le plus petit mécanisme qui prouve l'invite. Lisez references/keyframe-patterns.md uniquement si le mécanisme n'est pas clair.
3. Créez des keyframes sécurisées avec seek dans la durée d'exécution déclarée. Construisez de manière synchrone et enregistrez l'instance de la timeline.
4. Vérifiez avec hyperframes lint, hyperframes check, hyperframes keyframes, un --shot ciblé, et des captures d'écran aux moments de preuve.
5. Si la preuve échoue, corrigez les keyframes source et relancez le plus petit diagnostic qui a échoué avant le rendu.

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.
• 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 frame finale fait partie de l'animation, pas du nettoyage.
• Ne revenez pas à la position de repos sauf demande contraire.
• Ne terminez pas sur du noir sauf demande contraire.
• Si vous modifiez une scène de démarrage, préservez la mise en page, la copie, les actifs, les couleurs et l'état final, sauf si une refonte est demandée.

Règles d'exécution

GSAP :

• construisez de manière synchrone au chargement de la page
• utilisez gsap.timeline({ paused: true })
• enregistrez comme window.__timelines[compositionId]
• la clé d'enregistrement doit correspondre à data-composition-id
• n'appelez pas tl.play() pour un mouvement critique pour le rendu
• gardez les répétitions finies

Keyframes CSS :

• durée finie et nombre d'itérations fini
• délai déterministe
• animation-fill-mode: both
• utilisez data-start lorsque le timing appartient à un clip

Anime.js :

• créez de manière synchrone
• autoplay: false
• durée et boucles finies
• poussez chaque instance dans window.__hfAnime

WAAPI :

• duration finie
• fill: "both"
• construction déterministe
• la surface textuelle ne liste pas WAAPI ; vérifiez avec --shot (qui cherche WAAPI) et des captures d'écran

N'utilisez jamais pour un mouvement critique pour le rendu :

• Date.now()
• performance.now()
• Math.random() non ensemencé
• déclencheurs de survol/défilement
• minuteries
• timelines créées de manière asynchrone
• requestAnimationFrame non 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 qui touchent la même propriété.

Formes de keyframes

• Keyframes tableau : échelle de pose avec durée/easing par étape.
• Keyframes en pourcentage : timing exact à l'intérieur d'un tween.
• Tableaux de propriétés : changements multi-arrêts compacts.
• ease: "none" sur le parent lorsque chaque arrêt porte son propre easing.
• easeEach lorsque 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 continue ou FLIP. Divisez x/y/scale en plusieurs keyframes avec easing uniquement lorsque le spectateur doit ressentir des beats distincts ; chaque segment change de vélocité et peut être perçu comme un accroc.

Canaux

Préférez les canaux visuels/compositeur : x/y/z, xPercent/yPercent, scale, rotationX/Y/Z, skew, transformOrigin, svgOrigin, opacity, autoAlpha, clip-path, masques, variables CSS, valeurs SVG path/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'aide effectuant le mouvement du sujet.

Pour les changements de visibilité, utilisez autoAlpha sur la timeline GSAP enregistrée avec seek, 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 propriété visibility brute, et ne faites jamais de tween sur 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 de hiérarchie	élément partagé / FLIP
Le sujet parcourt un chemin visible	chemin de voyage
Le trait grandit ou trace	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 bougent avec un 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 se 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 (follow-through) vend l'énergie et la direction.
• Le dépassement (overshoot) 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 un ease-out brusque.
• Les éléments répétés ont besoin de décalages ordonnés, pas d'un timing identique.
• Les verrouillages finaux ont besoin de 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 mise à l'échelle ou voyage ; 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 à l'intérieur, déplacez les glyphes ou les bandes masquées, pas seulement les décorations autour du texte. Prenez des captures des frames lisibles.

SVG

Pour la croissance d'un 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 la preuve sous angle 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 à 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 lint
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 véritable sujet animé. Choisissez <times> pour la première frame, les poses de preuve, le final-moins-maintien, et le final exact. Choisissez <angle> uniquement lorsque la profondeur doit être prouvée.

Outil	Prouve
keyframes	cibles, arrêts explicites, chemins, traces, mouvement parent/enfant composé, arrêts CSS, enregistrement Anime
--shot	fantômes (ghosts), forme de la route, 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, lisibilité du texte, état complet, verrouillage final, queues de noir/réinitialisation

Si la preuve du sélecteur semble erronée :

1. relancez --json
2. trouvez la cible animée réelle
3. photographiez cette cible
4. prenez des captures de frames complètes
5. faites confiance aux pixels peints plutôt qu'aux logs

Lecture diagnostique

flat signifie qu'il n'y a pas de poses intermédiaires explicites. keyframes signifie qu'il y a des arrêts explicites. max est le temps total en secondes couvert par des keyframes. count est le nombre d'arrêts globaux. calls sont les points d'appel de la timeline. startAt et endAt sont les bords du window de la composition. offset est la position du clip sur la timeline core. empty signifie qu'aucune animation réelle n'est enregistrée. startsAtRun est le premier temps de la composition dans lequel ce clip a des keyframes. firstFrame et lastFrame sont les temps de début et de fin de la cible dans la timeline. target est ce qui est animé.

Lisez flat/keyframes pour repérer les keyframes accidentelles ``

[Le reste du texte est tronqué pour la traduction ; le contenu complet et fidèle doit être traduit de la même manière.]