Communitygithub.com

Emasoft/ai-maestro-webdesign

Composition HTML en rendu vidéo MP4 via le monorepo externe Hyperframes. Se déclenche sur « rendre du HTML en vidéo », « HTML vers MP4 », « site web en vidéo », « créer une vidéo à partir de HTML », « rasteriser la composition en MP4 ». Ne se déclenche PAS sur les mentions génériques d'« animation » ou « vidéo » — celles-ci passent par pretext ou le pipeline de l'utilisateur. À utiliser pour le rendu HTML vers MP4 via Hyperframes.

Qu'est-ce que ai-maestro-webdesign ?

Ce pont (bridge) permet de transformer des compositions HTML en fichiers vidéo MP4 en déléguant le rendu au monorepo externe Hyperframes (hébergé sur GitHub). Développé pour les agents d'IA comme Claude Code, Cursor ou Codex, il s'intègre dans la phase finale du pipeline de conception (Phase B). Le skill vérifie d'abord que le dépôt externe est bien cloné et fonctionnel, puis exécute une séquence de pré-rendu obligatoire (lint → validation → inspection → rendu) avant de lancer la commande `npx hyperframes render --output <mp4>`. Il accepte soit le chemin d'un fichier HTML unique (pour lequel il crée un projet temporaire), soit un dossier de projet Hyperframes existant. Après le rendu, il confirme que le fichier MP4 est valide et renvoie son chemin ainsi qu'un rapport d'achèvement. Ce skill est autonome : n'importe quel agent peut l'utiliser en lisant son SKILL.md. Il ne réimplémente pas le pipeline interne d'Hyperframes, il l'appelle simplement via des commandes shell. Son déclenchement est strictement réservé aux requêtes explicites de rendu HTML vers vidéo.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Emasoft/ai-maestro-webdesign/tree/HEAD/skills/amw-hyperframes-bridge

Demander à votre IA préférée

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

Documentation

Pont Hyperframes

Orchestré par : SKILL. Wrapper de dépendance externe. Le monorepo Hyperframes se trouve dans ../../external/hyperframes/ (cloné par /amw-init étape 6 si l'utilisateur accepte, OU par ce skill lors du premier rendu en secours). Ce skill documente le modèle d'appel shell ; il ne contient PAS le monorepo.

Aperçu

Rend des compositions HTML en vidéo MP4 en appelant le monorepo Hyperframes (external/hyperframes/). Accepte un seul fichier HTML ou un dossier de projet Hyperframes complet. Exécute la séquence de pré-rendu obligatoire (lint → validate → inspect → render) avant d'appeler npx hyperframes render --output <mp4>. Retourne le chemin du MP4 et un rapport d'achèvement. Pas de réimplémentation du pipeline Hyperframes dans le plugin — uniquement des appels shell.

Instructions

  1. Vérifier le repo externe avec deux contrôles : external/hyperframes/package.json doit exister, et npx hyperframes render --help doit répondre ; échouer immédiatement si l'un des deux échoue.
  2. Résoudre le répertoire du projet : utiliser project_dir s'il est fourni, ou créer un projet temporaire à partir de html_scene_path ; échouer immédiatement si aucun n'est fourni.
  3. Exécuter la séquence de pré-rendu dans l'ordre : lint → validate → inspect → render (abandonner si une étape retourne un code non nul).
  4. Exécuter cd "$HF_PROJ_DIR" && npx hyperframes render --output <mp4> ; collecter le chemin de sortie.
  5. Confirmer que le fichier MP4 existe et n'est pas vide ; signaler le chemin de sortie et les éventuels avertissements d'inspect.
  6. Voir la section ## Modèle d'appel ci-dessous pour les étapes d'exécution faisant autorité.

Activation

Pas de commande slash dédiée — ce skill n'a pas de raccourci /amw-* correspondant. Invoqué par l'orchestrateur design-principles comme dernière étape de la Phase B en mode Agent Principal lorsque la conception approuvée nécessite une sortie vidéo MP4. L'orchestrateur peut appliquer l'ensemble du pipeline d'appel Hyperframes et les techniques de composition de ce skill sans restriction de couche de commande.

Ce skill est autonome et auto-suffisant — n'importe quel agent (l'agent principal, un sous-agent ou un orchestrateur externe) peut l'utiliser en lisant ce SKILL.md et ses références. Les techniques du skill ne sont PAS limitées à ce que les commandes correspondantes exposent.

