Communitygithub.com

sq-cm/claude-template

Boucle de développement CLI HyperFrames — `npx hyperframes` pour le scaffolding (init), la validation (lint, validate, inspect), la prévisualisation, le rendu et le dépannage de l'environnement (doctor, browser, info, upgrade). Utilisez cette compétence lorsque vous exécutez l'une de ces commandes ou que vous diagnostiquez l'environnement de build/rendu HyperFrames. Pour les commandes de prétraitement des assets (`tts`, `transcribe`, `remove-background`), invoquez la compétence `hyperframes-media`.

Qu'est-ce que claude-template ?

Cette compétence fournit un guide complet pour l'interface en ligne de commande (CLI) HyperFrames, l'outil principal pour développer et produire des compositions vidéo interactives. Elle couvre l'ensemble du flux de travail, de l'initialisation d'un projet avec `npx hyperframes init` jusqu'au rendu final en MP4 ou WebM, en passant par le linting, la validation d'exécution et l'inspection visuelle. La compétence détaille les commandes de dépannage (`doctor`, `browser`, `info`, `upgrade`) pour garantir un environnement sain (Node.js >=22, FFmpeg, Chrome). Elle est conçue pour des agents IA et des développeurs utilisant HyperFrames sur n'importe quel système (macOS, Linux, Windows) et s'appuie sur la documentation officielle du projet vendored. L'organisation suit l'ordre du pipeline de développement : scaffolding, écriture, linting, validation, inspection, prévisualisation, puis rendu, avec des conseils sur les drapeaux (flags) comme `--quality`, `--fps`, `--docker` ou `--variables` pour des rendus paramétrés. Note de divergence : la commande upstream `validate` est dépréciée au profit de `check` depuis la restructuration de juillet 2026 ; cette compétence conserve l'ancienne interface pour compatibilité.

Compatible avec✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/sq-cm/claude-template/tree/HEAD/.claude/skills/hyperframes-cli

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

CLI HyperFrames

Tout passe par npx hyperframes. Nécessite Node.js >= 22 et FFmpeg.

Workflow

  1. Scaffolding — npx hyperframes init my-video
  2. Écrire — composer le HTML (voir la compétence hyperframes)
  3. Linter — npx hyperframes lint
  4. Valider l'exécution — npx hyperframes validate
  5. Inspecter visuellement — npx hyperframes inspect
  6. Prévisualiser — npx hyperframes preview
  7. Rendre — npx hyperframes render

Effectuez le linting et l'inspection avant la prévisualisation. lint détecte les data-composition-id manquants, les pistes qui se chevauchent et les timelines non enregistrées. inspect ouvre la composition rendue dans Chrome headless, parcourt la timeline et signale le texte qui dépasse des bulles/conteneurs ou du canevas.

Scaffolding

npx hyperframes init my-video                        # assistant interactif
npx hyperframes init my-video --example warm-grain   # choisir un exemple
npx hyperframes init my-video --video clip.mp4        # avec fichier vidéo
npx hyperframes init my-video --audio track.mp3       # avec fichier audio
npx hyperframes init my-video --example blank --tailwind # avec runtime navigateur Tailwind v4
npx hyperframes init my-video --non-interactive       # ignorer les invites (CI/agents)

Modèles : blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.

init crée la structure de fichiers appropriée, copie les médias, transcrit l'audio avec Whisper et installe les compétences de codage IA. Utilisez-le au lieu de créer les fichiers à la main.

Lorsque vous utilisez --tailwind, notez que le scaffold utilise Tailwind v4.2 via le runtime navigateur, pas la configuration Tailwind v3 de Studio — vérifiez la syntaxe des classes et des jetons de thème par rapport à la documentation v4 avant de modifier.

Linting

npx hyperframes lint                  # répertoire courant
npx hyperframes lint ./my-project     # projet spécifique
npx hyperframes lint --verbose        # constats de niveau info
npx hyperframes lint --json           # lisible par machine

Lint index.html et tous les fichiers dans compositions/. Signale les erreurs (à corriger absolument), les avertissements (à corriger si possible) et les informations (avec --verbose).

Validation d'exécution

npx hyperframes validate                  # répertoire courant
npx hyperframes validate ./my-project     # projet spécifique
npx hyperframes validate --json           # lisible par machine
npx hyperframes validate --timeout 5000   # scripts/médias lents (défaut 3000 ms)

Charge la composition dans Chrome headless et signale les erreurs de console JS, les assets manquants et les problèmes de contraste WCAG (--no-contrast pour ignorer la passe de contraste). Exécutez-la après lint, avant inspect.

validate est déprécié upstream au profit de npx hyperframes check, qui exécute la vérification du linting, de l'exécution, de la mise en page, de l'animation et du contraste en une seule session navigateur — l'une ou l'autre satisfait une tâche de « lint et validate ».

Inspection visuelle

npx hyperframes inspect                 # inspecte la mise en page rendue sur la timeline
npx hyperframes inspect ./my-project    # projet spécifique
npx hyperframes inspect --json          # constats lisibles par agent
npx hyperframes inspect --samples 15    # balayage plus dense de la timeline
npx hyperframes inspect --at 1.5,4,7.25 # horodatages explicites des images-clés

