Contribuir al Registro de HyperFrames
Guía al usuario desde la idea hasta una PR fusionada para un nuevo bloque o componente del registro.
Flujo de trabajo
1. Clarificar → 2. Andamiar → 3. Construir → 4. Validar → 5. Previsualizar → 6. Enviar
Paso 1: Clarificar
Pregunta qué están construyendo. El registro tiene dos tipos de elementos:
- Bloque (
registry/blocks/, tipohyperframes:block) — una composición independiente completa con dimensiones y duración fijas. Estilos de subtítulos, efectos VFX, tarjetas de título, tercios inferiores. - Componente (
registry/components/, tipohyperframes:component) — un fragmento reutilizable sin dimensiones ni duración fijas. Efectos CSS, tratamientos de texto, superposiciones que se adaptan a cualquier tamaño de composición.
Luego pregunta:
- Descripción de una frase del efecto
- Referencia visual (URL, captura de pantalla o descripción)
- ¿Quién usa esto y cuándo?
Paso 2: Andamiar
Crea la estructura del registro:
Para bloques:
registry/blocks/{nombre-del-bloque}/
{nombre-del-bloque}.html
registry-item.json
Para componentes:
registry/components/{nombre-del-componente}/
{nombre-del-componente}.html
registry-item.json
Convención de nomenclatura:
| Nombre del elemento | Prefijo ID | Ejemplos de IDs |
|---|---|---|
cap-hormozi | hz | hz-cg-0, hz-cw-3 |
cap-typewriter | tw | tw-cg-0, tw-ch-0-5 |
vfx-chrome | vc | vc-canvas |
Usa un prefijo de 2-3 letras. TODOS los IDs de elementos deben usar este prefijo para evitar colisiones en sub-composiciones.
registry-item.json para bloques:
{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "{nombre-del-bloque}",
"type": "hyperframes:block",
"title": "{Título Humano}",
"description": "{una frase}",
"dimensions": { "width": 1920, "height": 1080 }, // ajustar: 1080x1920 para vertical/redes sociales
"duration": 10, // ajustar para tu composición
"tags": ["{categoría}", "{subcategoría}"],
"files": [
{
"path": "{nombre-del-bloque}.html",
"target": "compositions/{nombre-del-bloque}.html",
"type": "hyperframes:composition"
}
]
}
registry-item.json para componentes (sin dimensions ni duration):
{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "{nombre-del-componente}",
"type": "hyperframes:component",
"title": "{Título Humano}",
"description": "{una frase}",
"tags": ["{categoría}"],
"files": [
{
"path": "{nombre-del-componente}.html",
"target": "compositions/components/{nombre-del-componente}.html",
"type": "hyperframes:snippet"
}
]
}
Paso 3: Construir
Aplica la plantilla correcta según el tipo. Consulta templates.md para iniciadores de copiar y pegar.
Bloques de subtítulos
Reglas de subtítulos no negociables:
- Fuente: Mínimo 96px para fuentes proporcionales. 64-72px aceptable para monoespaciadas (los caracteres más anchos necesitan menos tamaño).
- Legibilidad:
-webkit-text-stroke: 2-3pxOtext-shadowmulticapa - Desbordamiento: llama a
window.__hyperframes.fitTextFontSize()en cada grupo - Karaoke: resalta la palabra activa mediante
tl.to(wordEl, { color/scale }, WORDS[wi].start) - Corte brusco:
tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end)en CADA grupo - Nunca uses
tl.from(el, { opacity: 0 })en la misma posición quetl.set(el, { opacity: 1 })— elfromsobrescribe elset. Usatl.toen su lugar.
Animación por carácter (máquina de escribir, desorden):
- Envuelve cada carácter en
<span>con el ID{prefijo}-ch-{grupo}-{caracter} - Escalonado mediante
tl.seten intervalos calculados a partir de las marcas de tiempo de las palabras - Cursores/elementos decorativos: usa
tl.seten intervalos — NO animación CSS (no es buscable)
Variantes de posicionamiento:
- Centrado:
display: flex; align-items: center; justify-content: center; - Tercio inferior:
position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center; - Alineado a la izquierda:
position: absolute; bottom: 100px; left: 120px; text-align: left;
Bloques VFX (Three.js)
- Usa
[email protected]desde CDN (script global) tl.eventCallback("onUpdate", renderScene); renderScene();— NO requestAnimationFrame- Patrón proxy de estado: GSAP anima un objeto JS plano, la función de render lo lee
- PRNG con semilla (
mulberry32) para aleatoriedad
Todos los tipos
data-composition-idDEBE coincidir conwindow.__timelines["id"]- Todos los IDs de elementos prefijados con la abreviatura del bloque
gsap.timeline({ paused: true })— siempre en pausa- No
Math.random(), noDate.now()
Paso 4: Validar
hyperframes lint # 0 errores requeridos
hyperframes validate --no-contrast # 0 errores de consola requeridos
Paso 5: Previsualizar
# Renderizar video de vista previa
hyperframes render -o preview.mp4
# Captura instantánea para revisión visual
hyperframes snapshot --at "1.0,3.0,5.0,7.0"
# Publicar en hyperframes.dev para revisión
npx hyperframes publish
Imagen de vista previa del catálogo — La tarjeta del catálogo usa un PNG en docs/images/catalog/{tipo}/{nombre}.png (donde {tipo} es blocks o components). Genérala a partir de una captura instantánea, luego:
- Contribuidores internos de HeyGen: ejecuten
scripts/upload-docs-images.sh(requiere el perfil de AWSengineering-767398024897) - Contribuidores externos: adjunten el MP4 de vista previa a la descripción de su PR. Un mantenedor generará y subirá la imagen del catálogo antes de fusionar.
Paso 6: Enviar
Todos los pasos son requeridos. Si falta alguno, se produce una entrada de catálogo rota.
{tipo} es blocks o components dependiendo de lo que construiste en el Paso 1.
# 1. Crear rama
git checkout -b feat/registry-{nombre}
# 2. Formatear HTML
npx oxfmt registry/{tipo}/{nombre}/*.html
# 3. Actualizar registry/registry.json — agregar entrada al array "items":
# { "name": "{nombre}", "type": "hyperframes:block" } (o "hyperframes:component")
# 4. Generar página de documentación del catálogo
npx tsx scripts/generate-catalog-pages.ts
# 5. Publicar en hyperframes.dev para que los revisores puedan previsualizar
npx hyperframes publish
# 6. Agregar todo al área de preparación
git add registry/{tipo}/{nombre}/ registry/registry.json docs/catalog/
# 7. Hacer commit
git commit -m "feat(registry): agrega {nombre} — {una frase}"
# 8. Subir y abrir PR con enlace a hyperframes.dev
git push origin feat/registry-{nombre}
gh pr create --title "feat(registry): {nombre}" --body "preview: {url-de-hyperframes-dev}"
Si no tienes una cuenta de GitHub: necesitas una para abrir una PR. Regístrate en https://github.com/signup, luego ejecuta gh auth login.
Puerta de calidad
-
hyperframes lint→ 0 errores -
hyperframes validate→ 0 errores de consola -
npx oxfmt --checkpasa -
registry/registry.jsonactualizado con nueva entrada -
scripts/generate-catalog-pages.tsejecutado (página de documentación generada) -
npx hyperframes publishejecutado (reclama tu URL del proyecto) - MP4 de vista previa adjunto a la PR (externo) o PNG del catálogo subido (interno)
- Todos los IDs únicos y prefijados