Position dans le flux

SORTIE (Phase B — terminale). Pipeline de rendu HTML vers MP4. Déclenché uniquement lorsque l'utilisateur souhaite explicitement rasteriser une composition HTML en fichier vidéo. S'exécute en dernier, une fois la composition terminée.

Conditions de déclenchement

Invoquer ce skill UNIQUEMENT lorsque la requête correspond à l'un des cas suivants :

  • « rendre ce HTML en vidéo » / « rendre en MP4 »
  • « HTML vers MP4 » / « site web en vidéo » / « page en vidéo »
  • « créer une vidéo à partir de cette composition HTML »
  • « rasteriser la composition en vidéo »
  • Mention explicite d'Hyperframes / hyperframes render / .hf.html

Ne PAS invoquer sur les mentions génériques d'« animation », « mouvement », « lecture vidéo » ou « composant animé » — celles-ci relèvent de :

  • ../amw-design-principles/starter-components/animations.html (timeline Stage + Sprite dans le navigateur)
  • ../amw-pretext/ (mouvement typographique — pretext-art/ est une redirection obsolète)
  • Le propre pipeline de l'utilisateur

Prérequis

  • binaires d'exécution (prérequis système) : Node.js >= 22, git

  • binaires d'exécution (installés par /amw-init) : Bun (gestionnaire de paquets d'Hyperframes), FFmpeg. Chrome est géré par Hyperframes lui-même via hyperframes browser ensure (utilise Puppeteer + @puppeteer/browsers en interne — PAS Playwright).

  • source externe : ../../external/hyperframes/ — le monorepo Hyperframes cloné depuis https://github.com/heygen-com/hyperframes. Cibler v0.4.30 ou ultérieur pour le support d'inspect, --hdr et data-variable-values. Si le dossier n'existe pas, /amw-init ou ce skill DOIVENT le cloner avant de continuer :

    git clone --branch v0.4.30 --depth 1 https://github.com/heygen-com/hyperframes.git external/hyperframes
    cd external/hyperframes && bun install
    

Contrat d'entrée

Le pont accepte deux entrées mutuellement exclusives. Fournir exactement une :

ChampTypeDescription
html_scene_pathstring (optionnel)Chemin absolu vers un fichier HTML unique. Le pont crée un répertoire de projet Hyperframes temporaire via mktemp -d -t hf-XXXXXX (portable POSIX), y écrit le HTML comme index.html, effectue le rendu, puis nettoie après avoir écrit le rapport.
project_dirstring (optionnel)Chemin absolu vers un répertoire de projet Hyperframes existant (contient index.html et éventuellement compositions/, assets/). Le pont se place directement dedans — pas de création de structure. Prend en charge les sous-compositions, l'audio et les ressources externes.

Si les deux sont fournis, project_dir l'emporte. Si aucun n'est fourni, échouer immédiatement.

