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 efecto (sin dimensiones propias). Se pegan directamente en el HTML de una composición anfitriona.
Referencia rápida
hyperframes add data-chart # instalar un bloque
hyperframes add grain-overlay # instalar un componente
hyperframes add captions # instalar todos los bloques etiquetados como captions
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 fueron escritos y un fragmento para pegar en tu composición anfitriona. El fragmento es un punto de partida: deberás agregar los atributos data-composition-id (debe coincidir con el ID de composición interno del bloque), data-start y data-track-index al conectar bloques.
El valor posicional se resuelve primero como un nombre de elemento exacto. Si ningún elemento coincide y el valor es una etiqueta, el comando instala todos los bloques con esa etiqueta. Las dependencias del registro se instalan antes del elemento solicitado. hyperframes add funciona solo 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 el bloque aparece en la línea de tiempo anfitriona (segundos)data-duration— duració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 estilo y su JS en tu script (si lo hay):
- Lee el archivo instalado (ej.,
compositions/components/grain-overlay.html) - Copia los elementos HTML dentro de
<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 tu línea de tiempo) - Si el componente expone integración con la línea de tiempo de GSAP (ver 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
Usa la CLI como superficie de descubrimiento principal:
npx hyperframes catalog
npx hyperframes catalog --type block
npx hyperframes catalog --type component
npx hyperframes catalog --type block --tag social
npx hyperframes catalog --json
npx hyperframes catalog --human-friendly
El modo normal de tabla y --json solo listan coincidencias; instala un nombre seleccionado con hyperframes add <nombre>. --human-friendly abre un selector interactivo e instala el elemento seleccionado inmediatamente. En flujos de CI o agentes, prefiere --json seguido de un add explícito.
Si la CLI no puede alcanzar el registro configurado, inspecciona el manifiesto sin procesar como alternativa:
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
Cada registry-item.json de 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.
Contribuir con un nuevo bloque o componente
Para crear un NUEVO elemento del registro (estilo de subtítulos, bloque VFX, transición, tercio inferior o un componente reutilizable) y enviarlo como un PR ascendente — no instalar uno existente — sigue el flujo de trabajo completo de idea → andamiaje → construir → validar → previsualizar → enviar en contributing.md. Las plantillas de inicio para copiar y pegar (subtítulos / VFX / componente / registry-item.json) están en templates.md.