Utilisez-la après lint et validate, surtout pour les compositions avec des bulles de dialogue, des cartes, des sous-titres ou une typographie serrée. Elle signale :

  • Le texte s'étendant à l'extérieur du conteneur visuel ou de la bulle le plus proche
  • Le texte rogné par sa propre boîte de largeur/hauteur fixe
  • Le texte s'étendant à l'extérieur du canevas de la composition
  • Les enfants s'échappant des conteneurs de rognage

Les erreurs doivent être corrigées avant le rendu. Les avertissements sont présentés pour examen par l'agent ; ajoutez --strict pour échouer également sur les avertissements. Les problèmes statiques répétés sont regroupés par défaut pour que la sortie JSON reste compacte pour les fenêtres de contexte LLM. Si un débordement est intentionnel pour une animation d'entrée/sortie, marquez l'élément ou l'ancêtre avec data-layout-allow-overflow. Si un élément décoratif ne doit jamais être audité, marquez-le avec data-layout-ignore.

npx hyperframes layout reste disponible comme alias de compatibilité pour la même passe d'inspection visuelle.

Prévisualisation

npx hyperframes preview                   # sert le répertoire courant
npx hyperframes preview --port 4567       # port personnalisé (défaut 3002)

Recharge à chaud lors des modifications de fichiers. Ouvre le studio automatiquement dans votre navigateur.

Lorsque vous remettez un projet à l'utilisateur, utilisez l'URL du projet Studio, pas le chemin index.html source :

http://localhost:<port>/#project/<nom-du-projet>

Utilisez le port réel de la sortie de prévisualisation et le nom du répertoire du projet. Par exemple, après npx hyperframes preview --port 3017 dans codex-openai-video, signalez http://localhost:3017/#project/codex-openai-video.

Traitez index.html uniquement comme contexte de code source. Il est acceptable de le lier comme fichier d'implémentation, mais ne l'étiquetez pas comme projet ou surface de prévisualisation.

Rendu

npx hyperframes render                                # MP4 standard
npx hyperframes render --output final.mp4             # sortie nommée
npx hyperframes render --quality draft                # itération rapide
npx hyperframes render --fps 60 --quality high        # livraison finale
npx hyperframes render --format webm                  # WebM transparent
npx hyperframes render --docker                       # octet-identique
DrapeauOptionsDéfautNotes
--outputcheminrenders/nom_horodatage.mp4Chemin de sortie
--fps24, 30, 603060 ips double le temps de rendu
--qualitydraft, standard, highstandarddraft pour itérer
--formatmp4, webmmp4WebM prend en charge la transparence
--workers1-8 ou autoautoChacun lance Chrome
--dockerdrapeauoffSortie reproductible
--gpudrapeauoffEncodage accéléré par GPU
--strictdrapeauoffÉchoue sur les erreurs de lint
--strict-alldrapeauoffÉchoue sur les erreurs ET les avertissements
--variablesobjet JSON—Remplace les valeurs de variables déclarées dans data-composition-variables
--variables-filechemin—Fichier JSON avec valeurs de variables (alternative à --variables)
--strict-variablesdrapeauoffÉchoue le rendu sur des clés non déclarées ou des types incorrects dans --variables

Conseils de qualité : draft pendant l'itération, standard pour la relecture, high pour la livraison finale.

Rendus paramétrés : la composition déclare ses variables sur la racine <html> avec data-composition-variables — un tableau JSON de déclarations ({id, type, label, default} par entrée) qui définit le schéma. Les scripts internes lisent les valeurs résolues via window.__hyperframes.getVariables(). Le CLI --variables '{"title":"Rapport Q4"}' est un objet JSON indexé par id qui remplace ces valeurs par défaut déclarées pour un rendu ; les clés manquantes passent outre, donc la même composition s'exécute inchangée en prévisualisation dev et en production. (Les hôtes de sous-compositions peuvent également remplacer par instance avec data-variable-values — même forme d'objet, limitée à un montage de la sous-composition. Voir la compétence hyperframes pour le modèle complet.)

Prétraitement des assets

npx hyperframes tts, transcribe et remove-background produisent des assets (audio de narration, transcriptions au niveau du mot, vidéo transparente) qui sont déposés dans une composition. Chacun télécharge son propre modèle lors de la première exécution. Pour la sélection de voix, les règles du modèle Whisper (l'astuce .en qui traduit l'anglais), le choix du format de sortie (WebM alpha VP9 vs ProRes) et la chaîne TTS → transcription → sous-titres, invoquez la compétence hyperframes-media.

Dépannage

npx hyperframes doctor       # vérifier l'environnement (Chrome, FFmpeg, Node, mémoire)
npx hyperframes browser      # gérer le Chrome fourni
npx hyperframes info         # détails de version et d'environnement
npx hyperframes upgrade      # vérifier les mises à jour

Exécutez doctor en premier si le rendu échoue. Problèmes courants : FFmpeg manquant, Chrome manquant, mémoire insuffisante.

Autre

npx hyperframes compositions   # lister les compositions dans le projet
npx hyperframes docs           # ouvrir la documentation
npx hyperframes benchmark .    # benchmarker les performances de rendu

Skills associés