Modèle d'appel

  1. Vérifier le repo externe — deux contrôles requis :

    # Contrôle 1 — package.json présent (monorepo cloné)
    test -f "external/hyperframes/package.json" || exit-fail "monorepo introuvable"
    # Contrôle 2 — CLI répond (installation fonctionnelle)
    # @hyperframes/cli n'est PAS publié sur npm — doit être exécuté depuis l'espace de travail du monorepo
    (cd external/hyperframes && npx hyperframes render --help) >/dev/null 2>&1 || exit-fail "CLI hyperframes non fonctionnelle — exécutez bun install dans external/hyperframes/"
    

    Si l'un des contrôles échoue, échouer immédiatement. Ne pas continuer.

  2. Résoudre le répertoire du projet.

    • Si project_dir est fourni : l'utiliser directement. Définir HF_PROJ_DIR="$project_dir".
    • Si html_scene_path est fourni : créer un projet temporaire :
      HF_PROJ_DIR="$(mktemp -d -t hf-XXXXXX)"
      cp "$html_scene_path" "$HF_PROJ_DIR/index.html"
      
    • Sinon : échouer immédiatement.
  3. Exécuter la séquence de pré-rendu : lint → validate → inspect → render.

    cd "$HF_PROJ_DIR"
    npx hyperframes lint
    npx hyperframes validate
    npx hyperframes inspect --json  # abandonner en cas d'erreurs (sortie non nulle avec --strict)
    

    Voir TECH-hyperframes-cli-lint, TECH-hyperframes-cli-validate, TECH-hyperframes-cli-inspect.

[TECH-hyperframes-cli-inspect.md] Ce qu'il fait · Quand l'utiliser · Comment il fonctionne · Drapeaux · Sortie (mode JSON) · Exemple minimal · Attributs d'exclusion · Pièges · Références croisées [TECH-hyperframes-cli-validate.md] Ce qu'il fait · Quand l'utiliser · Comment il fonctionne · Sortie · Quand les avertissements apparaissent · Exemple minimal · Pièges · Références croisées [TECH-hyperframes-cli-lint.md] Ce qu'il fait · Quand l'utiliser · Comment il fonctionne · Exemple minimal · Pièges · Références croisées

Note sur la séquence de vérification : La séquence du pont (lint → validate → inspect → render) étend intentionnellement celle en amont (lint → inspect → preview → render — voir le SKILL.md de la CLI Hyperframes dans le monorepo external/hyperframes/) en ajoutant validate pour les pipelines Phase B non supervisés et en supprimant preview (une primitive de boucle de développeur).

  1. Rendu. Depuis le répertoire du projet résolu :
    cd "$HF_PROJ_DIR"
    npx hyperframes render --output <chemin-abs-mp4>
    
    Drapeaux supplémentaires si nécessaire (--fps, --quality, --format, --hdr, etc.) — voir TECH-hyperframes-cli-render.

[TECH-hyperframes-cli-render.md] Ce qu'il fait · Quand l'utiliser · Comment il fonctionne · Drapeaux · Conseils qualité · Vidéo transparente · Exemple minimal · Réglage des workers · Pièges · Références croisées

  1. Retourner le chemin du MP4 à l'appelant. Si le répertoire du projet était temporaire (html_scene_path), le supprimer après avoir écrit le rapport.

Règles de composition HTML (spécifiques à Hyperframes)

Les compositions utilisent du HTML simple avec des attributs data-* de timeline sur une racine #stage et ses enfants (pistes / clips / superpositions). C'est le même modèle mental Stage + Sprite que ../amw-design-principles/starter-components/animations.html — Hyperframes l'étend avec le mixage audio/vidéo multi-pistes et le rendu déterministe hors écran.

Attributs clés (le schéma faisant autorité se trouve dans external/hyperframes/packages/core/ une fois cloné) :

  • data-composition-id — identifiant au niveau de la scène
  • data-start, data-duration — secondes, par clip
  • data-track-index — ordre des calques (pistes vidéo / superposition / audio)
  • data-width, data-height — dimensions du canevas au niveau de la scène

N'introduisez PAS Framer Motion, GSAP en tant que dépendance, ou tout autre moteur d'animation tiers dans le pont. Hyperframes a son propre modèle d'adaptateur de trame ; si l'utilisateur souhaite GSAP dans une composition, c'est le problème d'Hyperframes, pas celui du pont.

Références

