Communitygithub.com

DigitalRavagers/Experiment

Contrato de composición HTML para HyperFrames. Útil para estructura de composición, atributos de datos, clips, pistas, subcomposiciones, variables, reproducción multimedia, reglas de renderizado deterministas y validación de proyectos renderizables mínimos.

¿Qué es Experiment?

Este skill define el contrato técnico central para HyperFrames, un sistema que compone video a partir de archivos HTML. Describe cómo estructurar composiciones usando atributos `data-*` en el DOM para declarar temporización, y cómo el framework gestiona la reproducción multimedia de manera determinista. Es compatible con proyectos GSAP, Lottie, Three.js, Anime.js y otros entornos de ejecución de animación, y distingue entre composiciones independientes (archivo `index.html` raíz) y subcomposiciones (archivos envueltos en `<template>`). Incluye reglas no negociables para evitar errores silenciosos de renderizado, como prohibir `Math.random()` o `repeat: -1`, y exige que los elementos `<video>/<audio>` sean hijos directos de la composición raíz. También cubre la estructura de la línea de tiempo, la validación mediante comandos CLI (`lint`, `validate`, `inspect`) y recomendaciones de edición para composiciones existentes. Es fundamental para desarrolladores que quieran crear proyectos de video renderizables y predecibles con HyperFrames.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

HyperFrames Core

HyperFrames renderiza video a partir de HTML. Una composición es un archivo HTML cuyo DOM declara la temporización mediante atributos data-*, cuyo tiempo de ejecución de animación es buscable, y cuya reproducción multimedia es gestionada por el framework.

Este skill es el contrato técnico. Otras áreas de interés residen en skills hermanos:

  • hyperframes-animation — reglas de movimiento atómico + planos de escena + adaptadores por entorno de ejecución (GSAP, Lottie, Three, Anime.js, CSS, WAAPI, TypeGPU)
  • hyperframes-creative — paletas, tipografía, narración, planificación de ritmo, reactividad de audio
  • hyperframes-media — TTS, transcripción con Whisper, eliminación de fondo, subtítulos
  • hyperframes-registry — instalar bloques y componentes (hyperframes add)
  • hyperframes-cli — comandos del bucle de desarrollo (lint / validate / preview / render)

Para proyectos con Tailwind v4 (hyperframes init --tailwind), consulta references/tailwind.md — el contrato del entorno de ejecución del navegador es distinto a la configuración de Tailwind v3 de Studio.

Enrutamiento

Si deseas…Lee
Ver una composición renderizable mínimareferences/minimal-composition.md
Decidir entre arquitectura monolítica de archivo único o modular con subcompreferences/composition-patterns.md
Estructurar un index.html modular (orquestador + slots + audio raíz)references/composition-patterns.md
Elegir un arquetipo de subcomp (contenido / solo driver / fusión multiescena / reactivo a audio)references/composition-patterns.md
Consultar un atributo data-* (raíz, clip, host de subcomp, alias heredados)references/data-attributes.md
Usar class="clip" correctamentereferences/data-attributes.md
Elegir un data-track-index; superposición en misma pista; track-index vs CSS z-indexreferences/tracks-and-clips.md
Temporizar un clip relativo a otro (data-start="intro + 2", superposición de crossfade, cadenas)references/tracks-and-clips.md
Conectar una subcomposición (atributos del host, envoltorio <template>, variables por instancia)references/sub-compositions.md
Animar dentro de una subcomposición (gsap.fromTo sobre gsap.from, comportamiento de búsqueda hacia atrás)references/sub-compositions.md
Declarar variables (tipos, opciones extra, valores predeterminados, --strict-variables en CI)references/variables-and-media.md
Colocar <video> / <audio>, ajustar volumen, recortar con data-media-startreferences/variables-and-media.md
Construir una línea de tiempo buscable (pausada, construcción síncrona, trampa gsap.set en escenas posteriores)references/determinism-rules.md
Evitar estado no determinista (relojes, Math.random, repeat: -1, fórmula de repetición finita)references/determinism-rules.md
Saber qué se puede / no se puede animar (lista blanca de propiedades visuales; no display/visibility)references/determinism-rules.md
Ajustar texto y evitar desbordamiento (firma de fitTextFontSize, regla de <br>, contrato de diseño)references/determinism-rules.md
Crear movimiento a pantalla completa con fondos compartidosreferences/full-screen-motion.md
Trabajar en un proyecto Tailwind v4 (init --tailwind)references/tailwind.md

Para detalles específicos del entorno de ejecución de animación (API GSAP, Lottie, Three.js, etc.) ve a hyperframes-animation → adapters/<runtime>.md.

Estructura de la Composición

Dos formas raíz; no son intercambiables.

  • Independiente (el index.html de nivel superior) — el <div data-composition-id="…"> raíz se encuentra directamente en <body>. Sin envoltorio <template>. Envolver una raíz independiente en <template> oculta todo el contenido del navegador y rompe el renderizado.
  • Subcomposición (un archivo cargado mediante data-composition-src) — el <div data-composition-id="…"> raíz debe estar envuelto en <template>. Sin el envoltorio, el entorno de ejecución no puede extraerlo ni montarlo.

⚠ Regla de transporte de subcomposición: el entorno de ejecución solo clona el contenido de <template> en el DOM vivo. Todo lo que está fuera de la plantilla — incluyendo <head> y cualquier bloque <style>/<script>/<link> que resida en <head> — se descarta. Coloca los bloques <style> y <script> dentro de <template>, no en <head>.

⚠ Regla de ID de host: en el archivo host, data-composition-id en el slot debe ser exactamente igual al data-composition-id de la plantilla interna y a la clave window.__timelines["<id>"]. No agregues sufijos -mount / -slot / -host.

