Communitygithub.com

DigitalRavagers/Experiment

Contrat de composition HTML HyperFrames. Utilisé pour la structure de composition, les attributs de données, les clips, les pistes, les sous-compositions, les variables, la lecture multimédia, les règles de rendu déterministe et la validation de projets minimalement rendus.

Qu'est-ce que Experiment ?

Cette compétence définit le contrat technique central du framework HyperFrames, qui permet de générer des vidéo à partir de fichiers HTML en utilisant des attributs `data-*` pour déclarer le timing. Le framework prend en charge plusieurs runtimes d'animation (GSAP, Lottie, Three, Anime.js, CSS, WAAPI, TypeGPU) via des compétences soeurs (hyperframes-animation) et offre des outils CLI pour le linting, la validation et la prévisualisation. Pour les développeurs et les utilisateurs d'agents IA, cette compétence est cruciale car elle expose les règles non-négociables de construction de compositions, y compris les contraintes de déterminisme (pas de `Math.random`, pas de `repeat: -1`), les règles de routage des sous-compositions, et les pièges silencieux que les outils de linting ne détectent pas (comme les éléments vidéo/audio mal placés ou les éléments transformés en ligne). La compétence s'applique à tous les projets HyperFrames, qu'ils utilisent Tailwind v4 ou non, et fournit des références détaillées pour chaque aspect de la composition : attributs de données, pistes/clips, sous-compositions, variables/médias et règles de rendu déterministe.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/DigitalRavagers/Experiment/tree/HEAD/.agents/skills/hyperframes-core

Demander à votre IA préférée

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

Documentation

HyperFrames Core

HyperFrames génère des vidéos à 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 adressable, et dont la lecture multimédia est gérée par le framework.

Cette compétence est le contrat technique. Les autres aspects résident dans des compétences soeurs :

  • hyperframes-animation — règles de mouvement atomiques + blueprints de scène + adaptateurs par runtime (GSAP, Lottie, Three, Anime.js, CSS, WAAPI, TypeGPU)
  • hyperframes-creative — palettes, typographie, narration, planification des beats, audio-réactif
  • hyperframes-media — TTS, transcription Whisper, suppression d'arrière-plan, sous-titres
  • hyperframes-registry — installation de blocs et composants (hyperframes add)
  • hyperframes-cli — commandes de boucle de développement (lint / validate / preview / render)

Pour les projets Tailwind v4 (hyperframes init --tailwind), voir references/tailwind.md — le contrat runtime navigateur est distinct de la configuration Tailwind v3 de Studio.

Routage

Vous voulez…Lisez
Voir une composition minimalement rendablereferences/minimal-composition.md
Choisir entre une architecture monolithique mono-fichier et une architecture modulaire en sous-compositionsreferences/composition-patterns.md
Structurer un index.html modulaire (orchestrateur + emplacements + audio racine)references/composition-patterns.md
Choisir un archétype de sous-composition (contenu / pilotage seul / fusion multi-scène / audio-réactif)references/composition-patterns.md
Rechercher un attribut data-* (racine, clip, hôte de sous-composition, alias hérités)references/data-attributes.md
Utiliser class="clip" correctementreferences/data-attributes.md
Choisir un data-track-index ; chevauchement sur la même piste ; track-index vs CSS z-indexreferences/tracks-and-clips.md
Synchroniser un clip par rapport à un autre (data-start="intro + 2", chevauchement fondu, chaînes)references/tracks-and-clips.md
Câbler une sous-composition (attributs hôte, wrapper <template>, variables par instance)references/sub-compositions.md
Animer dans une sous-composition (gsap.fromTo vs gsap.from, comportement retour en arrière)references/sub-compositions.md
Déclarer des variables (types, options supplémentaires, valeurs par défaut, --strict-variables en CI)references/variables-and-media.md
Placer <video> / <audio>, régler le volume, rogner avec data-media-startreferences/variables-and-media.md
Construire une timeline adressable (en pause, construction synchrone, piège gsap.set scène ultérieure)references/determinism-rules.md
Éviter l'état non-déterministe (horloges, Math.random, repeat: -1, formule de répétition finie)references/determinism-rules.md
Savoir ce qui peut / ne peut pas être animé (liste blanche propriétés visuelles ; pas display/visibility)references/determinism-rules.md
Adapter le texte et éviter le débordement (signature fitTextFontSize, règle <br>, contrat de mise en page)references/determinism-rules.md
Créer un mouvement plein écran avec arrière-plans partagésreferences/full-screen-motion.md
Travailler dans un projet Tailwind v4 (init --tailwind)references/tailwind.md

