ONIKOSIOLA/video-editing-kit

Qualité HyperFrames — Portails de Vérification

Vue d'ensemble

L'écart entre une bonne exécution HyperFrames et une médiocre n'est pas la créativité — c'est la discipline de vérification. Les bonnes exécutions traitent chaque frame comme non prouvée jusqu'à ce que ses pixels aient été examinés, à plusieurs instants de recherche. Les exécutions médiocres font confiance au vérificateur et livrent la première chose qui passe le lint.

Principe fondamental : le linter vérifie les rects et les attributs ; seuls les pixels rendus disent la vérité. Ne déclarez jamais une frame comme terminée sans l'avoir vue.

Portails non-négociables

Travaillez dans CET ORDRE pour chaque frame que vous construisez ou éditez. Sauter un portail parce que « c'est un petit changement » est la raison pour laquelle la qualité baisse.

1. Lisez le bloc ## Video direction propre au storyboard et obéissez-lui plutôt qu'au boilerplate prédéfini. Lorsque le storyboard dit en minuscules et que le préréglage de frame.md dit en majuscules, c'est le storyboard qui gagne. La direction du projet prime sur les valeurs par défaut du préréglage.
2. Un mouvement dominant par frame. Si votre frame a deux éléments qui se résolvent en même temps, coupez-en un. Tout charger puis figer (« mode diaporama ») et tout faire flotter (« mode économiseur d'écran ») sont deux échecs.
3. Vérifiez vous-même les pièges mécaniques (tableau ci-dessous) en faisant une recherche dans votre propre fichier avant de le déclarer terminé.
4. Testez par seek dans un navigateur avant de signaler comme terminé. Clonez le <template>, enregistrez la timeline, et timeline.seek(t, false) à : t=0, chaque limite de scène ±0,05s, et la dernière frame. Capturez chacune. REGARDEZ-les. Un rapport de frame sans test de seek est une affirmation non vérifiée.
   • Piège suppressEvents : .seek(t) brut supprime les callbacks onUpdate — les compteurs/typages semblent cassés dans votre test mais fonctionnent dans le rendu. Passez toujours false.
5. Après TOUT ré-échantillonnage, redérivez data-start/data-duration sur les clips affectés. Les temps des tweens GSAP et les fenêtres de visibilité des clips sont deux systèmes séparés ; ré-échantillonner l'un sans l'autre crée des éléments invisibles ou des silences. C'est la source de régression numéro 1.
6. Après l'assemblage, prenez un snapshot de la vidéo complète à chaque limite de coupe et au milieu de chaque frame, et lisez vous-même la mosaïque d'images. Corrigez ce qui semble faux, reprenez le snapshot, puis seulement rendez.

Tableau des pièges mécaniques (recherchez-les dans votre propre fichier)

Piège	Symptôme	Correctif
id commence par un chiffre + querySelector("#...")	SyntaxError tue silencieusement l'enregistrement de la timeline → frame vide	Préfixez les ids par une lettre, ou utilisez getElementById d'abord
CSS transform: sur un élément animé par GSAP	GSAP écrase le décalage CSS lors du premier tween	Intégrez le décalage dans left/top ; les transformations appartiennent à GSAP uniquement
Absence de box-sizing: border-box sur les cartes rembourrées	Les largeurs augmentent, le centrage dérive, les cartes se heurtent	Définissez-le sur chaque carte rembourrée
@font-face pointant vers fonts.gstatic.com / tout CDN	Rendu non déterministe ; casse hors ligne	Fichiers locaux sous assets/fonts/, relatifs à la racine du projet
Calcul de chevauchement à l'œil	Les cartes ultérieures enterrent le texte des cartes précédentes	Calculez les rects avec getBoundingClientRect() au moment du maintien ; vérifiez que le texte clé de CHAQUE élément empilé est visible dans une capture d'écran
Résultats de chevauchement du vérificateur sur du texte serré/avec interlignage réduit	Faux positif (les rects se chevauchent, les glyphes non)	Vérifiez les pixels d'abord, puis data-layout-allow-overlap — ne supprimez jamais aveuglément
Capture d'écran étirée/recolorée dans un mockup de téléphone	Appareil non naturel	Rapport d'aspect natif toujours ; recadrez avec overflow:hidden, ne mettez jamais à l'échelle de manière non uniforme
Fichiers ._* AppleDouble sur des volumes externes	Casse les constructions/rendus	find . -name '._*' -delete avant l'assemblage/rendu
Node < 22	CLI échoue	Préfixez : export PATH="$HOME/.nvm/versions/node/v22*/bin:$PATH" (ou nvm use 22)

Modèle d'orchestration (constructions multi-frames)

• Un worker par frame, un fichier par worker ; les workers ne touchent jamais aux fichiers partagés.
• Stagiez les ressources partagées (polices, logos, captures d'écran) AVANT de distribuer les workers ; les paquets nomment des chemins exacts.
• Chaque paquet contient : le bloc de storyboard de la frame mot pour mot, le bloc global de direction Vidéo, le tableau des pièges ci-dessus, et l'exigence de test de seek.
• L'orchestrateur relance lint + check + inspection de mosaïque après l'assemblage, quoi que les workers aient rapporté — les auto-rapports des workers sont des affirmations, pas des preuves.

Drapeaux rouges — arrêtez-vous et vérifiez

• « Lint et check ont réussi, donc la frame est correcte » → les vérifications ne voient pas le texte enterré ni les silences. Regardez les pixels.
• « J'ai ré-échantillonné les tweens ; c'est fait » → avez-vous aussi ré-échantillonné les fenêtres data-* du clip ?
• « Je vais sauter le test de seek, le code est simple » → le bug de frame vide (sélecteur d'id numérique) était dans du code simple et seul un test de seek l'a attrapé.
• « La carte ne recouvre probablement pas l'autre » → calculez les rects ; puis capturez.
• « Une police CDN, ça va pour cette fois » → non ; les rendus doivent être sans réseau.

Tout cela signifie : exécutez le portail que vous alliez sauter.