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 audiohyperframes-media— TTS, transcripción con Whisper, eliminación de fondo, subtítuloshyperframes-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ínima | references/minimal-composition.md |
| Decidir entre arquitectura monolítica de archivo único o modular con subcomp | references/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" correctamente | references/data-attributes.md |
Elegir un data-track-index; superposición en misma pista; track-index vs CSS z-index | references/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-start | references/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 compartidos | references/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.htmlde 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-iden el slot debe ser exactamente igual aldata-composition-idde la plantilla interna y a la clavewindow.__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 eldata-composition-idde 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,Promiseo 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-durationen 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.)
- No usar
Math.random()/Date.now()/performance.now()para controlar elementos visuales — usa un PRNG con semilla. - No usar
repeat: -1. Usarepeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)—floor, noceil(ceilsobrepasadata-durationy activa el lintgsap_repeat_ceil_overshoot;max(0, …)evita un repeat negativo = infinito). <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 usarvideo.play()/audio.play()/currentTime = …. Una subcomp no puede controlar elementos del host (selector oquerySelector), así que anima el multimedia del host desde la línea de tiempo principal a tiempo global. Consultareferences/variables-and-media.md.- No usar
gsap.set()en elementos de clip de escenas posteriores (aún no están en el DOM). Usatl.set(selector, vars, time)en o después deldata-startdel clip. - No animar
display/visibility. Animaopacity/ transformaciones; el ciclo de vida del clip maneja mostrar/ocultar. - No usar
<br>en el cuerpo del texto. Deja que el texto se ajuste mediantemax-width. - Los elementos transformados deben ser de nivel de bloque + tener tamaño.
transform/scaleX/scaleYes inoperante en un<span>inline, y escalar un elemento con ancho automático (0px) no muestra nada → barras/rellenos invisibles. Dalesdisplay: block/inline-block/flex-item y unwidth/heightreal (por ejemplo,width: 100%dentro de un padre con tamaño). - 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 bordeoverflow: 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-indexque no se superponga o ajusta intencionadamente la temporización circundante. - Al agregar una subcomposición, verifica su
data-composition-idinterno antes de conectar el host.
Validación
Usa hyperframes-cli para los detalles de los comandos.
-
npx hyperframes lintpasa (0 errores) -
npx hyperframes validatepasa (0 errores de consola) -
npx hyperframes inspectpasa, o el desbordamiento está marcado intencionadamente - Proyectos con subcomposiciones:
npx hyperframes snapshot --at <midpoints>y revisa visualmente cada fotograma