Index complet des références : INDEX.md — 32 fichiers TECH-*.md regroupés par pipeline Capture (7 étapes), commandes CLI (12), rédaction de composition (7), Registre (4). Chaque fichier a sa propre table des matières ; chargez uniquement celui dont vous avez besoin.

Exemples

Voir les exemples travaillés dans les fichiers de référence par étape sous ./references/TECH-hyperframes-capture-step-*.md (pipeline site-web-vers-vidéo en 7 étapes) et le guide de rédaction de composition à TECH-hyperframes-composition-core.

[TECH-hyperframes-composition-core.md] Ce qu'il fait · Quand l'utiliser · Comment il fonctionne · Approche (ordre narratif) · Squelette d'un seul fichier · Porte d'identité visuelle (OBLIGATOIRE — avant d'écrire le HTML) · Pièges · Références croisées

Sortie

Un fichier vidéo MP4 rendu plus un rapport d'achèvement de tâche. Le MP4 est produit par npx hyperframes render --output <mp4> depuis le répertoire du projet résolu ; le pont confirme que le fichier existe et n'est pas vide avant de signaler le succès. Contrat complet ci-dessous.

Sortie et liste de vérification d'achèvement

Le contrat de sortie complet (règles d'inférence des chemins d'artefacts, forme du rapport d'achèvement, liste de vérification obligatoire) se trouve dans TECH-output-contract. Deux sorties sont obligatoires :

  1. Artefacts — dossier du projet Hyperframes + MP4 rendu. Le chemin est déduit du projet (chemin utilisateur → convention du framework → ./design/<sous-type>/ → solution de repli ./design/videos/).
  2. Rapport d'achèvement de tâche à $MAIN_ROOT/reports/webdesigner/<ts±tz>-amw-video-producer-<slug>-<8-char-hash>.md listant chaque artefact + le verdict par élément de la liste.

Avant de signaler l'achèvement : chaque élément de la liste dans TECH-output-contract DOIT être PASS ou N/A. Tout FAIL déclenche une boucle de correction.

Ressources

  • ../amw-design-principles/starter-components/animations.html — le moteur de timeline Stage + Sprite d'environ 50 lignes utilisé pour les aperçus dans le navigateur ; Hyperframes partage le même rythme.
  • ../../bin/amw-html-export.py — PAS un substitut. html-export rend une seule image en PNG/PDF ; Hyperframes rend une vidéo MP4 multi-images en utilisant Puppeteer + Chrome (géré par hyperframes browser ensure) + FFmpeg.
  • ../amw-dev-browser/ — PAS un substitut. dev-browser est destiné à l'entrée/l'automatisation ; Hyperframes est le rasteriseur de sortie.
  • /amw-init — installe Bun, FFmpeg et clone external/hyperframes/ lors de la première utilisation. Chrome pour le rendu est provisionné par Hyperframes lui-même via hyperframes browser ensure.
  • Dépôt externe : https://github.com/heygen-com/hyperframes

Non-négociables

  • Utiliser le monorepo externe via appel shell. Ne PAS réimplémenter son pipeline dans le plugin.
  • Ne PAS vendre la source d'Hyperframes dans skills/ — 500+ fichiers est une portée trop large pour un skill.
  • Ne PAS substituer dev-browser à Hyperframes — ils résolvent des problèmes opposés (entrée vs. sortie).
  • Ne PAS substituer html-export.py — une image PNG unique n'est pas une vidéo.
  • L'utilisateur DOIT exécuter /amw-init avant la première utilisation pour installer Bun + FFmpeg et cloner le repo externe. Chrome est provisionné en exécutant (cd external/hyperframes && npx hyperframes browser ensure) une fois après le clonage.

Gestion des erreurs

Les modes de défaillance courants et les mesures correctives se trouvent dans TECH-error-handling. Couvre : repo externe manquant, provisionnement de Bun/FFmpeg/Chrome, erreurs d'analyse des attributs HTML, échecs d'encodage vidéo, clones obsolètes.

Skills associés