Contribuer au registre HyperFrames

Guidez l'utilisateur de l'idée à la PR fusionnée pour un nouveau bloc ou composant de registre.

Flux de travail

1. Clarifier → 2. Générer la structure → 3. Construire → 4. Valider → 5. Prévisualiser → 6. Publier

Étape 1 : Clarifier

Demandez ce que l'utilisateur construit. Le registre comporte deux types d'éléments :

Bloc (registry/blocks/, type hyperframes:block) — une composition autonome complète avec des dimensions et une durée fixes. Styles de légende, effets VFX, cartes titres, tiers inférieurs.
Composant (registry/components/, type hyperframes:component) — un extrait réutilisable sans dimensions ni durée fixes. Effets CSS, traitements de texte, superpositions qui s'adaptent à n'importe quelle taille de composition.

Puis demandez :

Description en une phrase de l'effet
Référence visuelle (URL, capture d'écran ou description)
Qui utilise cela et quand ?

Étape 2 : Générer la structure

Créez la structure du registre :

Pour les blocs :

registry/blocks/{nom-du-bloc}/
  {nom-du-bloc}.html
  registry-item.json

Pour les composants :

registry/components/{nom-du-composant}/
  {nom-du-composant}.html
  registry-item.json

Convention de nommage :

Nom de l'élément	Préfixe ID	Exemples d'ID
`cap-hormozi`	`hz`	`hz-cg-0`, `hz-cw-3`
`cap-typewriter`	`tw`	`tw-cg-0`, `tw-ch-0-5`
`vfx-chrome`	`vc`	`vc-canvas`

Utilisez un préfixe de 2 à 3 lettres. TOUS les ID d'éléments doivent utiliser ce préfixe pour éviter les collisions dans les sous-compositions.

registry-item.json pour les blocs :

{
  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
  "name": "{nom-du-bloc}",
  "type": "hyperframes:block",
  "title": "{Titre humain}",
  "description": "{une phrase}",
  "dimensions": { "width": 1920, "height": 1080 }, // ajuster : 1080x1920 pour portrait/réseaux sociaux
  "duration": 10, // ajuster pour votre composition
  "tags": ["{catégorie}", "{sous-catégorie}"],
  "files": [
    {
      "path": "{nom-du-bloc}.html",
      "target": "compositions/{nom-du-bloc}.html",
      "type": "hyperframes:composition"
    }
  ]
}

registry-item.json pour les composants (pas de dimensions ni duration) :

{
  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
  "name": "{nom-du-composant}",
  "type": "hyperframes:component",
  "title": "{Titre humain}",
  "description": "{une phrase}",
  "tags": ["{catégorie}"],
  "files": [
    {
      "path": "{nom-du-composant}.html",
      "target": "compositions/components/{nom-du-composant}.html",
      "type": "hyperframes:snippet"
    }
  ]
}

Étape 3 : Construire

Appliquez le modèle approprié en fonction du type. Voir templates.md pour les modèles prêts à copier-coller.

Blocs de légende

Règles de légende non négociables :

Police : 96px minimum pour les polices proportionnelles. 64-72px acceptable pour les polices monospace (les caractères plus larges nécessitent moins de taille).
Lisibilité : -webkit-text-stroke: 2-3px OU text-shadow multicouche
Débordement : appeler window.__hyperframes.fitTextFontSize() sur chaque groupe
Karaoké : mettre en surbrillance le mot actif via tl.to(wordEl, { color/scale }, WORDS[wi].start)
Suppression définitive : tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end) sur CHAQUE groupe
N'utilisez jamais tl.from(el, { opacity: 0 }) à la même position que tl.set(el, { opacity: 1 }) — le from écrase le set. Utilisez tl.to à la place.

Animation par caractère (machine à écrire, embrouillage) :

Encapsuler chaque caractère dans <span> avec l'ID {préfixe}-ch-{groupe}-{caractère}
Échelonner via tl.set à des intervalles calculés à partir des horodatages des mots
Curseurs/éléments décoratifs : utiliser tl.set à intervalles — PAS d'animation CSS (non accessible par seek)