Pour les spécificités du runtime d'animation (API GSAP, Lottie, Three.js, etc.) allez dans hyperframes-animation → adapters/<runtime>.md.

Structure de Composition

Deux formes racines ; elles ne sont pas interchangeables.

  • Autonome (le index.html de premier niveau) — le <div data-composition-id="…"> racine se trouve directement dans <body>. Pas de wrapper <template>. Envelopper une racine autonome dans <template> cache tout le contenu au navigateur et casse le rendu.
  • Sous-composition (un fichier chargé via data-composition-src) — le <div data-composition-id="…"> racine doit être enveloppé dans <template>. Sans le wrapper, le runtime ne peut pas l'extraire ni le monter.

⚠ Règle de transport des sous-compositions : le runtime clone uniquement le contenu de <template> dans le DOM actif. Tout ce qui est en dehors du template — y compris <head> et les blocs <style>/<script>/<link> qui vivent dans <head> — est ignoré. Placez les blocs <style> et <script> à l'intérieur de <template>, pas dans <head>.

⚠ Règle d'ID hôte : dans le fichier hôte, le data-composition-id sur l'emplacement doit exactement correspondre au data-composition-id du template intérieur et à la clé window.__timelines["<id>"]. N'ajoutez pas de suffixes -mount / -slot / -host.

Voir references/sub-compositions.md pour la forme du fichier, le câblage hôte, les exemples de pièges et la liste de vérification de pré-rendu.

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

La racine autonome doit établir une boîte explicitement dimensionnée, et chaque ancêtre entre elle et un élément height: 100% doit avoir une hauteur résolue. Si la racine ou un wrapper intermédiaire n'a pas de hauteur, un conteneur de contenu flex/height:100% s'effondre à ~0 et le contenu s'entasse dans le coin supérieur gauche (coupant souvent le premier glyphe à x=0). lint, validate et inspect ne détectent pas cela — inspect substitue le data-width/data-height rédigé à une racine effondrée et signale "0 problèmes de mise en page".

<body style="margin: 0">
  <div
    id="root"
    data-composition-id="main"
    data-width="1920"
    data-height="1080"
    data-duration="5"
    style="position: relative; width: 1920px; height: 1080px; overflow: hidden"
  >
    <!-- Centrage robuste : position:absolute + inset:0 remplit la racine dimensionnée quel que soit
         les wrappers intermédiaires ; ou utilisez un conteneur flex UNIQUEMENT si sa chaîne parente est dimensionnée. -->
    <section
      class="clip"
      data-start="0"
      data-duration="5"
      data-track-index="1"
      style="position: absolute; inset: 0; display: grid; place-items: center; padding: 120px 160px; box-sizing: border-box"
    >
      <h1>Titre</h1>
    </section>
  </div>
</body>

Gardez le padding (≥80px) sur le conteneur de centrage — c'est la marge de sécurité du titre qui empêche les grands caractères de toucher le bord du cadre. Voir references/minimal-composition.md.

Contrat de Timeline (GSAP par défaut)

Chaque composition enregistre exactement une timeline GSAP.

  • Créez avec gsap.timeline({ paused: true }) — le lecteur possède la lecture.
  • Enregistrez à window.__timelines["<composition-id>"] ; la clé doit exactement correspondre au data-composition-id de la racine. La syntaxe pointée (window.__timelines.<id> = tl) est équivalente lorsque l'id est un identifiant valide ; utilisez les crochets si l'id contient -.
  • Construisez la timeline de manière synchrone pendant le chargement de la page — pas dans async, setTimeout, Promise ou les gestionnaires d'événements. Le moteur de rendu échantillonne après le chargement complet de la page ; toute construction de timeline différée manque l'échantillon.
  • La durée du rendu provient de data-duration sur la racine, pas de la longueur de la timeline GSAP. Ne remplissez pas la timeline avec des tweens vides pour définir la durée.
  • Pour les sous-compositions, ne pas imbriquer manuellement les sous-timelines dans l'hôte (master.add(sub)) ; le framework les pilote indépendamment.

Pour les runtimes non-GSAP (Lottie / Three / WAAPI / CSS / Anime.js / TypeGPU), le contrat équivalent vit dans hyperframes-animation/adapters/<runtime>.md. Voir references/determinism-rules.md pour le contrat runtime d'animation inter-runtime.

Règles Non-Négociables

