HyperFrames Core
HyperFrames rend des vidéos à partir de HTML. Une composition est un fichier HTML dont le DOM déclare la temporisation avec des attributs data-*, dont le runtime d'animation est interruptible, et dont la lecture multimédia est gérée par le framework.
C'est le contrat de composition — comment construire un projet hyperframes. Le corps ci-dessous est le guide de construction ; les détails par sujet se trouvent dans references/ (index suivant), lisez à la demande. Les autres préoccupations se trouvent dans les sections sœurs du même skill — ../cli (boucle de dev) et ../registry (installer des blocs / composants) — et dans les skills de conception sœurs, /hyperframes-motion (recettes d'animation) et /hyperframes-design (palettes, typographie, préréglages de cadre). La carte des capacités dans ../SKILL.md dit ce que chacun couvre.
Références
| Fichier | Lisez-le pour… |
|---|---|
references/minimal-composition.md | démarrer à partir du plus petit squelette de composition renderisable |
references/composition-patterns.md | choisir monolithique vs modulaire ; structurer un index.html modulaire ; choisir un archétype de sous-comp |
references/data-attributes.md | rechercher n'importe quel data-* (racine / clip / hôte de sous-comp / alias hérités) ; utiliser class="clip" |
references/tracks-and-clips.md | choisir data-track-index, gérer le chevauchement / z-index sur la même piste, temporiser un clip par rapport à un autre |
references/sub-compositions.md | câbler une sous-composition (attributs hôte, <template>, variables par instance) et animer à l'intérieur |
references/variables-and-media.md | déclarer des variables ; placer <video> pour une lecture uniquement visuelle |
references/determinism-rules.md | construire une timeline interruptible ; interdictions du déterminisme ; liste autorisée des propriétés animables ; mise en page / ajustement du texte |
references/full-screen-motion.md | créer une animation plein écran avec des arrière-plans partagés |
references/storyboard-format.md | créer un plan STORYBOARD.md (+ le manifeste analysé) |
references/subagent-dispatch.md | mapper les verbes de répartition des sous-agents (fan-out parallèle / arrière-plan / attente) à votre harnais |
references/tailwind.md | travailler dans un projet Tailwind v4 (init --tailwind ; le contrat d'exécution diffère du Studio v3) |
Pour les spécificités du runtime d'animation (API GSAP, Lottie, Three.js, etc.) allez dans /hyperframes-motion → adapters/<runtime>.md.
Construire une composition
Deux formes racines (non interchangeables)
- Autonome (
index.htmlde niveau supérieur) —<div data-composition-id="…">racine se trouve directement dans<body>, pas de wrapper<template>(l'envelopper cache tout le contenu et casse le rendu). - Sous-composition (chargée via
data-composition-src) — la racine doit être enveloppée dans<template>.
⚠ Règle de transport : le runtime clone uniquement le contenu de
<template>; tout ce qui est à l'extérieur (y compris les styles/scripts<head>) est ignoré — mettez<style>/<script>à l'intérieur du template. ⚠ Règle d'ID hôte : ledata-composition-idde l'emplacement hôte doit exactement correspondre audata-composition-iddu template interne et à la cléwindow.__timelines["<id>"]— pas de suffixe-mount/-slot/-host.
Forme du fichier, câblage de l'hôte et liste de vérification pré-rendu → references/sub-compositions.md.
La racine doit être dimensionnée (bug de mise en page silencieux)
La racine autonome a besoin d'une boîte dimensionnée explicite (width/height en px), et chaque ancêtre jusqu'à un élément height:100% doit avoir une hauteur résolue — sinon un enfant flex/100% s'effondre à ~0 et le contenu s'empile dans le coin supérieur gauche. lint/validate/inspect ne détectent pas cela. Squelette → references/minimal-composition.md.
Une timeline en pause
Chaque composition enregistre exactement une gsap.timeline({ paused: true }) à window.__timelines["<id>"] (clé = data-composition-id racine), construite de manière synchrone au chargement de la page. Durée du rendu = data-duration racine, pas la longueur de la timeline. N'imbriquez pas manuellement des sous-timelines dans l'hôte. Contrat complet (y compris les runtimes non-GSAP) → references/determinism-rules.md + /hyperframes-motion/adapters/.
Règles non-négociables (bugs silencieux que lint/validate/inspect ne détecteront pas)
Affichées ici ; raisonnement complet dans la référence liée. Ne les violez pas :
- Pas d'horloges /
Math.randomnon ensemencé / réseau / état d'entrée au moment du rendu ; pas derepeat: -1(utilisez un nombre fini). →determinism-rules.md - Animer uniquement la liste autorisée des propriétés visuelles ; jamais
display/visibility; pas degsap.setsur les clips de scènes ultérieures. →determinism-rules.md - Pas de
<br>dans le texte du corps ; les éléments transformés doivent être de niveau bloc + dimensionnés ; les décoratifs absolus pulsés nécessitent un dégagement de pic. →determinism-rules.md <video>doit être un enfant direct de la racine hôte (jamais à l'intérieur d'un<template>/wrapper de sous-comp) ; le framework contrôle la lecture. →variables-and-media.md- Chaque
iddoit être unique sur la page assemblée ; à l'intérieur d'une sous-comp, préfixez les id avec l'id de la composition (#<id>-hero). Lesiden double de<video>/<img>rendent vide — le producteur injecte les images pargetElementById, et les doublons entre fichiers échappent àlint. →composition-patterns.md - Un remplissage de scène plein écran va sur un enfant à pleine largeur (
position:absolute; inset:0), jamais sur la racine de la composition elle-même — la composition d'images du producteur peut supprimer lebackgroundde l'élément racine (le cadre rend noir) même si l'aperçu/snapshotl'affiche correctement. →composition-patterns.md
Modifier des compositions existantes
- Lisez d'abord les fichiers. Préservez la temporisation, les pistes, les ID, les variables, les chemins multimédias non liés.
- Faites correspondre les ID de composition et les clés de timeline existants.
- Ajouter un clip : choisissez un
data-track-indexsans chevauchement ou ajustez intentionnellement la temporisation environnante. - Ajouter une sous-composition : vérifiez son
data-composition-idinterne avant de câbler l'hôte.
Validation
Exécutez la porte CLI (voir ../cli/SKILL.md → Workflow + Minimum Completion Gate pour la liste de vérification canonique lint / validate / inspect / snapshot / preview / render, y compris le test visuel de fumée requis pour les projets de sous-composition).