topcheer/ggcode

HyperFrames Core

HyperFrames rend une vidéo à 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 accessible (seekable) 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 texte 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 vivent dans les compétences de domaine associées — 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	démarrer à partir du squelette de composition minimal rendable
references/composition-patterns.md	choisir entre monolithique et modulaire ; structurer un index.html modulaire ; choisir un archétype de sous-comp
references/data-attributes.md	consulter 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, chronométrer un clip par rapport à un autre
references/sub-compositions.md	câbler une sous-composition (attributs hôtes, <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 accessible (seekable) ; 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 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 d'étape (audio, images, assemblage, transitions, sous-titres, vérifier, livrer) qu'une construction libre suit directement
references/brief-contract.md	les règles de base du brief — déduction du mode (collaboratif / autonome), registre de champs partagés, 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é qu'un workflow de Setup écrit et que chaque étape ultérieure lit
references/script-format.md	créer le SCRIPT.md facultatif 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 partagé du rôle de frame-worker — chaque constructeur de paquet de workflow narratif le préfixe au delta de ce workflow dans sub-agents/frame-worker.md
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 voir hyperframes-animation → adapters/<runtime>.md.

Construire une composition

Deux formes racines (non interchangeables)

• Autonome (index.html de premier niveau) — le <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 se trouve à l'extérieur (y compris les styles/scripts de <head>) est ignoré — placez <style>/<script> à l'intérieur du template. ⚠ Règle de l'ID hôte : le data-composition-id de l'emplacement hôte doit exactement correspondre au data-composition-id du template intérieur 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. Ne comptez pas uniquement sur des barrières 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. La 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-animation/adapters/.

Règles non négociables (bugs silencieux que les barrières automatisées peuvent manquer)

Listées ici ; justifications complètes dans la référence liée. Ne violez pas :

• Pas d'horloges au moment du rendu / Math.random non ensemencé / réseau / état d'entrée ; pas de repeat: -1 (utilisez un nombre fini). → determinism-rules.md
• Animer uniquement la liste autorisée des propriétés visuelles ; ne jamais animer 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 seulement 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ène ultérieure 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 éléments décoratifs absolus pulsants nécessitent un dégagement de crête. → determinism-rules.md
• <video>/<audio> fonctionnent à n'importe quelle profondeur d'imbrication (y compris à l'intérieur d'un <template> ou d'un 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 racines 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 identifiants avec l'ID de composition (#<id>-hero). Les identifiants <video>/<img> en double rendent vide — le producteur injecte les images par getElementById, et les doublons entre fichiers passent à travers lint. → composition-patterns.md
• Un remplissage de scène plein écran va sur un enfant à fond perdu (position:absolute; inset:0), jamais sur la racine de composition elle-même — l'assemblage d'images du producteur peut supprimer le background propre de l'élément racine (l'image rend noir) même si l'aperçu/snapshot l'affiche correctement. → composition-patterns.md

Éditer des compositions existantes

• Lisez d'abord les fichiers. Préservez le timing, les pistes, les identifiants, les variables et les chemins de médias non concernés.
• Faites correspondre les identifiants de composition existants et les clés de timeline.
• Ajouter un clip : choisissez un data-track-index non chevauchant ou ajustez intentionnellement le timing environnant.
• data-hidden sur n'importe quel élément de composition le cache à la fois dans l'APERÇU et le RENDU, en ignorant sa fenêtre temporelle ; il est non destructif/réversible et basculé par l'icône de l'œil de la timeline de Studio.
• Ajouter 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 réussi (0 résultats parmi lint, runtime, mise en page, mouvement et contraste)
• Projets avec sous-compositions : npx hyperframes snapshot --at <midpoints> et inspectez visuellement chaque image
• npx hyperframes preview pour la révision (l'utilisateur peut éditer n'importe quoi dans la timeline de Studio)
• npx hyperframes render seulement après approbation de l'utilisateur