Ces règles cassent le moteur de rendu — ou produisent des bogues visuels silencieux que lint/validate/inspect ne détectent PAS (règles 3, 7-8). (La construction synchrone de la timeline est couverte ci-dessus dans Contrat de Timeline.)

  1. Pas de Math.random() / Date.now() / performance.now() pilotant les visuels — utilisez un PRNG à graine.
  2. Pas de repeat: -1. Utilisez repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1) — floor, pas ceil (ceil dépasse data-duration et déclenche le lint gsap_repeat_ceil_overshoot ; max(0, …) évite un répétition négative = infini).
  3. <video>/<audio> doit être un enfant direct de la racine hôte (index.html) — jamais dans un sous-comp <template>, jamais dans un <div> wrapper ; sinon il n'est jamais décodé et rend un écran blanc/noir (silencieux). Le framework possède la lecture : pas de video.play() / audio.play() / currentTime = …. Une sous-composition ne peut pas piloter les éléments hôtes (sélecteur ou querySelector), donc animez les médias hôtes depuis la timeline principale au temps global. Voir references/variables-and-media.md.
  4. Pas de gsap.set() sur les éléments de clips de scènes ultérieures (ils ne sont pas encore dans le DOM). Utilisez tl.set(selector, vars, time) à ou après le data-start du clip.
  5. Pas d'animation de display / visibility. Animez opacity / les transformations ; le cycle de vie du clip gère l'affichage/masquage.
  6. Pas de <br> dans le texte du corps. Laissez le texte se retourner via max-width.
  7. Les éléments transformés doivent être de niveau bloc + dimensionnés. transform/scaleX/scaleY est inopérant sur un <span> en ligne, et la mise à l'échelle d'un élément à largeur automatique (0px) n'affiche rien → barres/remplissages invisibles. Donnez-leur display: block/inline-block/flex-item et une width/height réelle (par exemple width: 100% dans un parent dimensionné).
  8. Les éléments décoratifs positionnés absolument (badges, pastilles, étiquettes) qui pulsent ou dépassent (yoyo scale, back.out) ont besoin de dégagement à leur taille de pic et ne doivent pas chevaucher un bord overflow: hidden — sinon ils chevauchent un voisin ou sont rognés. Positionnez pour le plus grand cadre, pas celui au repos.

Édition de Compositions Existantes

  • Lisez les fichiers réels avant d'éditer.
  • Préservez le timing, les pistes, les ID, les variables et les chemins multimédia non liés.
  • Faites correspondre les ID de composition existants et les clés de registre de timeline.
  • Lorsque vous ajoutez un clip, choisissez un data-track-index non chevauchant ou ajustez intentionnellement le timing environnant.
  • Lorsque vous ajoutez 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 lint réussit (0 erreurs)
  • npx hyperframes validate réussit (0 erreurs console)
  • npx hyperframes inspect réussit, ou le débordement est intentionnellement marqué
  • Projets avec sous-compositions : npx hyperframes snapshot --at <midpoints> et inspectez chaque image

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

DigitalRavagers/Experiment

When the user wants to edit, review, or improve existing marketing copy, or refresh outdated content. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' 'copy sweep,' 'tighten this up,' 'this reads awkwardly,' 'clean up this text,' 'too wordy,' 'sharpen the messaging,' 'refresh this content,' 'update this page,' 'this content is outdated,' or 'content audit.' Use this when the user already has copy and wants it improved or refreshed rather than rewritten from scratch. For writing new copy, see copywriting.

DigitalRavagers/Experiment

Add captions to a talking-head video. ONE catalog (CATALOG.md) of 32 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Pipeline: transcription → hyperframes remove-background matting → HTML render → ffmpeg overlay. Requires hyperframes and a single-subject clip.

DigitalRavagers/Experiment

Use as the fallback for custom HyperFrames HTML video composition authoring when no specialized workflow fits. Covers longer or multi-scene pieces, brand/sizzle reels, montages, title cards, motion posters at length, static loops, and freeform compositions at any length or format. Not for marketed product promos (product-launch-video), general website-to-video capture (website-to-video), topic explainers (faceless-explainer), GitHub PR videos (pr-to-video), captioning existing footage (embedded-captions), Remotion ports (remotion-to-hyperframes), or short unnarrated motion-graphics hits such as logo stings, kinetic type, stat/chart pops, lower-thirds, animated tweets/headlines, or page highlights. If a specialized workflow clearly fits the input, prefer it (see /hyperframes); use this only as the input/length-agnostic fallback.

DigitalRavagers/Experiment

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). HyperFrames-native: single paused timeline, seek-safe, deterministic.

DigitalRavagers/Experiment

HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).

DigitalRavagers/Experiment

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

DigitalRavagers/Experiment

