Registro HyperFrames
El registro proporciona bloques y componentes reutilizables que se instalan mediante hyperframes add <nombre>.
- Bloques — subcomposiciones independientes (con sus propias dimensiones, duración y línea de tiempo). Se incluyen mediante
data-composition-srcen una composición anfitriona. - Componentes — fragmentos de efectos (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, el 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 de composición interno del bloque), data-start y data-track-index al conectar bloques.
El valor posicional se resuelve primero como un nombre exacto de elemento. Si no coincide ningún elemento 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> en su lugar.
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 obtener todos los 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— cuándo 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 obtener todos los 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 (por ejemplo,
compositions/components/grain-overlay.html) - Copia los elementos HTML dentro de tu
<div data-composition-id="..."> - 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 la 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 obtener todos los detalles.
Descubrimiento
Usa el CLI como superficie principal de descubrimiento. Busca por intención antes de navegar: el registro contiene más elementos de los que puedes escanear visualmente, por lo que listarlos y buscar coincidencias por nombres o etiquetas es el camino lento, y falla cada vez que la redacción del autor difiere de la tuya.
# Clasificar todo el catálogo según lo que el beat debería hacer
npx hyperframes catalog --query "revelar un titular línea por línea"
npx hyperframes add caption-clip-wipe
La búsqueda es local y no envía nada. Por defecto, clasifica según el vocabulario compartido con el nombre, título y descripción del elemento, por lo que solo encuentra elementos que reutilizan tus palabras; --on-device clasifica por significado, después de una descarga única del modelo. Con --json, el sobre indica qué nivel respondió, así que verifica eso en lugar de asumir que ocurrió una clasificación.
La instalabilidad se aplica después de la clasificación, no antes: un nombre que los vectores transportan pero que este registro no puede servir se elimina de los resultados y se cuenta en dropped, por lo que un dropped distinto de cero significa que son dos generaciones diferentes. Consulta /hyperframes-cli para el nivel fuera de línea, las puertas de consentimiento y cómo actualizar un índice obsoleto.
Para navegar o filtrar en lugar de buscar:
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 de tabla normal 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 trabajo CI o de agentes, prefiere --json seguido de un add explícito.
Si el 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
El registry-item.json de cada elemento contiene: nombre, tipo, título, descripción, etiquetas, dimensiones (solo bloques), duración (solo bloques) y lista de archivos.
Consulta discovery.md para obtener detalles sobre el 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 PR ascendente — no instalar uno existente — sigue el flujo de trabajo completo de idea → scaffolding → construcción → validación → vista previa → envío en contributing.md. Las plantillas de inicio para copiar y pegar (subtítulos / VFX / componente / registry-item.json) están en templates.md.