HyperFrames Core
HyperFrames rend la vidéo à partir d'HTML. Une composition est un fichier HTML dont le DOM déclare la temporisation avec des attributs data-*, dont le runtime d'animation est déplaçable, et dont la lecture multimédia est gérée par le framework.
Cette compétence est le contrat technique — 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), à lire à la demande. Les autres préoccupations résident dans les compétences de domaine sœurs — hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. La carte des capacités dans /hyperframes décrit ce que chacune couvre.
Références
| Fichier | Lisez-le pour... |
|---|---|
references/minimal-composition.md | commencer par le squelette de composition rendable le plus petit |
references/composition-patterns.md | choisir entre monolithique ou modulaire ; structurer un index.html modulaire ; choisir un archétype de sous-comp |
references/data-attributes.md | consulter tout attribut 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>/<audio>, régler le volume, le rognage |
references/determinism-rules.md | construire une timeline déplaçable ; interdictions du déterminisme ; liste blanche des propriétés animables ; ajustement de la disposition / du texte |
references/full-screen-motion.md | créer des animations plein écran avec des arrière-plans partagés |
references/storyboard-format.md | rédiger un plan STORYBOARD.md (+ le manifeste analysé) |
references/review-loop.md | exécuter les passes de révision plan → esquisse → construction sur un tableau vivant — partagé par chaque workflow de planification de storyboard |
references/production-loop.md | transformer un plan approuvé en une vidéo livrée — les dépendances des étapes (audio, images, assemblage, transitions, sous-titres, vérification, livraison) qu'une construction libre suit directement |
references/brief-contract.md | les règles de base du brief — dérivation du mode (collaboratif / autonome), registre de champs partagés, invariants des questions (la question elle-même réside dans /hyperframes → la couche d'intention) |
references/brief-format.md | rédiger BRIEF.md — le document d'intention confirmé qu'un Setup de workflow écrit et que chaque étape ultérieure lit |
references/script-format.md | rédiger le SCRIPT.md optionnel de narration verrouillée |
references/subagent-dispatch.md | mapper les verbes de dispatch des sous-agents (fan-out parallèle / arrière-plan / attente) à votre harnais |
references/frame-worker-core.md | le contrat de rôle partagé du frame-worker — chaque constructeur de paquet de workflow narratif le préfixe au delta sub-agents/frame-worker.md de ce workflow |
references/tailwind.md | travailler dans un projet Tailwind v4 (init --tailwind ; le contrat d'exécution diffère de la v3 de Studio) |
Pour les spécificités du runtime d'animation (API GSAP, Lottie, Three.js, etc.), allez dans hyperframes-animation → adapters/<runtime>.md.
Construire une composition
Deux formes racines (non interchangeables)
- Autonome (
index.htmlde premier niveau) — la<div data-composition-id="…">racine se trouve directement dans<body>, pas d'encapsulation<template>(l'encapsuler cache tout le contenu et casse le rendu). - Sous-composition (chargée via
data-composition-src) — la racine doit être encapsulée dans<template>.
⚠ Règle de transport : le runtime clone uniquement le contenu de
<template>; tout ce qui est à l'extérieur (incl. les styles/scripts<head>) est ignoré — placez<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 hôte et liste de contrôle pré-rendu → references/sub-compositions.md.
La racine doit être dimensionnée (bug de disposition silencieux)
La racine autonome nécessite 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. Ne comptez pas uniquement sur les contrôles automatisés pour détecter cela ; inspectez un instantané. Squelette → references/minimal-composition.md.
Une seule 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. La durée de rendu = data-duration racine, pas la longueur de la timeline. N'imbriquez pas manuellement de sous-timelines dans l'hôte. Contrat complet (incluant les runtimes non GSAP) → references/determinism-rules.md + hyperframes-animation/adapters/.
Pièges de lint de première passe (un échec garanti à la première construction)
Deux règles que lint attrape, mais seulement après coup — écrivez-les correctement du premier coup :
- L'élément de composition racine doit porter
data-start="0"(avecdata-composition-id/data-width/data-height) ; l'omettre fait échouerlintavecroot_composition_missing_data_start. - Ne jamais associer un
transformCSS initial à un tween GSAP sur la même propriété — la valeur CSS et le début du tween se battent etlintle rejette avecgsap_css_transform_conflict. Définissez l'état initial dans le tween avecgsap.fromTo(el, { x: -40 }, { x: 0 })au lieu d'untransform: translateX(-40px)CSS.
Règles non négociables (bugs silencieux que les contrôles automatisés peuvent manquer)
Signalées ici ; justification complète dans la référence liée. Ne violez pas :
- Pas d'horloges au moment du rendu /
Math.randomnon ensemencé / réseau / état d'entrée ; pas derepeat: -1(utilisez un nombre fini). →determinism-rules.md - Animez uniquement la liste blanche des propriétés visuelles ; ne tweenez jamais
displayouvisibilitybrute.autoAlphade GSAP et les limites de timeline de durée nulle sont les seules exceptions de visibilité, et uniquement sur des éléments non clip ou des wrappers à l'intérieur d'un clip. Le framework seul contrôle la visibilité.clip. Ne faites pas degsap.setsur les clips de scènes ultérieures au chargement de la page. →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 une marge de crête. →determinism-rules.md <video>/<audio>fonctionnent à n'importe quelle profondeur d'imbrication (y compris à l'intérieur d'un<template>ou wrapper de sous-comp) ; le framework possède la lecture et cherche/décode les médias où qu'ils se trouvent. La seule mise en garde concerne les timelines, pas le placement : une timeline de sous-comp ne peut pas animer les éléments racine de l'hôte. →variables-and-media.md- Chaque
iddoit être unique sur la page assemblée ; à l'intérieur d'une sous-comp, préfixez les ids avec l'identifiant de composition (#<id>-hero). Les ids en double de<video>/<img>rendent une image vierge — 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 plein écran (
position:absolute; inset:0), jamais sur la racine de la composition elle-même — la composition d'image du producteur peut supprimer lebackgroundpropre de l'élément racine (l'image 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 IDs, les variables, les chemins de médias non liés.
- Faites correspondre les IDs de composition et les clés de timeline existants.
- Ajout d'un clip : choisissez un
data-track-indexnon chevauchant ou ajustez intentionnellement la temporisation environnante. data-hiddensur tout élément de composition le masque à la fois dans l'APERÇU et le rendu, remplaçant sa fenêtre temporelle ; il est non destructif/réversible et basculé par l'icône d'œil de timeline de Studio.- Ajout d'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 checkpasse (0 résultats sur le lint, le runtime, la disposition, l'animation et le contraste) - Projets avec sous-compositions :
npx hyperframes snapshot --at <milieux>et examinez chaque image -
npx hyperframes previewpour la révision (l'utilisateur peut éditer n'importe quoi dans la timeline de Studio) -
npx hyperframes renderuniquement après approbation de l'utilisateur