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 clips, la reproducción de medios y la
sincronización de la línea de tiempo.
API de atributos, estructura de composición/plantilla, variables y reglas de medios: references/authoring.md. Léelo antes de escribir tu primera composición HTML en una sesión.
Enfoque
Descubrimiento (solo para solicitudes exploratorias)
Para solicitudes abiertas ("hazme un video de lanzamiento de producto") donde el usuario no se ha comprometido con una dirección, entiende la intención antes de elegir colores: audiencia, plataforma, prioridad (calidad del movimiento vs precisión vs velocidad), y si quieren variaciones. Si hay variaciones, ofrece 2-3 que difieran en ritmo o estructura - una segura, una ambiciosa - no intercambios de color.
Para solicitudes específicas ("añade una tarjeta de título", "arregla la temporización de la escena 3"), omite el descubrimiento.
Paso 1: Sistema de diseño
Si existe design.md o DESIGN.md, léelo primero (ambas mayúsculas/minúsculas - son
archivos diferentes en Linux). Es la fuente de verdad para colores de marca,
fuentes y restricciones - usa sus valores exactos. Si nombra fuentes sin
archivos .woff2 en fonts/ y sin coincidencia incorporada, advierte al usuario antes
de escribir HTML.
Si no existe design.md, ofrece una opción:
- ¿El usuario nombró un estilo o estado de ánimo? Lee visual-styles.md (8 ajustes preestablecidos con nombre), elige el más cercano.
- ¿Navegar visualmente? Ejecuta el selector de diseño - references/design-picker.md.
- ¿Ir rápido? Pregunta estado de ánimo, claro/oscuro, colores/fuentes de marca; elige una paleta de house-style.md.
design.md define la marca, no las reglas de composición de video. Esas vienen de references/video-composition.md y house-style.md. Colores de marca a escala de video, no opacidad de interfaz web.
Paso 2: Expansión del prompt
Ejecutar en cada composición excepto piezas de una sola escena y ediciones triviales - fundamenta la intención contra design.md/house-style.md en un intermedio consistente. Proceso y formato: references/prompt-expansion.md.
Paso 3: Planificar
- Qué - arco narrativo, momentos clave, latidos emocionales.
- Estructura - cuántas composiciones, sub-comps vs en línea, qué pistas llevan qué.
- Ritmo - declara el ritmo de la escena antes de implementar (rápido-rápido-LENTO-rápido-SHADER-pausa). Plantillas: references/beat-direction.md.
- Temporización - qué clips impulsan la duración, dónde caen las transiciones.
- Diseño - construye primero el estado final (siguiente sección).
- Animar - luego añade movimiento.
Construye lo que se pidió. "Una tarjeta de título" no es "una tarjeta de título + 3 escenas de apoyo + música + subtítulos." Propón extras; no los añadas.
Para ediciones pequeñas, salta directamente a las reglas.
Diseño Antes de la Animación
Posiciona cada elemento donde debería estar en su momento más visible - completamente entrado, colocado correctamente, sin haber salido aún. Escríbelo como HTML+CSS estático primero. Sin GSAP todavía.
Por qué: si posicionas los elementos en su estado de inicio animado (fuera de pantalla, opacidad 0) y haces una interpolación hacia donde crees que aterrizan, estás adivinando el diseño final, y las superposiciones permanecen invisibles hasta el render. Construye el estado final primero y los errores de diseño son visibles antes de que exista el movimiento.
- Identifica el fotograma héroe por escena - el momento en que la mayoría de los elementos están simultáneamente visibles. Construye ese diseño.
- Escribe CSS estático para él.
.scene-contentDEBE llenar la escena:width: 100%; height: 100%; padding: Npx;condisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-box. El padding empuja el contenido hacia adentro - NUNCA usesposition: absolute; top: Npxen un contenedor de contenido (se desborda cuando el contenido crece). Reserva el posicionamiento absoluto para elementos decorativos. - Entradas con
gsap.from()- anima DESDE fuera de pantalla HASTA la posición CSS. CSS es la verdad fundamental; la interpolación es el viaje. (Sub-comps cargadas víadata-composition-src: prefieregsap.fromTo()- consulta references/motion-principles.md.) - Solo la última escena: salidas con
gsap.to(). Todas las demás escenas terminan completamente visibles - la transición ES la salida (regla de transición 3 a continuación).
Si el elemento A sale antes de que el elemento B entre en la misma área, da a ambos posiciones CSS correctas para sus propios fotogramas héroes - la línea de tiempo evita que coexistan, y el paso de diseño detecta la superposición accidental de errores de temporización. La superposición intencional (brillo detrás del texto, pilas de tarjetas) está bien; el paso existe para detectar superposición no intencional - dos titulares chocando, una estadística cubriendo una etiqueta, contenido fuera del fotograma.
Contrato de Línea de Tiempo
- Todas las líneas de tiempo comienzan
{ paused: true }- el reproductor controla la reproducción - Registra cada línea de tiempo:
window.__timelines["<id-de-composición>"] = tl - El framework anida automáticamente las sub-líneas de tiempo - NO las añadas manualmente
- La duración proviene de
data-duration, no de la longitud de la línea de tiempo GSAP - Nunca crees interpolaciones vacías para establecer la duración
Reglas (No Negociables)
Determinista: sin Math.random(), Date.now(), o lógica basada en tiempo.
PRNG con semilla (ej. mulberry32) para pseudoaleatoriedad.
GSAP: solo anima propiedades visuales (opacity, x, y, scale,
rotation, color, backgroundColor, borderRadius, transformaciones). Nunca
animes visibility o display; nunca llames a video.play()/audio.play().
Conflictos de animación: nunca animes la misma propiedad en el mismo elemento desde múltiples líneas de tiempo simultáneamente.
Sin repeat: -1: las repeticiones infinitas rompen el motor de captura. Calcula
repeat: Math.ceil(duracion / duracionCiclo) - 1.
Construcción síncrona de líneas de tiempo: nunca construyas líneas de tiempo dentro
de async/await, setTimeout, o Promesas - el motor de captura lee
window.__timelines síncronamente después de la carga. Las fuentes están incrustadas por el
compilador; no esperes a la carga de fuentes.
Nunca hagas:
- Olvidar el registro de
window.__timelines - Usar video para audio - siempre video silenciado +
<audio>separado - Anidar video dentro de un div temporizado - usa un contenedor no temporizado
- Usar
data-layer(usadata-track-index) odata-end(usadata-duration) - Animar dimensiones del elemento de video - anima un div contenedor
- Llamar a play/pause/seek en los medios - el framework posee la reproducción
- Crear un contenedor de nivel superior sin
data-composition-id - Usar
repeat: -1en cualquier línea de tiempo o interpolación - Construir líneas de tiempo asíncronamente
- Usar
gsap.set()en elementos de clip de escenas posteriores - no existen en el DOM en la carga de la página. Usatl.set(selector, vars, timePosition)en o después deldata-startdel clip. - Usar
<br>en el texto del contenido - se apila con el ajuste natural y causa superposición; usamax-widthen su lugar. Excepción: títulos de visualización cortos deliberadamente una palabra por línea.
Transiciones de Escena (No Negociables)
Toda composición de múltiples escenas DEBE seguir las cuatro. Violar cualquiera es una composición rota.
- SIEMPRE usa transiciones entre escenas. Sin cortes bruscos.
- SIEMPRE anima CADA elemento ENTRANDO vía
gsap.from(). Nada aparece completamente formado. Cinco elementos significan cinco interpolaciones de entrada. - NUNCA uses animaciones de salida excepto en la última escena. Sin
gsap.to()desvaneciendo opacidad, moviendo fuera de pantalla, o escalando a 0 antes de una transición - la transición ES la salida, y la escena saliente debe estar completamente visible cuando se active. Una interpolación de salida antes de una transición entrega a la transición un fotograma vacío. - Solo la última escena puede desvanecer elementos.
Selección e implementación de transiciones: references/transitions.md.
Barreras de Protección de Animación
- Desplaza la primera animación 0.1-0.3s (no t=0)
- Varía las curvas de suavizado - al menos 3 curvas diferentes por escena, sin patrón de entrada repetido dentro de una escena
- Evita gradientes lineales de pantalla completa sobre fondos oscuros (bandas H.264) - radial o sólido + brillo localizado
- Titulares de 60px+, cuerpo de 20px+, etiquetas de datos de 16px+
font-variant-numeric: tabular-numsen columnas de números
Editar Composiciones Existentes
- Lee los archivos reales, no adivines. La composición ES la especificación - extrae códigos hex exactos, fuentes y patrones de suavizado de la fuente, no de la memoria.
- Solo cambia lo que se solicitó; conserva la temporización de clips no relacionados.
Lista de Verificación de Salida
Rápido (ejecutar inmediatamente, bloquear en resultados):
-
npx hyperframes lintynpx hyperframes validatepasan ambos - Adherencia al diseño verificada si existe design.md
Lento (ejecutar en paralelo mientras se presenta la vista previa):
-
npx hyperframes inspectpasa, o cada desbordamiento reportado está marcado intencionalmente - Advertencias de contraste abordadas
- Coreografía de animación verificada (script de mapa de animación)
Cómo ejecutar y corregir cada verificación: references/quality-checks.md.
Índice de Referencias
Leer siempre para cualquier composición nueva:
| Archivo | Cubre |
|---|---|
| references/authoring.md | atributos data, estructura de plantilla, variables, video/audio, fuentes/activos |
| references/video-composition.md | reglas de medio de video - estas anulan los instintos web |
| references/typography.md | emparejamiento de fuentes, OpenType, ajustes de fondo oscuro |
| references/motion-principles.md | diseño de movimiento, movimiento de imagen, reglas GSAP de soporte de carga |
Leer siempre también para composiciones de múltiples escenas:
| Archivo | Cubre |
|---|---|
| references/beat-direction.md | plantillas de ritmo, verbos de coreografía, capas de profundidad |
| references/transitions.md | selección de transiciones; catálogo enruta a implementaciones; las transiciones de shader viven en el paquete npm @hyperframes/shader-transitions (lee su fuente en node_modules) |
Leer cuando la tarea lo requiera:
| Archivo | Leer cuando |
|---|---|
| references/quality-checks.md | ejecutando verificaciones de inspect/contraste/diseño/mapa de animación |
| references/cli.md | cualquier comando CLI; solución de problemas de compilación/renderizado |
| references/captions.md | cualquier texto sincronizado con la temporización de audio |
| references/transcript-guide.md | manejo de transcripciones del lado de los subtítulos (la invocación CLI vive en media.md) |
| references/dynamic-techniques.md | animación de subtítulos dinámicos (karaoke, slam, dispersión) |
| references/audio-reactive.md | visuales que responden a música/voz |
| references/css-patterns.md | resaltado de marcadores (resaltado, círculo, explosión, garabato) |
| references/techniques.md | técnicas de planificación por compás (11 patrones con código) |
| references/narration.md | ritmo de voz en off/TTS y estructura del guión |
| references/media.md | TTS (Kokoro), transcripción (Whisper), eliminación de fondo |
| references/prompt-expansion.md | Paso 2 del enfoque |
| references/design-picker.md | crear un design.md visualmente |
| references/from-website.md | convertir un sitio web en un video |
| references/registry.md | instalar/contribuir bloques del registro (hyperframes add) |
| visual-styles.md | el usuario nombra un estilo; generar design.md |
| house-style.md | valores predeterminados estéticos cuando no hay design.md |
| patterns.md | PiP, tarjetas de título, presentaciones de diapositivas |
| data-in-motion.md | datos, estadísticas, infografías |
Adaptadores de tiempo de ejecución (leer cuando la composición use ese tiempo de ejecución en lugar de GSAP): waapi, lottie, three, animejs, css-animations, typegpu.