Variantes de positionnement :

Centré : display: flex; align-items: center; justify-content: center;
Tiers inférieur : position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center;
Aligné à gauche : position: absolute; bottom: 100px; left: 120px; text-align: left;

Blocs VFX (Three.js)

Utiliser [email protected] depuis un CDN (script global)
tl.eventCallback("onUpdate", renderScene); renderScene(); — PAS de requestAnimationFrame
Modèle de proxy d'état : GSAP anime un objet JS simple, la fonction de rendu le lit
PRNG ensemencée (mulberry32) pour l'aléatoire

Tous les types

data-composition-id DOIT correspondre à window.__timelines["id"]
Tous les ID d'éléments préfixés par l'abréviation du bloc
gsap.timeline({ paused: true }) — toujours en pause
Pas de Math.random(), pas de Date.now()

Étape 4 : Valider

hyperframes lint                    # 0 erreurs requises
hyperframes validate --no-contrast  # 0 erreurs console requises

Étape 5 : Prévisualiser

# Générer la vidéo de prévisualisation
hyperframes render -o preview.mp4

# Instantané pour vérification visuelle
hyperframes snapshot --at "1.0,3.0,5.0,7.0"

# Publier sur hyperframes.dev pour révision
npx hyperframes publish

Image de prévisualisation du catalogue — La carte du catalogue utilise un PNG à docs/images/catalog/{kind}/{name}.png (où {kind} est blocks ou components). Générez-la à partir d'un instantané, puis :

Contributeurs internes HeyGen : exécutez scripts/upload-docs-images.sh (nécessite le profil AWS engineering-767398024897)
Contributeurs externes : joignez la MP4 de prévisualisation à la description de votre PR. Un mainteneur générera et téléchargera l'image du catalogue avant la fusion.

Étape 6 : Publier

Toutes les étapes sont requises. L'absence de l'une d'entre elles produit une entrée de catalogue cassée.

{kind} est blocks ou components selon ce que vous avez construit à l'étape 1.

# 1. Créer une branche
git checkout -b feat/registry-{nom}

# 2. Formater le HTML
npx oxfmt registry/{kind}/{nom}/*.html

# 3. Mettre à jour registry/registry.json — ajouter l'entrée au tableau "items" :
#    { "name": "{nom}", "type": "hyperframes:block" }  (ou "hyperframes:component")

# 4. Générer la page de documentation du catalogue
npx tsx scripts/generate-catalog-pages.ts

# 5. Publier sur hyperframes.dev pour que les réviseurs puissent prévisualiser
npx hyperframes publish

# 6. Mettre en scène tout
git add registry/{kind}/{nom}/ registry/registry.json docs/catalog/

# 7. Commiter
git commit -m "feat(registry): ajout de {nom} — {une phrase}"

# 8. Pousser et ouvrir une PR avec le lien hyperframes.dev
git push origin feat/registry-{nom}
gh pr create --title "feat(registry): {nom}" --body "preview: {url-hyperframes-dev}"

Si vous n'avez pas de compte GitHub : vous en avez besoin pour ouvrir une PR. Inscrivez-vous sur https://github.com/signup, puis exécutez gh auth login.

Porte de qualité

hyperframes lint → 0 erreurs
hyperframes validate → 0 erreurs console
npx oxfmt --check passe
registry/registry.json mis à jour avec la nouvelle entrée
scripts/generate-catalog-pages.ts exécuté (page de documentation générée)
npx hyperframes publish exécuté (revendiquez l'URL de votre projet)
MP4 de prévisualisation jointe à la PR (externe) ou PNG du catalogue téléchargé (interne)
Tous les ID uniques et préfixés

shengdabai/Tony-Claude-Code-Skills

Qu'est-ce que Tony-Claude-Code-Skills ?

Demander à votre IA préférée

Documentation