HyperFrames Core
HyperFrames génère des vidéos à partir de HTML. Une composition est un fichier HTML dont le DOM déclare le timing avec des attributs data-*, dont le runtime d'animation est adressable, et dont la lecture multimédia est gérée par le framework.
Cette compétence est le contrat technique. Les autres aspects résident dans des compétences soeurs :
hyperframes-animation— règles de mouvement atomiques + blueprints de scène + adaptateurs par runtime (GSAP, Lottie, Three, Anime.js, CSS, WAAPI, TypeGPU)hyperframes-creative— palettes, typographie, narration, planification des beats, audio-réactifhyperframes-media— TTS, transcription Whisper, suppression d'arrière-plan, sous-titreshyperframes-registry— installation de blocs et composants (hyperframes add)hyperframes-cli— commandes de boucle de développement (lint / validate / preview / render)
Pour les projets Tailwind v4 (hyperframes init --tailwind), voir references/tailwind.md — le contrat runtime navigateur est distinct de la configuration Tailwind v3 de Studio.
Routage
| Vous voulez… | Lisez |
|---|---|
| Voir une composition minimalement rendable | references/minimal-composition.md |
| Choisir entre une architecture monolithique mono-fichier et une architecture modulaire en sous-compositions | references/composition-patterns.md |
Structurer un index.html modulaire (orchestrateur + emplacements + audio racine) | references/composition-patterns.md |
| Choisir un archétype de sous-composition (contenu / pilotage seul / fusion multi-scène / audio-réactif) | references/composition-patterns.md |
Rechercher un attribut data-* (racine, clip, hôte de sous-composition, alias hérités) | references/data-attributes.md |
Utiliser class="clip" correctement | references/data-attributes.md |
Choisir un data-track-index ; chevauchement sur la même piste ; track-index vs CSS z-index | references/tracks-and-clips.md |
Synchroniser un clip par rapport à un autre (data-start="intro + 2", chevauchement fondu, chaînes) | references/tracks-and-clips.md |
Câbler une sous-composition (attributs hôte, wrapper <template>, variables par instance) | references/sub-compositions.md |
Animer dans une sous-composition (gsap.fromTo vs gsap.from, comportement retour en arrière) | references/sub-compositions.md |
Déclarer des variables (types, options supplémentaires, valeurs par défaut, --strict-variables en CI) | references/variables-and-media.md |
Placer <video> / <audio>, régler le volume, rogner avec data-media-start | references/variables-and-media.md |
Construire une timeline adressable (en pause, construction synchrone, piège gsap.set scène ultérieure) | references/determinism-rules.md |
Éviter l'état non-déterministe (horloges, Math.random, repeat: -1, formule de répétition finie) | references/determinism-rules.md |
Savoir ce qui peut / ne peut pas être animé (liste blanche propriétés visuelles ; pas display/visibility) | references/determinism-rules.md |
Adapter le texte et éviter le débordement (signature fitTextFontSize, règle <br>, contrat de mise en page) | references/determinism-rules.md |
| Créer un mouvement plein écran avec arrière-plans partagés | references/full-screen-motion.md |
Travailler dans un projet Tailwind v4 (init --tailwind) | references/tailwind.md |
Pour les spécificités du runtime d'animation (API GSAP, Lottie, Three.js, etc.) allez dans hyperframes-animation → adapters/<runtime>.md.
Structure de Composition
Deux formes racines ; elles ne sont pas interchangeables.
- Autonome (le
index.htmlde premier niveau) — le<div data-composition-id="…">racine se trouve directement dans<body>. Pas de wrapper<template>. Envelopper une racine autonome dans<template>cache tout le contenu au navigateur et casse le rendu. - Sous-composition (un fichier chargé via
data-composition-src) — le<div data-composition-id="…">racine doit être enveloppé dans<template>. Sans le wrapper, le runtime ne peut pas l'extraire ni le monter.
⚠ Règle de transport des sous-compositions : le runtime clone uniquement le contenu de
<template>dans le DOM actif. Tout ce qui est en dehors du template — y compris<head>et les blocs<style>/<script>/<link>qui vivent dans<head>— est ignoré. Placez les blocs<style>et<script>à l'intérieur de<template>, pas dans<head>.⚠ Règle d'ID hôte : dans le fichier hôte, le
data-composition-idsur l'emplacement doit exactement correspondre audata-composition-iddu template intérieur et à la cléwindow.__timelines["<id>"]. N'ajoutez pas de suffixes-mount/-slot/-host.
Voir references/sub-compositions.md pour la forme du fichier, le câblage hôte, les exemples de pièges et la liste de vérification de pré-rendu.
La racine doit être dimensionnée (bogue de mise en page silencieux)
La racine autonome doit établir une boîte explicitement dimensionnée, et chaque ancêtre entre elle et un élément height: 100% doit avoir une hauteur résolue. Si la racine ou un wrapper intermédiaire n'a pas de hauteur, un conteneur de contenu flex/height:100% s'effondre à ~0 et le contenu s'entasse dans le coin supérieur gauche (coupant souvent le premier glyphe à x=0). lint, validate et inspect ne détectent pas cela — inspect substitue le data-width/data-height rédigé à une racine effondrée et signale "0 problèmes de mise en page".
<body style="margin: 0">
<div
id="root"
data-composition-id="main"
data-width="1920"
data-height="1080"
data-duration="5"
style="position: relative; width: 1920px; height: 1080px; overflow: hidden"
>
<!-- Centrage robuste : position:absolute + inset:0 remplit la racine dimensionnée quel que soit
les wrappers intermédiaires ; ou utilisez un conteneur flex UNIQUEMENT si sa chaîne parente est dimensionnée. -->
<section
class="clip"
data-start="0"
data-duration="5"
data-track-index="1"
style="position: absolute; inset: 0; display: grid; place-items: center; padding: 120px 160px; box-sizing: border-box"
>
<h1>Titre</h1>
</section>
</div>
</body>
Gardez le padding (≥80px) sur le conteneur de centrage — c'est la marge de sécurité du titre qui empêche les grands caractères de toucher le bord du cadre. Voir references/minimal-composition.md.
Contrat de Timeline (GSAP par défaut)
Chaque composition enregistre exactement une timeline GSAP.
- Créez avec
gsap.timeline({ paused: true })— le lecteur possède la lecture. - Enregistrez à
window.__timelines["<composition-id>"]; la clé doit exactement correspondre audata-composition-idde la racine. La syntaxe pointée (window.__timelines.<id> = tl) est équivalente lorsque l'id est un identifiant valide ; utilisez les crochets si l'id contient-. - Construisez la timeline de manière synchrone pendant le chargement de la page — pas dans
async,setTimeout,Promiseou les gestionnaires d'événements. Le moteur de rendu échantillonne après le chargement complet de la page ; toute construction de timeline différée manque l'échantillon. - La durée du rendu provient de
data-durationsur la racine, pas de la longueur de la timeline GSAP. Ne remplissez pas la timeline avec des tweens vides pour définir la durée. - Pour les sous-compositions, ne pas imbriquer manuellement les sous-timelines dans l'hôte (
master.add(sub)) ; le framework les pilote indépendamment.
Pour les runtimes non-GSAP (Lottie / Three / WAAPI / CSS / Anime.js / TypeGPU), le contrat équivalent vit dans hyperframes-animation/adapters/<runtime>.md. Voir references/determinism-rules.md pour le contrat runtime d'animation inter-runtime.
Règles Non-Négociables
Ces règles cassent le moteur de rendu — ou produisent des bogues visuels silencieux que lint/validate/inspect ne détectent PAS (règles 3, 7-8). (La construction synchrone de la timeline est couverte ci-dessus dans Contrat de Timeline.)
- Pas de
Math.random()/Date.now()/performance.now()pilotant les visuels — utilisez un PRNG à graine. - Pas de
repeat: -1. Utilisezrepeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)—floor, pasceil(ceildépassedata-durationet déclenche le lintgsap_repeat_ceil_overshoot;max(0, …)évite un répétition négative = infini). <video>/<audio>doit être un enfant direct de la racine hôte (index.html) — jamais dans un sous-comp<template>, jamais dans un<div>wrapper ; sinon il n'est jamais décodé et rend un écran blanc/noir (silencieux). Le framework possède la lecture : pas devideo.play()/audio.play()/currentTime = …. Une sous-composition ne peut pas piloter les éléments hôtes (sélecteur ouquerySelector), donc animez les médias hôtes depuis la timeline principale au temps global. Voirreferences/variables-and-media.md.- Pas de
gsap.set()sur les éléments de clips de scènes ultérieures (ils ne sont pas encore dans le DOM). Utiliseztl.set(selector, vars, time)à ou après ledata-startdu clip. - Pas d'animation de
display/visibility. Animezopacity/ les transformations ; le cycle de vie du clip gère l'affichage/masquage. - Pas de
<br>dans le texte du corps. Laissez le texte se retourner viamax-width. - Les éléments transformés doivent être de niveau bloc + dimensionnés.
transform/scaleX/scaleYest inopérant sur un<span>en ligne, et la mise à l'échelle d'un élément à largeur automatique (0px) n'affiche rien → barres/remplissages invisibles. Donnez-leurdisplay: block/inline-block/flex-item et unewidth/heightréelle (par exemplewidth: 100%dans un parent dimensionné). - Les éléments décoratifs positionnés absolument (badges, pastilles, étiquettes) qui pulsent ou dépassent (
yoyoscale,back.out) ont besoin de dégagement à leur taille de pic et ne doivent pas chevaucher un bordoverflow: hidden— sinon ils chevauchent un voisin ou sont rognés. Positionnez pour le plus grand cadre, pas celui au repos.
Édition de Compositions Existantes
- Lisez les fichiers réels avant d'éditer.
- Préservez le timing, les pistes, les ID, les variables et les chemins multimédia non liés.
- Faites correspondre les ID de composition existants et les clés de registre de timeline.
- Lorsque vous ajoutez un clip, choisissez un
data-track-indexnon chevauchant ou ajustez intentionnellement le timing environnant. - Lorsque vous ajoutez une sous-composition, vérifiez son
data-composition-idinterne avant de câbler l'hôte.
Validation
Utilisez hyperframes-cli pour les détails des commandes.
-
npx hyperframes lintréussit (0 erreurs) -
npx hyperframes validateréussit (0 erreurs console) -
npx hyperframes inspectréussit, ou le débordement est intentionnellement marqué - Projets avec sous-compositions :
npx hyperframes snapshot --at <midpoints>et inspectez chaque image