MooT020/gsap-explainer

GSAP explainer — le niveau vidéo produite

Construit un explicateur HTML/SVG/GSAP autonome qui se lit comme une animation YouTube produite, pas un diaporama : une timeline GSAP par scène pour une chorégraphie dynamique, un mascotte de présentateur volant persistant, des mondes en couches avec profondeur, des populations de personnages, une « caméra » avec vignette et grain, et un lecteur interactif avec barre de recherche. Utilisez un harnais CSS uniquement pour des intégrations dans un entonnoir de vente ; utilisez CECI pour des vidéos de contenu de qualité YouTube.

La construction de référence est scaffold.html dans ce dossier de compétence — un exemple fonctionnel de 5 scènes (sujet : « Comment les intérêts composés font boule de neige ») avec chaque motif ci-dessous en contexte, rétention sans chevauchement. Il est livré avec GSAP retiré : exécutez python3 inline-gsap.py scaffold.html une fois (télécharge GSAP 3.13 dans un vendor/ ignoré par git, puis l'intègre) et ouvrez le fichier — il doit jouer. Lisez-le chaque fois qu'un motif ci-dessous n'est pas clair.

Commencez ici — le chemin qui ne peut pas échouer

1. Écrivez le script de scènes EN PREMIER sous forme de document markdown : par scène — horodatage, durée, VISUEL, texte À L'ÉCRAN, ligne VO. Terminez par une liste de vérification de précision et vérifiez chaque affirmation qu'il contient. Les durées des scènes deviennent le tableau SCENES ; les lignes VO deviennent la transcription sr-only.
2. Copiez scaffold.html vers <sujet>.html. Il a tous les pièges pré-corrigés : horloge du harnais, chrome de recherche, vols du présentateur, fonds de mondes, superpositions de caméra, personnages de population, mouvement réduit, transcription. Exécutez inline-gsap.py dessus et ouvrez-le avant de toucher à quoi que ce soit — il doit jouer.
3. Remplacez les scènes une par une, en gardant les cinq exemples fonctionnels comme source d'idiome jusqu'à ce que chacun soit remplacé : S0 = accroche sombre avec une révélation par retournement ; S1 = chute avec rebond physique ; S2 = vol/motionPath + DrawSVG ; S3 = la preuve de collision par chevauchement forcé (le motif pic) ; S4 = maintien de l'appel à l'action. Mettez à jour SCENES, FL, ACTS, CH_STARTS ensemble — ce sont des structures parallèles indexées par la scène.
4. AQ chaque scène avec des arrêts sur image (voir AQ), corrigez, puis publiez (fichier autonome).

N'écrivez jamais la chorégraphie d'une scène à partir de zéro quand un motif ci-dessous correspond — adaptez le motif. C'est comme ça que vous atteignez la barre quel que soit le modèle.

Contrat d'architecture (déjà câblé dans le squelette)

• Stage fixe 800×500 redimensionné au conteneur (fitScale). L'horloge de scène est setTimeout (tableau SCENES, secondes par scène ; dernière entrée 999 = maintien de l'appel à l'action ; advance() appelle done() dessus).
• Le texte/les puces/les légendes entrent via des primitives CSS (.fu fondu vers le haut, .pp pop, .fi fondu entrée) avec animation-delay en ligne — bon marché et rejouable. La chorégraphie héroïque est GSAP : runScene(i) (appelé depuis showScene) tue la timeline précédente et construit gsap.timeline() à partir de FL[i] (vol du présentateur) + ACTS[i] (acte de scène).
• Chaque ACTS[i] DOIT commencer par des réinitialisations gsap.set(...) pour tous les éléments qu'il touche — les scènes se réactivent lors de la relecture/recherche et les tweens tués laissent des styles en ligne obsolètes.
• Les éléments appartenant à GSAP reçoivent la classe g-hero (ou vivent à l'intérieur d'un) et ne portent jamais .fu/.pp/.fi — un propriétaire par élément.
• pause()/resume() appellent curTl.pause()/play() ; le côté CSS est gelé par la classe .paused. La navigation reprend toujours la lecture (une scène fraîchement coupée en pause est à des entrées d'opacité 0 — ne jamais « chercher et rester en pause »).
• Lecteur : barre de progression cliquable (sceneAt(frac)), boutons précédent/suivant, touches ←/→, repères de chapitres (CH_STARTS), lecture automatique au défilement, pause automatique lors du changement d'onglet.
• La livraison est la piste visuelle silencieuse (le maître reste silencieux) ; la VO est livrée comme une variante d'aperçu <sujet>-vo.html séparée construite par le pipeline ElevenLabs (voir Production VO). La transcription sr-only EST le script VO. Le recalage sur une lecture = EXTENDRE SCENES[i] pour clip+1.5–2s (l'extension ne laisse jamais de battements en suspens ; seules les coupes le font).

La bibliothèque de motifs (adaptez, n'inventez pas)

Tous existent textuellement dans scaffold.html — copiez le plus proche.

• Vol du présentateur — FL[i] = [[fraction, x, y, pointant], ...]. Premier point de passage = dernier de la scène précédente (coupures sans couture). Les longues jambes font automatiquement une swoop via MotionPath (dans fly()). La pointe du crayon se trouve à un décalage d'acteur d'environ (−10, +95) : pour pointer vers une cible, garez le présentateur au-dessus-droite de celle-ci. Envoyez le présentateur hors scène (x=850) quand une scène a besoin du cadre.
• Chute avec poids — gsap.set(els,{y:-300,opacity:0}) puis .to(els,{y:0,opacity:1,ease:'bounce.out',stagger:.09}). Le décalage + le rebond EST la sensation physique. (layMarbles range les rangées à l'intérieur du récipient ; la largeur de rangée est 168, pas 180 — plus large et les gouttes traversent le mur.)
• Collision par chevauchement forcé (le pic de preuve) — deux barres tombent dans une seule piste qui ne peut pas contenir les deux ; la seconde tente de l'esquiver (x yoyo), échoue, se stabilise ; le segment de chevauchement apparaît avec back.out et brille (boxShadow yoyo repeat:-1) ; puis deux mini-personnages des deux badges apparaissent à l'intérieur. Intention → échec → conséquence est ce qui le rend vivant.
• Versement/transformation — le conteneur pivote (transformOrigin au bec), le contenu sort un par un sur des arcs motionPath ({path:[{x,y},{x,y}],curviness:1.6}, ease:'power1.in'), atterrit en rangée, se fond en fondu croisé dans la nouvelle forme dessinée avec DrawSVG.
• Révélation par retournement — un ✓ tentant apparaît (back.out(2.4)), gigote, puis échange pour le ✗ qui s'écrase (scale:3→1, power4.out) + un flash d'arrière-plan (backgroundColor yoyo).
• Tentation puis fracas — la réponse brille/pulse (scale yoyo ×3), puis meurt (opacity:.25, scale:.92, rotation:-3, power2.in) ; la bonne réponse s'imprime après.
• Slam de timbre — gsap.set(stamp,{opacity:0,scale:2.6,rotation:-14}) → .to({opacity:1,scale:1,rotation:0,duration:.35,ease:'power4.out'}).
• DrawSVG — gsap.set(path,{drawSVG:'0%'}) → .to({drawSVG:'100%'}) ; retour = dessiner à 72% puis inverser rapidement. DrawSVG écrase stroke-dasharray — les lignes en tirets se rendent pleines pendant le dessin ; concevez en conséquence.
• Population comme personnages (le geste Kurzgesagt le plus emblématique) — usine de mini-personnages minion(size, badges) : les quantités sont de petits personnages, pas des points. Essaim ambiant de 3 personnages sur 35–55s de boucle CSS ; les groupes contiennent leur distribution de personnages ; le moment de preuve est un personnage portant les deux badges.
• Fondu de coupure de scène (intégré dans runScene) — deux panneaux inclinés (accent en tête, encre en traîne .09s) balayent la scène à chaque coupure. Laissez-le ; c'est le gain de « vraies transitions » le moins cher. Idées de scènes riches en accessoires à voler : un personnage de page vivante, une ruine de surligneur, un classeur, une aiguille de jauge, une course de barres de progression.

La suite de plugins gratuits (GSAP 3.13 — TOUS gratuits depuis l'acquisition par Webflow)

inline-gsap.py télécharge + intègre le cœur + DrawSVG + MotionPath + MorphSVG, SplitText, Physics2D, PhysicsProps, CustomEase, CustomWiggle, CustomBounce, Flip, ScrambleText. Tout est sous licence libre. inline-gsap.py <fichier> injecte tout + un bloc registerPlugin au marqueur <!--GSAP_INLINE--> ; --refresh échange la suite dans un fichier déjà intégré. Motifs éprouvés (tous présents dans le squelette) :

• Cascade de caractères SplitText — diviser UNE FOIS à l'initialisation via un registre (splitOnce(key,sel) avec cache dans SPL{} — re-diviser à chaque réexécution de scène imbrique des spans). Coup de pied : caractères depuis {opacity:0,y:14}, décalage .016, début ≤.15s. Mot héroïque : caractères depuis {y:-64,rotation:-9} avec back.out(1.9) décalage .07 ; ou {scale:2.7} power4 décalage .11 = slam de timbre. Les scènes se cachent via opacité (pas display:none) pour que la division à l'init soit sûre.
• Verrouillage de définition ScrambleText — une ligne de révélation se brouille en place : scrambleText:{text:'≥ 1',chars:'<>=~≠≤≥',speed:.6}. Préférez les échappements JS \u pour les symboles dans les chaînes JS. Des ensembles de caractères thématiques (symboles mathématiques pour les définitions) se lisent mieux que 'upperCase' — un long brouillage aléatoire en majuscules ressemble à un glitch de chargement.
• Rétablissement CustomWiggle — CustomWiggle.create('wigSettle',{wiggles:4,type:'easeOut'}), puis rotation:'+=10', ease:'wigSettle' — oscille et REVIENT AU DÉPART, donc les valeurs relatives ne s'accumulent jamais entre les relectures. Utilisez pour : atterrissages de timbres, réactions de personnages, le tapotement de crayon du présentateur à l'arrivée (if(wp[i][3]&&!wp[i-1][3]) dans fly()).
• Chute avec écrasement CustomBounce — CustomBounce.create('thud',{strength:.58,squash:2.4}) crée des eases jumelés 'thud'+'thud-squash'. L'assistant drop(tl,targets,time,dur,stagger) exécute 3 tweens synchronisés : pop d'opacité, y avec 'thud', scaleX:1.45,scaleY:.55 avec 'thud-squash' (transformOrigin:'50% 100%' dans la réinitialisation). Strictement meilleur que bounce.out — l'écrasement EST le poids.
• Explosion Physics2D — burst(tl,scene,x,y,n,time,colors) : particules de célébration/débris où l'atterrissage n'a pas d'importance (pics de collision, timbres de victoire). Angles/vitesses indexés par graine ((i*53)%140) = relecture identique, pas de Math.random. Supprime les .pfx obsolètes à la réentrée ; fondu avant la fin de la scène pour que rien ne persiste.
• Fusion MorphSVG — le geste ultime Kurzgesagt : N objets « deviennent » le concept. Les éléments atterrissent en rangée → un chemin de capsule se fond dessus → morphSVG vers la silhouette de flèche pendant que fill se tweene (« mêmes objets, nouvelle forme », littéralement). La réinitialisation nécessite gsap.set(path,{morphSVG:D_ORIGINAL}) — un chemin morphié conserve son d muté.
• Flip : NE PAS UTILISER ici — dans un stage 800×500 à coordonnées absolues fixes, vous connaissez toujours le delta ; un simple tween y: est déterministe sous QA avec tl.pause(t), alors que la mesure à l'exécution de Flip casse le scrutation freeze-frame (et les callbacks ne se déclenchent pas sur les recherches supprimées). Flip n'est utile que dans les mises en page à reflow réel (listes pilotées par DOM, conteneurs responsifs). Un temps de « réclamation de place vacante » est un tween à delta connu.

Fabrication d'actifs (motifs 10x-pass — comment les accessoires cessent d'être des divs stylisées)

Plongée en profondeur : la discipline complète de génération d'actifs (ordre de construction, usines, contrats SVG, portes de qualité) vit dans la compétence explainer-assets — utilisez-la à chaque CRÉATION ou reconstruction d'actif ; cette section est la référence rapide.

• L'autocollant en une recette — profondeur entièrement à partir de box-shadow en couches : goutte d'encre dure vers le bas-droite (3px 3px 0 var(--ink)) + inset 0 2px 0 rgba(255,255,255,.3-.5) brillance supérieure + inset 0 -3px 0 rgba(0,0,0,.1) ombre inférieure + inset 0 0 0 1-2px rgba(255,255,255,.14) bordure de découpe. Les inserts translucides fonctionnent sur N'IMPORTE QUELLE couleur de fond, donc un seul passage CSS sur .xchip/.qbar/.stamp/.l3 span élève chaque variante, claire et foncée. Gardez une échelle de rayons (sm 10 / base 13 / lg 16) et UNE direction de lumière (haut-gauche) sur tout le film.
• Remplissage plat deux tons — remplacez background:rgba(...) par linear-gradient(180deg, plus clair, base) + les inserts brillance/ombre. La couleur sémantique survit ; la surface se lit comme éclairée.
• Recette de récipient artisanal (seaux/pots/tasses) — ellipse d'ombre de base → corps dégradé → 2 bandes de cerceau effilées avec surbrillance blanche 1px → anneau de bord + une ELLIPSE D'OUVERTURE INTÉRIEURE PLUS FONCÉE (cette seule ellipse foncée fait qu'une bouche se lit en 3D) → courbe spéculaire douce. Interpolez les extrémités des bandes le long des côtés du trapèze.
• Art linéaire artisanal en un sélecteur — filter:drop-shadow(0 1.5px .5px rgba(0,0,0,.17)) statique sur tous les traits dessinés donne à chaque flèche/boîte un dessous deux tons et se révèle AVEC l'animation DrawSVG (le filtre est indépendant de dashoffset).
• Décorez les accessoires pilotés par GSAP avec des pseudo-éléments — ::before/::after (lignes réglées, bandes de ruban, fissures, lignes de ménisque) suivent automatiquement la transformation de la timeline : zéro nouvelle chorégraphie, zéro changement d'empreinte. Suivez quels pseudo sont « pris » par classe — les collisions sont silencieuses.
• Personnages d'usine : ids uniquement sur les singletons — le présentateur (une seule instance) peut porter des dégradés/spéculaires suffixés par uid ; une usine multi-inline (mini-personnages) doit rester sans id (remplissages simples uniquement) ou les ids se dupliquent dans le document.
• Préservez le contrat de chorégraphie tout en refabriquant — construisez un inventaire de sélecteurs à partir du script EN PREMIER ; les sélecteurs positionnels sont des mines terrestres (.bkt3 path = PREMIER chemin doit rester le corps tweéné — commencez par des ellipses, pas des chemins). Les nouvelles transformations décoratives vont sur des <g> d'emballage.
• Avertissement sur la brillance sans danger pour le texte — sur les puces portant du texte SplitText/héroïque, la brillance doit être des box-shadow inset (peint SOUS le texte), jamais une superposition ::before positionnée (peint SUR les caractères et les assombrit).
• Recette de pile de papier + coin plié (toute feuille d'accessoire) — 2 rectos arrière décalés (rotation ±0.6–1.5°, crème plus foncée, overflow:visible sur le svg), triangle d'ombre de coin coupé + rabat plié, une règle de marge, chemin de lueur en haut à gauche. Empreinte inchangée, seulement du débord visuel.
• Kit de façade de tiroir/meuble — recto avant + bande de brillance supérieure + plaque d'étiquette + barre de poignée encastrée + ligne d'ombre de profondeur inter-unité ; paramétrez la palette pour l'unité surlignée, conservez sa classe d'animation.
• Nuage vectoriel deux tons — ellipse de base teintée + 3 cercles blancs superposés + une ellipse supérieure plus claire ; recolorizez la teinte de base par variante d'ambiance.
• Superposition de carte technique — svg enfant positionné absolument (grille réglée faible + 4 repères de coin) comme premier enfant d'une carte : texture de dessin technique sans effet sur la classe tween de la carte ou son enfant texte.

La couche cinéma (motifs Kurzgesagt-pass)

• Grue de caméra #xplCam — un emballage de contenu uniquement À L'INTÉRIEUR de #xplStage contenant les scènes (couches d'environnement, acteur, vignette/grain restent à l'extérieur). Plongées par temps sur les chutes (~1.02–1.05, transformOrigin au héros), retraits sur les révélations, remise à l'échelle 1 dans runScene à chaque coupure. Ne mettez jamais #xplStage lui-même à l'échelle — c'est le travail de fitScale. La scène pic mérite UN seul lent recul ininterrompu sur tout son acte. Vérifiez le risque de clip par rapport aux limites VISIBLES de la pilule/accessoire, pas des conteneurs pleine largeur.
• Poignée de jeu d'acteur du présentateur actorBody — div .xpl-actor > [data-host], indépendante de fly() (x/y extérieur) et armEl. Assistants : saut (y-8 yoyo), inclinaison (±4° vers la cible pointée), sursaut (recul+ inclinaison), rotation à 360° sur la plus grande victoire. Réinitialisez chaque coupure. Personnalité d'entrée des mini-personnages : jeter un coup d'œil depuis un bord (décalage x → 0) AVANT l'apparition.
• Lumière d'accentuation — un #xplGlow radiale floue partagée (mix-blend-mode:screen, teinte via var CSS), positionnée et épanouie derrière l'objet héroïque au plus grand temps de chaque scène, réinitialisée par coupure. Sensation « éclairé » instantanée pour ~15 lignes.
• Dégradation temporel — ensemencez un filter de base sur #envFar à l'init (pour que les tweens interpolent, jamais ne sautent de none), puis adoucissez luminosité/teinte

…