Mouvement sûr pour le seek
HyperFrames ne joue pas la timeline. Il la seeke (recherche) : pour chaque image, le moteur de rendu positionne la timeline au temps de cette image et capture la page. Avec HyperFrames 0.8.x, cela se fait avec trois workers en parallèle, chacun prenant une image sur trois, et chaque pas de seek recule de 1 ms puis avance pour se stabiliser. Ainsi, chaque image doit être une fonction pure de son temps. Tout ce qui dépend de ce qui a été rendu avant, de l'horloge ou du hasard est rendu différemment dans chaque worker, et le résultat est un élément manquant sur une image sur trois.
Ce bogue est invisible dans l'aperçu Studio (qui joue dans l'ordre) et dans les captures uniques. Dans la production d'où proviennent ces compétences, c'était le seul défaut qui parvenait au relecteur : le titre d'ouverture « bégayant et clignotant » pendant ses sept premières secondes.
Linter d'abord
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/seek-safe-motion/scripts/lint_motion.py" <video_dir>/video
Il lit index.html, src/*.tpl et les *.js à côté (scripts inline uniquement), affiche fichier:ligne: sévérité RÈGLE: raison ainsi que la correction, et se termine avec le code 1 en cas d'erreur (--strict fait aussi échouer les avertissements, --json pour les outils). Exécutez-le après chaque modification de la timeline et avant chaque rendu. Il est statique : il ne peut pas voir les variables calculées à l'exécution (il les compte comme « non vérifiables ») ni deux tweens se chevauchant dans le temps. Ceux-ci restent à votre charge, avec la reproduction ci-dessous. qa.py (render-qa) l'exécute également et signale un échec dans le rapport en cas d'erreur.
Les règles, et pourquoi chacune existe
- Toute clé dans les
fromVarsd'unfromToapparaît aussi dans sestoVars(SS001, erreur). Lorsque l'image d'un worker tombe exactement sur le début d'un tween, le pas de 1 ms en arrière ramène le tween à avant son début, et une clé qui n'existe que dansfromVarsn'est jamais réécrite. Le tween du titre étaitfromTo(sel, {yPercent: 110, opacity: 1}, {yPercent: 0}):opacity: 1ne vivait que dansfromVars, donc un worker a gardé le titre à une opacité de 0 pour le reste du tween. Écrivez{yPercent: 110, opacity: 1}à{yPercent: 0, opacity: 1}, ou untl.set()suivi d'untl.to(). Il en va de même pourstartAtdans unto()(SS002). immediateRender: falsesur chaquefromToaprès le temps 0 (SS003, avertissement). Sinon, le tween écrit ses valeurs de départ lors de la construction de la timeline, écrasant ce que les tweens précédents ont défini, et un seek au milieu de la timeline part d'un mauvais état.- Préférer
fromToàfrom(SS004, avertissement). Unfrom()se termine sur ce qu'était l'élément au moment de la construction ; une fois que des tweens antérieurs touchent l'élément, les workers ne sont plus d'accord. - Ne jamais animer
displayouvisibility(SS005, erreur). Ils ne peuvent pas être interpolés ; ils basculent à un point arbitraire du tween. Modifiez-les avec untl.set()de durée nulle à un moment explicite, et fondez avecopacityouautoAlpha. - Pas d'horloge, pas de hasard, pas de minuteurs (SS006, erreur) : pas de
Date,performance.now(),Math.random(),setTimeout,setIntervalourequestAnimationFramepour quoi que ce soit de visible. Une gigue de dactylographie ou une forme d'onde utilise un générateur à graine ; un minuteur d'appel affiché à l'écran est calculé à partir detl.time()dans leonUpdatede la timeline. - Une seule timeline en pause, enregistrée, jamais jouée (SS007, SS011, SS012). Créez-la avec
gsap.timeline({ paused: true }), construisez-la complètement (à l'intérieur dedocument.fonts.readylorsque les positions dépendent des métriques de texte), et seulement ensuite assignezwindow.__timelines["<id de la composition>"] = tl. Enregistrer une timeline vide avant la fin de la construction rend une vidéo vierge ;tl.play()entre en conflit avec les seeks du moteur de rendu. - Les défilements sont des
fromToavec un début et une fin explicites afin que chaque worker calcule le même décalage, limité au contenu réel pour qu'aucune ligne ou icône ne s'arrête net. - Jamais deux tweens sur la même propriété du même élément en même temps. Une réinitialisation de curseur qui tombait à l'intérieur du déplacement suivant laissait le pointeur au mauvais endroit après un seek. Non linté : vérifiez le tableau de temporisation de la build.
- Animer les transformations, pas la mise en page (SS009, avertissement) :
x,y,scale,clip-pathau lieu deleft,top,width,margin. Les tweens de mise en page refondent chaque image ethyperframes checkles signale commegsap_non_transform_motion. Un changement de largeur court sur un contrôle produit réel (un panneau latéral qui s'agrandit) peut être accepté lorsqu'il reproduit le produit. - Ne jamais tween un élément
.clip(SS010, erreur). HyperFrames contrôle la visibilité d'un clip viadata-startetdata-duration; animez un wrapper à l'intérieur. - Répétitions finies (SS008, avertissement).
repeat: -1n'est autorisé que sous unedata-durationracine finie ; calculez un compte avecMath.max(0, Math.floor(span / period) - 1). - Définir chaque état initial explicitement au temps 0. Un helper qui fait
gsap.set(sel, vars)devrait aussi fairetl.set(sel, vars, 0), afin que le retour au temps 0 restaure la première image au lieu de conserver le dernier état rendu par un worker.
Reproduire un bogue suspect avant le rendu
Le lint détecte des motifs ; une capture prouve des pixels. Pour un tween suspect commençant à t0 :
npx --yes hyperframes@<épinglé> snapshot . --at <t0 + 0.3> --no-end --describe false -o a
npx --yes hyperframes@<épinglé> snapshot . --at <t0>,<t0 + 0.3> --no-end --describe false -o b
L'image à t0 + 0.3 doit être identique dans a et b. Si elle diffère, le passage par le début du tween a changé l'état. Pour rejouer exactement un worker, faites des snapshots des images 0, 3, 6, ... dans cet ordre jusqu'à juste après le tween. Bissectez en réduisant de moitié la plage temporelle jusqu'à ce qu'il ne reste qu'un tween. Après le rendu, scan_render.py (render-qa) signale le même bogue comme une exécution WORKER PATTERN : des images aberrantes qui partagent toutes un même index d'image modulo 3.
Références
references/patterns.md: code avant et après pour chaque règle, les helpers qui maintiennent un template sûr (lineIn,init, dactylographie, défilements, clics curseur) et ce que le lint peut et ne peut pas voir. Lisez-le lors de l'écriture d'un nouveau helper ou de la correction d'une constatation du lint.