Consulta references/sub-compositions.md para la forma del archivo, cableado del host, ejemplos de errores y la lista de verificación previa al renderizado.

La raíz debe tener tamaño (error de diseño silencioso)

La raíz independiente debe establecer un cuadro con tamaño explícito, y cada ancestro entre ella y un elemento con height: 100% debe tener una altura resuelta. Si la raíz o un envoltorio intermedio no tiene altura, un contenedor de contenido flex/height:100% se colapsa a ~0 y el contenido se apila en la esquina superior izquierda (a menudo recortando el primer glifo en x=0). lint, validate e inspect no detectan esto — inspect sustituye el data-width/data-height proporcionado por una raíz colapsada e informa "0 problemas de diseño."

<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"
  >
    <!-- Centrar de forma robusta: position:absolute + inset:0 llena la raíz con tamaño independientemente de
         envoltorios intermedios; o usa un contenedor flex SOLO si su cadena padre tiene tamaño. -->
    <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>Título</h1>
    </section>
  </div>
</body>

Mantén el padding (≥80px) en el contenedor de centrado — es el margen de seguridad del título que evita que el texto grande toque el borde del fotograma. Consulta references/minimal-composition.md.

Contrato de Línea de Tiempo (GSAP por defecto)

Cada composición registra exactamente una línea de tiempo de GSAP.

  • Crea con gsap.timeline({ paused: true }) — el reproductor controla la reproducción.
  • Registra en window.__timelines["<composition-id>"]; la clave debe coincidir exactamente con el data-composition-id de la raíz. La sintaxis de punto (window.__timelines.<id> = tl) es equivalente cuando el id es un identificador válido; usa corchetes si el id contiene -.
  • Construye la línea de tiempo de forma síncrona durante la carga de la página — no dentro de async, setTimeout, Promise o manejadores de eventos. El renderizador muestrea después de que la carga de la página se completa; cualquier construcción diferida de la línea de tiempo pierde la muestra.
  • La duración del renderizado proviene de data-duration en la raíz, no de la longitud de la línea de tiempo de GSAP. No rellenes la línea de tiempo con interpolaciones vacías para establecer la duración.
  • Para subcomposiciones, no anides manualmente sublíneas de tiempo en el host (master.add(sub)); el framework las controla de forma independiente.

Para otros entornos de ejecución (Lottie / Three / WAAPI / CSS / Anime.js / TypeGPU), el contrato equivalente se encuentra en hyperframes-animation/adapters/<runtime>.md. Consulta references/determinism-rules.md para el Contrato de Entorno de Ejecución de Animación multiplataforma.

Reglas No Negociables

Estas rompen el renderizador — o producen errores visuales silenciosos que lint/validate/inspect NO detectan (reglas 3, 7-8). (La construcción síncrona de la línea de tiempo se cubre arriba en Contrato de Línea de Tiempo.)

  1. No usar Math.random() / Date.now() / performance.now() para controlar elementos visuales — usa un PRNG con semilla.
  2. No usar repeat: -1. Usa repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1) — floor, no ceil (ceil sobrepasa data-duration y activa el lint gsap_repeat_ceil_overshoot; max(0, …) evita un repeat negativo = infinito).
  3. <video>/<audio> debe ser hijo directo de la raíz del host (index.html) — nunca dentro de un <template> de subcomp, nunca dentro de un <div> envoltorio; de lo contrario, nunca se decodifica y se renderiza en blanco/negro (silencioso). El framework controla la reproducción: no usar video.play() / audio.play() / currentTime = …. Una subcomp no puede controlar elementos del host (selector o querySelector), así que anima el multimedia del host desde la línea de tiempo principal a tiempo global. Consulta references/variables-and-media.md.
  4. No usar gsap.set() en elementos de clip de escenas posteriores (aún no están en el DOM). Usa tl.set(selector, vars, time) en o después del data-start del clip.
  5. No animar display / visibility. Anima opacity / transformaciones; el ciclo de vida del clip maneja mostrar/ocultar.
  6. No usar <br> en el cuerpo del texto. Deja que el texto se ajuste mediante max-width.
  7. Los elementos transformados deben ser de nivel de bloque + tener tamaño. transform/scaleX/scaleY es inoperante en un <span> inline, y escalar un elemento con ancho automático (0px) no muestra nada → barras/rellenos invisibles. Dales display: block/inline-block/flex-item y un width/height real (por ejemplo, width: 100% dentro de un padre con tamaño).
  8. Los elementos decorativos posicionados absolutamente (insignias, píldoras, etiquetas) que pulsen o sobrepasen (escala yoyo, back.out) necesitan espacio libre en su tamaño máximo y no deben cruzar un borde overflow: hidden — de lo contrario se superponen a un vecino o se recortan. Posiciona para el fotograma más grande, no para el de reposo.

Editar Composiciones Existentes

  • Lee los archivos reales antes de editar.
  • Conserva la temporización, pistas, IDs, variables y rutas multimedia no relacionadas.
  • Coincide con los IDs de composición y las claves de registro de la línea de tiempo existentes.
  • Al agregar un clip, elige un data-track-index que no se superponga o ajusta intencionadamente la temporización circundante.
  • Al agregar una subcomposición, verifica su data-composition-id interno antes de conectar el host.

Validación

Usa hyperframes-cli para los detalles de los comandos.

  • npx hyperframes lint pasa (0 errores)
  • npx hyperframes validate pasa (0 errores de consola)
  • npx hyperframes inspect pasa, o el desbordamiento está marcado intencionadamente
  • Proyectos con subcomposiciones: npx hyperframes snapshot --at <midpoints> y revisa visualmente cada fotograma

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 relacionados