Registro de HyperFrames
El registro proporciona bloques y componentes reutilizables instalables mediante hyperframes add <nombre>.
- Bloques — subcomposiciones independientes (dimensiones, duración, línea de tiempo propias). Se incluyen mediante
data-composition-srcen una composición anfitriona. - Componentes — fragmentos de efectos (sin dimensiones propias). Se pegan directamente en el HTML de la composición anfitriona.
Cuándo usar esta habilidad
- El usuario menciona
hyperframes add, "bloque", "componente" ohyperframes.json - Aparece la salida de
hyperframes adden la sesión (rutas de archivo, fragmento en el portapapeles) - Necesitas conectar un elemento instalado en una composición existente
- Deseas descubrir qué hay disponible en el registro
Referencia rápida
hyperframes add data-chart # instalar un bloque
hyperframes add grain-overlay # instalar un componente
hyperframes add shimmer-sweep --dir . # apuntar a un proyecto específico
hyperframes add data-chart --json # salida legible por máquina
hyperframes add data-chart --no-clipboard # omitir portapapeles (CI/headless)
Después de la instalación, la CLI imprime qué archivos se escribieron y un fragmento para pegar en tu composición anfitriona. El fragmento es un punto de partida: deberás añadir los atributos data-composition-id (debe coincidir con el ID interno del bloque), data-start y data-track-index al conectar bloques.
Nota: hyperframes add solo funciona para bloques y componentes. Para ejemplos, usa hyperframes init <dir> --example <nombre>.
Ubicaciones de instalación
Los bloques se instalan en compositions/<nombre>.html por defecto.
Los componentes se instalan en compositions/components/<nombre>.html por defecto.
Estas rutas son configurables en hyperframes.json:
{
"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
"paths": {
"blocks": "compositions",
"components": "compositions/components",
"assets": "assets"
}
}
Consulta install-locations.md para más detalles.
Conexión de bloques
Los bloques son composiciones independientes — inclúyelos mediante data-composition-src en tu index.html anfitrión:
<div
data-composition-id="data-chart"
data-composition-src="compositions/data-chart.html"
data-start="2"
data-duration="15"
data-track-index="1"
data-width="1920"
data-height="1080"
></div>
Atributos clave:
data-composition-src— ruta al archivo HTML del bloquedata-composition-id— debe coincidir con el ID interno del bloquedata-start— momento en que aparece el bloque en la línea de tiempo anfitriona (segundos)data-duration— duración de reproducción del bloquedata-width/data-height— dimensiones del lienzo del bloquedata-track-index— orden de capas (mayor = al frente)
Consulta wiring-blocks.md para más detalles.
Conexión de componentes
Los componentes son fragmentos — pega su HTML en el marcado de tu composición, su CSS en tu bloque de estilos y su JS en tu script (si lo hay):
- Lee el archivo instalado (ej.,
compositions/components/grain-overlay.html) - Copia los elementos HTML dentro del
<div data-composition-id="...">de tu composición - Copia el bloque
<style>en los estilos de tu composición - Copia cualquier contenido
<script>en el script de tu composición (antes del código de línea de tiempo) - Si el componente expone integración con la línea de tiempo de GSAP (consulta el bloque de comentarios en el fragmento), agrega esas llamadas a tu línea de tiempo
Consulta wiring-components.md para más detalles.
Descubrimiento
Navega por los elementos disponibles:
# Leer el manifiesto del registro
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
Cada registry-item.json de un elemento contiene: nombre, tipo, título, descripción, etiquetas, dimensiones (solo bloques), duración (solo bloques) y lista de archivos.
Consulta discovery.md para detalles sobre filtrado por tipo y etiquetas.