hyperframes-core

HyperFrames Core

HyperFrames rend une vidéo à partir d'HTML. Une composition est un fichier HTML dont le DOM déclare le timing avec des attributs data-*, dont le runtime d'animation est scrutable, 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), lisez à 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 indique ce que chacune couvre.

Références

Fichier	Lisez-le pour…
references/minimal-composition.md	commencer par le squelette de composition minimal rendable
references/composition-patterns.md	choisir monolithique vs modulaire ; structurer un index.html modulaire ; choisir un archétype de sous-composition
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/creator-editing-recipes.md	copier des recettes d'édition véridiques (couper/rogner/réorganiser/retemporiser/geler/caméra/masque/fondu enchaîné/audio) et leurs limites
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, rogner
references/determinism-rules.md	construire une timeline scrutable ; interdictions de déterminisme ; liste autorisée des propriétés animables ; mise en page / ajustement du texte
references/full-screen-motion.md	créer un mouvement plein écran avec des arrière-plans partagés
references/storyboard-format.md	créer un plan STORYBOARD.md (+ le manifeste parsé)
references/review-loop.md	exécuter les passes de révision plan → esquisse → construction sur un tableau vivant — partagé par chaque flux de travail 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) ; 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é, invariants de questions (la question elle-même vit dans /hyperframes → la couche d'intention)
references/brief-format.md	créer BRIEF.md — le document d'intention confirmé que le Setup d'un flux de travail écrit et que chaque étape ultérieure lit
references/script-format.md	créer le SCRIPT.md optionnel de narration verrouillée
references/subagent-dispatch.md	mapper les verbes de répartition des sous-agents (fan-out parallèle / arrière-plan / attente) à votre harnais
references/frame-worker-core.md	le contrat de rôle du frame-worker partagé — le constructeur de paquet de chaque flux de travail narratif le préfixe au delta sub-agents/frame-worker.md de ce flux
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.html de niveau supérieur) — <div data-composition-id="…"> racine se trouve directement dans <body>, pas de wrapper <template> (l'envelopper cache tout le contenu et brise 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 de <head>) est ignoré — placez <style>/<script> à l'intérieur du template. ⚠ Règle d'ID hôte : le data-composition-id de l'emplacement hôte doit exactement égaler le data-composition-id du template intérieur et la clé window.__timelines["<id>"] — pas de suffixe -mount/-slot/-host.

Forme du fichier, câblage hôte, et liste de vérification pré-rendu → references/sub-compositions.md.

La racine doit être dimensionnée (bogue silencieux de mise en page)

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. Ne comptez pas uniquement sur des passerelles automatisées pour détecter cela ; inspectez un instantané. 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 de rendu = data-duration racine, pas la longueur de la timeline. N'imbriquez pas manuellement des 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 premier échec de construction garanti)

Deux règles que lint détecte effectivement, mais seulement après coup — écrivez-les correctement dès la première fois :

• L'élément de composition racine doit porter data-start="0" (avec data-composition-id/data-width/data-height) ; l'omettre fait échouer lint avec root_composition_missing_data_start.
• Ne jamais associer une propriété CSS transform initiale à un tween GSAP sur la même propriété — la valeur CSS et le début du tween se battent et lint le rejette avec gsap_css_transform_conflict. Définissez l'état initial à l'intérieur du tween avec gsap.fromTo(el, { x: -40 }, { x: 0 }) au lieu d'un CSS transform: translateX(-40px).

Règles non négociables (bogues silencieux que les passerelles automatisées peuvent manquer)

Révélées ici ; justification complète dans la référence liée. Ne violez pas :

• Pas d'horloges au moment du rendu / Math.random non amorcé / réseau / état d'entrée ; pas de repeat: -1 (utilisez un nombre fini). → determinism-rules.md
• Animez uniquement la liste autorisée des propriétés visuelles ; ne tweenez jamais display ou visibility brute. autoAlpha de GSAP et les ensembles de 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é de .clip. Ne faites pas gsap.set sur des clips de scènes ultérieures au chargement de la page. → determinism-rules.md
• Pas de <br> dans le corps du texte ; les éléments transformés doivent être de niveau bloc + dimensionnés ; les décoratifs absolus pulsants ont besoin de dégagement de pic. → determinism-rules.md
• <video>/<audio> fonctionnent à toute profondeur d'imbrication (y compris à l'intérieur d'un <template> de sous-comp ou d'un wrapper) ; le framework possède la lecture et cherche/décode le média où qu'il se trouve. 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 id doit ê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). Les id en double de <video>/<img> rendent vide — le producteur injecte les images par getElementById, et les doublons entre fichiers échappent à lint. → composition-patterns.md
• Un remplissage de scène plein écran va sur un enfant pleine page (position:absolute; inset:0), jamais sur la racine de la composition elle-même — le compositing d'images du producteur peut supprimer le background propre de l'élément racine (l'image rend noire) même si l'aperçu/snapshot l'affiche correctement. → composition-patterns.md

Modifier des compositions existantes

• Lisez d'abord les fichiers. Préservez le timing, les pistes, les ID, les variables, les chemins médias non liés.
• Faites correspondre les ID de composition existants et les clés de timeline.
• Ajout d'un clip : choisissez un data-track-index sans chevauchement ou ajustez intentionnellement le timing environnant.
• data-hidden sur 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 la timeline de Studio.
• Ajout d'une sous-composition : vérifiez son data-composition-id interne avant de câbler l'hôte.

Validation

Utilisez hyperframes-cli pour les détails des commandes

• npx hyperframes check passe (0 résultats parmi lint, runtime, mise en page, mouvement et contraste)
• Projets avec sous-compositions : npx hyperframes snapshot --at <midpoints> et inspectez chaque image
• npx hyperframes preview --background pour la révision (l'utilisateur peut modifier n'importe quoi dans la timeline de Studio, et le serveur survit à la commande invocatrice)
• npx hyperframes render uniquement après l'approbation de l'utilisateur