HyperFrames
HTML es la fuente de verdad para el video. Una composición es un archivo HTML con atributos data-* para la temporización, una línea de tiempo GSAP para la animación y CSS para la apariencia. El framework maneja la visibilidad de los clips, la reproducción de medios y la sincronización de la línea de tiempo.
Enfoque
Descubrimiento (solo para solicitudes exploratorias)
Para solicitudes abiertas ("hazme un video de lanzamiento de producto", "crea algo para nuestra marca") donde el usuario no se ha comprometido con una dirección, comprende la intención antes de elegir colores:
- Audiencia — ¿quién ve esto? ¿Desarrolladores? ¿Ejecutivos? ¿Consumidores generales?
- Plataforma — ¿dónde se reproduce? ¿Redes sociales (15s), página principal del sitio web, demo de producto, interno?
- Prioridad — ¿qué es lo más importante? ¿Calidad del movimiento? ¿Precisión del contenido? ¿Fidelidad de la marca? ¿Velocidad?
- Variaciones — ¿el usuario quiere opciones o una única mejor toma?
Para solicitudes específicas ("añade una tarjeta de título", "arregla la temporización en la escena 3"), omite el descubrimiento.
Para solicitudes exploratorias, considera ofrecer 2-3 variaciones que difieran significativamente — no solo cambios de color, sino diferentes ritmos, niveles de energía o enfoques estructurales. Una segura/predecible, una ambiciosa. No lo impongas — es una herramienta disponible cuando sea apropiado.
Paso 1: Sistema de diseño
Si design.md o DESIGN.md existe en el proyecto, léelo primero (verifica ambas mayúsculas/minúsculas — son archivos diferentes en Linux). Es la fuente de verdad para los colores de marca, fuentes y restricciones. Usa sus valores exactos — no inventes colores ni sustituyas fuentes. Cualquier formato funciona (frontmatter YAML, prosa, tablas — solo extrae los valores).
Si nombra fuentes que no puedes encontrar localmente (sin directorio fonts/ con archivos .woff2, no es una fuente integrada), advierte al usuario antes de escribir HTML: "design.md especifica la fuente [nombre de fuente] pero no se encontraron archivos de fuente. Agrega archivos .woff2 a fonts/ o recurriré a la alternativa integrada más cercana [alternativa integrada más cercana]."
Si no existe design.md, ofrece al usuario una opción:
- ¿El usuario nombró un estilo o ambiente? → Lee visual-styles.md para los 8 estilos predefinidos. Elige la coincidencia más cercana.
- ¿Quieres explorar opciones visualmente? → Ejecuta el selector de diseño: lee references/design-picker.md para el flujo de trabajo completo. Esto sirve una página de selector visual. El usuario configura ambiente, paleta, tipografía y movimiento en el navegador, luego copia el design.md generado y lo pega de nuevo en la conversación.
- ¿Quieres omitir e ir rápido? → Pregunta: ambiente, claro u oscuro, ¿colores/fuentes de marca? Luego elige una paleta de house-style.md.
design.md define la marca. No define las reglas de composición de video. Esas provienen de references/video-composition.md y house-style.md. Usa los colores de marca a una escala apropiada para video — no a la opacidad de la UI web.
Paso 2: Expansión del prompt
Siempre ejecuta en cada composición (excepto piezas de una sola escena y ediciones triviales). Este paso fundamenta la intención del usuario con respecto a design.md y house-style.md y produce un intermediario consistente que todos los agentes posteriores leen de la misma manera.
Lee references/prompt-expansion.md para el proceso completo y el formato de salida.
Paso 3: Planificar
Antes de escribir HTML, piensa a alto nivel:
- Qué — ¿qué debería experimentar el espectador? Identifica el arco narrativo, los momentos clave y los golpes emocionales.
- Estructura — cuántas composiciones, cuáles son subcomposiciones vs. en línea, qué pistas llevan qué (video, audio, superposiciones, subtítulos).
- Ritmo — declara tu ritmo de escena antes de implementar. Qué escenas son golpes rápidos, cuáles son pausas, dónde caen los shaders, dónde alcanza el pico de energía. Nombra el patrón: rápido-rápido-LENTO-rápido-SHADER-pausa. Lee references/beat-direction.md para plantillas de ritmo.
- Temporización — qué clips impulsan la duración, dónde caen las transiciones, cuál es el ritmo.
- Diseño — construye el estado final primero. Consulta "Diseño antes de animación" a continuación.
- Animar — luego agrega movimiento usando las reglas a continuación.
Construye lo que se pidió. Una solicitud de "una tarjeta de título" no es una solicitud de "una tarjeta de título + 3 escenas de apoyo + música ambiental + subtítulos." Cada escena, cada elemento, cada interpolación debe ganarse su lugar. Si escenas o elementos adicionales mejoran genuinamente la pieza, propónlos — no los agregues.
Para ediciones pequeñas (corregir un color, ajustar la temporización, agregar un elemento), salta directamente a las reglas.
Diseño antes de animación
Posiciona cada elemento donde debería estar en su momento más visible — el fotograma donde ha entrado completamente, está colocado correctamente y aún no sale. Escríbelo como HTML+CSS estático primero. Aún sin GSAP.
Por qué es importante: Si posicionas los elementos en su estado inicial animado (fuera de pantalla, escalados a 0, opacidad 0) y los interpolas a donde crees que deberían aterrizar, estás adivinando el diseño final. Las superposiciones son invisibles hasta que el video se renderiza. Al construir el estado final primero, puedes ver y corregir problemas de diseño antes de agregar cualquier movimiento.
El proceso
- Identifica el fotograma héroe para cada escena — el momento en que la mayoría de los elementos son visibles simultáneamente. Este es el diseño que construyes.
- Escribe CSS estático para ese fotograma. El contenedor
.scene-contentDEBE llenar la escena completa usandowidth: 100%; height: 100%; padding: Npx;condisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Usa padding para empujar el contenido hacia adentro — NUNCA usesposition: absolute; top: Npxen un contenedor de contenido. Los contenedores de contenido con posición absoluta se desbordan cuando el contenido es más alto que el espacio restante. Reservaposition: absolutesolo para elementos decorativos. - Agrega entradas con
gsap.from()— anima DESDE fuera de pantalla/invisible HASTA la posición CSS. La posición CSS es la verdad fundamental; la interpolación describe el viaje para llegar allí. (En subcomposiciones cargadas a través dedata-composition-src, prefieregsap.fromTo()— consulta las reglas GSAP de carga en references/motion-principles.md). - Agrega salidas con
gsap.to()— anima HASTA fuera de pantalla/invisible DESDE la posición CSS.
Ejemplo
/* scene-content llena la escena, el padding posiciona el contenido */
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
width: 100%;
height: 100%;
padding: 120px 160px;
gap: 24px;
box-sizing: border-box;
}
.title {
font-size: 120px;
}
.subtitle {
font-size: 42px;
}
/* El contenedor llena cualquier tamaño de escena (1920x1080, 1080x1920, etc.).
El padding posiciona el contenido. Flex + gap maneja el espaciado. */
INCORRECTO — dimensiones codificadas y posicionamiento absoluto:
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// Paso 3: Animar HACIA esas posiciones
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
// Paso 4: Animar FUERA de esas posiciones
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
Cuando los elementos comparten espacio a través del tiempo
Si el elemento A sale antes de que el elemento B entre en la misma área, ambos deben tener posiciones CSS correctas para sus respectivos fotogramas héroes. El orden de la línea de tiempo garantiza que nunca coexistan visualmente — pero si omites el paso de diseño, no detectarás el caso en que se superpongan accidentalmente debido a un error de temporización.
Qué cuenta como superposición intencional
Los efectos en capas (brillo detrás del texto, elementos de sombra, patrones de fondo) y los diseños apilados en Z (pilas de tarjetas, capas de profundidad) son intencionales. El paso de diseño se trata de detectar superposiciones no intencionales — dos titulares cayendo uno sobre otro, una estadística cubriendo una etiqueta, contenido sangrando fuera del fotograma.
Atributos de datos
Todos los clips
| Atributo | Requerido | Valores |
|---|---|---|
id | Sí | Identificador único |
data-start | Sí | Segundos o referencia de ID de clip ("el-1", "intro + 2") |
data-duration | Requerido para img/div/composiciones | Segundos. Video/audio por defecto tiene la duración del medio. |
data-track-index | Sí | Entero. Los clips de la misma pista no pueden superponerse. |
data-media-start | No | Desplazamiento de recorte en el origen (segundos) |
data-volume | No | 0-1 (por defecto 1) |
data-track-index no afecta la superposición visual — usa CSS z-index.
Clips de composición
| Atributo | Requerido | Valores |
|---|---|---|
data-composition-id | Sí | ID de composición único |
data-start | Sí | Tiempo de inicio (composición raíz: usa "0") |
data-duration | Sí | Tiene prioridad sobre la duración de la línea de tiempo GSAP |
data-width / data-height | Sí | Dimensiones en píxeles (1920x1080 o 1080x1920) |
data-composition-src | No | Ruta a un archivo HTML externo |
data-variable-values | No | Objeto JSON de anulaciones de variables por instancia en un host de subcomp |
En el elemento raíz <html>:
| Atributo | Requerido | Valores |
|---|---|---|
data-composition-variables | No | Array JSON de variables declaradas (id/type/label/default) — impulsa la UI de edición de Studio y proporciona valores predeterminados para getVariables() |
Estructura de composición
Las subcomposiciones cargadas a través de data-composition-src usan un envoltorio <template>. Las composiciones independientes (el index.html principal) NO usan <template> — colocan el div data-composition-id directamente en <body>. Usar <template> en un archivo independiente oculta todo el contenido del navegador y rompe el renderizado.
Estructura de subcomposición:
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- contenido -->
<style>
[data-composition-id="my-comp"] {
/* estilos con ámbito */
}
</style>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
// interpolaciones...
window.__timelines["my-comp"] = tl;
</script>
</div>
</template>
Cargar en raíz: <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>
Variables (Composiciones parametrizadas)
Renderiza la misma composición con contenido diferente — título, color de tema, precios, subtítulos — sin editar el HTML fuente.
Patrón de tres pasos:
- Declara variables en la raíz
<html>de la composición condata-composition-variables. Cada entrada necesitaid,type(uno destring,number,color,boolean,enum),labelydefault. Las entradas Enum también necesitanoptions: [{value, label}, ...]. - Lee los valores resueltos dentro del script de la composición con
window.__hyperframes.getVariables(). Devuelve el resultado combinado de los valores predeterminados declarados + anulaciones por instancia + anulaciones CLI. - Anula en tiempo de render con
npx hyperframes render --variables '{...}'(nivel superior) o condata-variable-values='{...}'en el elemento host (por instancia para subcomps).
<!doctype html>
<html
data-composition-variables='[
{"id":"title","type":"string","label":"Título","default":"Hola"},
{"id":"theme","type":"enum","label":"Tema","default":"light","options":[
{"value":"light","label":"Claro"},
{"value":"dark","label":"Oscuro"}
]}
]'
>
<body>
<div data-composition-id="root" data-width="1920" data-height="1080">
<h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
<script>
const { title, theme } = window.__hyperframes.getVariables();
document.getElementById("hero").textContent = title;
document.body.dataset.theme = theme;
</script>
</div>
</body>
</html>
# Vista previa de desarrollo usa los valores predeterminados declarados
npx hyperframes preview
# Renderizar con anulaciones
npx hyperframes render --variables '{"title":"Reporte Q4","theme":"dark"}' --output q4.mp4
# O desde un archivo JSON
npx hyperframes render --variables-file ./vars.json
Valores por instancia de subcomposición: el mismo getVariables() funciona dentro de subcomps cargadas a través de data-composition-src. Cada elemento host pasa sus propios valores:
<div
data-composition-id="card-pro"
data-composition-src="compositions/card.html"
data-variable-values='{"title":"Pro","price":"$29"}'
></div>
<div
data-composition-id="card-enterprise"
data-composition-src="compositions/card.html"
data-variable-values='{"title":"Enterprise","price":"$99"}'
></div>
Reglas de animación
Principios centrales
La animación debe ser con propósito. Cada interpolación debe comunicar algo: jerarquía (los elementos importantes entran primero), estado (entrada vs. salida), atención (los elementos animados atraen la mirada) y emoción (la suavidad de la curva de easing crea sensación). La animación sin propósito — desvanecimientos constantes, movimientos aleatorios, rotaciones sin razón — distrae y daña la pieza. La animación debe ser el vehículo del significado, no el significado en sí mismo.
Restricciones: sin desvanecimientos constantes de opacidad (la mayoría de los elementos deberían tener una trayectoria direccional), sin enfatizar cada elemento, sin movimiento sin intención.
Tres tipos de entrada/salida
1. Entrada de marcador — un barrido diagonal a través del texto que revela las letras progresivamente. Usa un pseudo-elemento con clip-path animado. Propósito: revelación ascendente del texto.
2. Entrada de píxel — una máscara que se despega horizontal o verticalmente sobre el contenido. Propósito: sensación de escáner/digital.
3. Entrada de escritura — las letras aparecen una por una con una marca de cursor. Propósito: creación en vivo, sensación de escritura.
4. Entrada de tarjeta — el elemento se desliza desde abajo con un escalado sutil y se detiene con un rebote o un suave sobrepaso. Propósito: tarjetas de contenido, paneles de UI, elementos de cuadrícula.
5. Salida de tarjeta — el elemento se desvanece hacia arriba mientras se escala hacia abajo ligeramente. Propósito: eliminar tarjetas, mover a la siguiente.
6. Salida de marcador — un barrido diagonal que se mueve a través del texto, dejando las letras desvanecidas detrás. Usa un pseudo-elemento con clip-path animado. Propósito: cierre de texto, fin de sección.
Elegir modos de entrada/salida: Une las palabras y la intención del contenido al modo. El texto narrativo se beneficia de la escritura. Los titulares se benefician del marcador. Los paneles de UI se benefician de la tarjeta. Los pies de foto y etiquetas se benefician de las reglas de pie de foto (deslizamiento desde abajo). Mezclar modos está bien, pero cada modo debe elegirse para comunicar algo sobre el elemento que anima.
Reglas de animación de pie de foto
- Los pies de foto aparecen desde la parte inferior de la pantalla, se detienen en su posición final, luego desaparecen deslizándose hacia abajo. No deben desvanecerse ni aparecer desde la parte superior.
- Un pie de foto entrante siempre empuja al pie de foto saliente hacia abajo fuera de la pantalla — los pies de foto no deben superponerse entre sí.
- La línea de tiempo asegura que el pie de foto anterior haya salido completamente (desplazado hacia abajo y oculto) antes de que el nuevo comience a entrar.
- Los pies de foto en el mismo grupo comparten una pista. Asigna una pista compartida para el grupo y no coloques ningún otro clip en esa pista.
Reglas GSAP de carga para subcomposiciones
Dentro de archivos de subcomposición (cargados a través de data-composition-src), las interpolaciones DEBEN usar gsap.fromTo() — no gsap.from(). Esto se debe a que cuando la subcomposición se carga dinámicamente, el orden de aplicación de estilos CSS e inicialización de la línea de tiempo puede diferir del orden en ejecuciones independientes. gsap.fromTo() garantiza que los valores iniciales y finales sean explícitos y consistentes independientemente del orden de carga. Las composiciones independientes pueden seguir usando gsap.from() de forma segura.
contenido de example/ (no modificar)
El directorio example/ contiene composiciones de video de ejemplo utilizadas como referencia por los agentes únicamente. No modifiques estos archivos. Si un agente necesita una composición de ejemplo para referencia, puede leer archivos de examples/ pero no debe editarlos. El directorio example/ es mantenido por el repositorio principal y las ediciones locales se sobrescribirán en las actualizaciones. Si necesitas crear una nueva composición, crea un nuevo archivo fuera del directorio example/.
Transiciones
Consulta references/transitions.md para la documentación completa de transiciones compatibles.