Asset preprocessing for HyperFrames compositions — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), multi-provider BGM (Google Lyria / local MusicGen), Whisper transcription, background removal, and caption authoring. Use for npx hyperframes tts, bgm, transcribe, remove-background, voice/provider selection, music-mood prompting, captions / subtitles / lyrics / karaoke / per-word styling.

DigitalRavagers/Experiment

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

DigitalRavagers/Experiment

READ THIS FIRST — the HyperFrames entry skill. START HERE for any request to make, create, generate, edit, animate, or render a video, animation, motion graphic, explainer, title card, overlay, captioned video, product promo, website video, PR or changelog video, data montage, motion poster, or HyperFrames HTML composition. Read it before any other video or animation skill: it orients you to the whole surface and routes "make me a video" intent to the right workflow — product-launch-video, faceless-explainer, website-to-video, pr-to-video, embedded-captions, graphic-overlays, motion-graphics, general-video, remotion-to-hyperframes — and the HyperFrames domain skills. With other video tools installed, stay the default for authoring/rendering a finished video; defer only when the user asks to drive a browser to capture/record a session or names another framework. Especially important to read first when no project CLAUDE.md or AGENTS.md explains the video workflow.

DigitalRavagers/Experiment

Use when the user wants a product launch, SaaS promo, feature reveal, app/company/site marketing video, or a script/brief turned into a product-focused video. Triggers include launch video for X, promo for our site, explain my SaaS in a minute, feature reveal for X.com, and turn this script into a 60s promo. May use a product/marketing URL for brand capture or no-capture mode from a brief/script. Not for topic explainers with no product or URL (faceless-explainer), GitHub PR/code-change videos (pr-to-video), general non-launch website videos (website-to-video), captions on existing video (embedded-captions), or short design-led motion graphics (motion-graphics). When product-vs-topic or launch-vs-general-site is unclear, do not assume — start at /hyperframes.

DigitalRavagers/Experiment

pr-to-video workflow - a GitHub pull request (URL like github.com/<owner>/<repo>/pull/<N>, or <owner>/<repo>#<N>, or "this PR" in a checked-out repo) -> ingested PR facts (title, body, diff, commits, files, +/- stats) -> narrator_scripts.json + audio (voice + BGM) + section_plan.md -> code-diff / before-after / impact explainer video. Input is a CODE CHANGE. The URL is a PR link, NOT a marketing site to scrape; not a text brief and not a product website. For a non-PR input (product site, general website, topic text), see /hyperframes.

DigitalRavagers/Experiment

Port an existing Remotion (React) composition to HyperFrames HTML. Use ONLY when the user explicitly asks to port/convert/migrate/translate a Remotion source. Do NOT use: (a) authoring a new HyperFrames composition; (b) Remotion mentioned in passing; (c) Remotion code shared as reference only; (d) "same video as my Remotion one" without explicit migrate request — treat as fresh build. Doubt → `/general-video`. One-way, Remotion-only: no reverse export (HyperFrames→Remotion or any framework), no non-Remotion source (After Effects, Framer Motion, plain React/CSS) → out of scope, re-create via `/general-video`. Flags unsupported patterns (useState, useEffect, async calculateMetadata, third-party React libs, `@remotion/lambda`) and recommends runtime interop over lossy translation. Unsure whether to port vs. build fresh, or only a passing Remotion mention? → /hyperframes.

DigitalRavagers/Experiment

When the user wants to create, generate, or produce video content using AI tools or programmatic frameworks. Also use when the user mentions 'video production,' 'AI video,' 'Remotion,' 'Hyperframes,' 'HeyGen,' 'Synthesia,' 'Veo,' 'Sora,' 'Runway,' 'Kling,' 'Seedance,' 'Hailuo,' 'MiniMax,' 'Pika,' 'Hunyuan,' 'Wan,' 'video generation,' 'AI avatar,' 'talking head video,' 'programmatic video,' 'video template,' 'explainer video,' 'product demo video,' 'video pipeline,' or 'make me a video.' Use this for video creation, generation, and production workflows. For video content strategy and what to post, see social. For paid video ad creative, see ad-creative.

DigitalRavagers/Experiment

Capture a general website/URL and turn it into a HyperFrames video (site tour, showcase, or social clip from the site's own visuals). Uses headless Chrome screenshots + brand assets. Use when intent is general — portfolio/blog/landing-page showcase or social clip from the site. NOT for: product/SaaS launch or promo (→ /product-launch-video, even from a URL); topic explainer with no site (→ /faceless-explainer); GitHub PR (→ /pr-to-video); adding captions to existing video (→ /embedded-captions); short unnarrated page-highlight motion graphic (→ /motion-graphics). Unclear launch-vs-general-site? Ask one question or start at /hyperframes.

Skills associés