HyperFrames Core
HyperFrames renderiza video desde HTML. Una composición es un archivo HTML cuyo DOM declara la temporización con atributos data-*, cuyo tiempo de ejecución de animación es buscable (seekable) y cuya reproducción de medios es controlada por el framework.
Este skill es el contrato técnico — cómo construir un proyecto de hyperframes. El cuerpo a continuación es la guía de construcción; los detalles por tema están en references/ (índice a continuación), léelos bajo demanda. Otras preocupaciones viven en los skills de dominio hermanos — hyperframes-animation, hyperframes-creative, hyperframes-media, hyperframes-cli, hyperframes-registry. El mapa de capacidades en /hyperframes dice qué cubre cada uno.
Referencias
| Archivo | Léelo para… |
|---|---|
references/minimal-composition.md | empezar desde el esqueleto de composición renderizable más pequeño |
references/composition-patterns.md | elegir entre monolítico vs modular; estructurar un index.html modular; elegir un arquetipo de subcomp |
references/data-attributes.md | consultar cualquier atributo data-* (raíz / clip / host de subcomp / alias heredados); usar class="clip" |
references/tracks-and-clips.md | elegir data-track-index, manejar superposición/mismo-track z-index, temporizar un clip relativo a otro |
references/sub-compositions.md | conectar una subcomposición (atributos del host, <template>, variables por instancia) y animar dentro de ella |
references/variables-and-media.md | declarar variables; colocar <video>/<audio>, ajustar volumen, recortar |
references/determinism-rules.md | construir una línea de tiempo buscable; prohibiciones de determinismo; la lista blanca de propiedades animables; diseño / ajuste de texto |
references/full-screen-motion.md | crear animaciones a pantalla completa con fondos compartidos |
references/storyboard-format.md | redactar un plan STORYBOARD.md (+ el manifiesto analizado) |
references/script-format.md | redactar la narración fija opcional SCRIPT.md |
references/subagent-dispatch.md | mapear los verbos de despacho de subagentes (fan-out paralelo / fondo / espera) a tu harness |
references/tailwind.md | trabajar en un proyecto Tailwind v4 (init --tailwind; el contrato de tiempo de ejecución difiere del v3 de Studio) |
Para detalles específicos del tiempo de ejecución de animación (API de GSAP, Lottie, Three.js, etc.) ve a hyperframes-animation → adapters/<runtime>.md.
Construyendo una composición
Dos formas raíz (no intercambiables)
- Independiente (
index.htmlde nivel superior) — el<div data-composition-id="…">raíz se coloca directamente en<body>, sin envoltorio<template>(envolverlo oculta todo el contenido y rompe el renderizado). - Subcomposición (cargada mediante
data-composition-src) — la raíz debe estar envuelta en<template>.
⚠ Regla de transporte: el tiempo de ejecución solo clona los contenidos de
<template>; todo lo demás (incluyendo estilos/scripts de<head>) se descarta — coloca<style>/<script>dentro del template. ⚠ Regla de ID del host: eldata-composition-iddel slot del host debe ser exactamente igual aldata-composition-iddel template interno y a la clavewindow.__timelines["<id>"]— sin sufijo-mount/-slot/-host.
Forma del archivo, conexión del host y lista de verificación previa al renderizado → references/sub-compositions.md.
La raíz debe tener tamaño (error de diseño silencioso)
La raíz independiente necesita un contenedor con tamaño explícito (width/height en px), y cada ancestro hasta un elemento con height:100% debe tener una altura resuelta — de lo contrario, un hijo flex/100% colapsa a ~0 y el contenido se apila en la esquina superior izquierda. lint/validate/inspect no detectan esto. Esqueleto → references/minimal-composition.md.
Una línea de tiempo pausada
Cada composición registra exactamente una gsap.timeline({ paused: true }) en window.__timelines["<id>"] (clave = raíz data-composition-id), construida síncronamente al cargar la página. La duración del renderizado = raíz data-duration, no la longitud de la línea de tiempo. No anides manualmente sublíneas de tiempo en el host. Contrato completo (incluyendo tiempos de ejecución no GSAP) → references/determinism-rules.md + hyperframes-animation/adapters/.
Reglas no negociables (errores silenciosos que lint/validate/inspect no detectarán)
Expuestas aquí; justificación completa en la referencia enlazada. No violar:
- Sin relojes en tiempo de renderizado /
Math.randomsin semilla / red / estado de entrada; sinrepeat: -1(usar un contador finito). →determinism-rules.md - Animar solo la lista blanca de propiedades visuales; nunca
display/visibility; singsap.seten clips de escenas posteriores. →determinism-rules.md - Sin
<br>en el texto del cuerpo; los elementos transformados deben ser de nivel de bloque + tener tamaño; los decorativos absolutos pulsantes necesitan espacio libre máximo. →determinism-rules.md <video>/<audio>debe ser un hijo directo de la raíz del host (nunca dentro de un<template>/envoltorio de subcomp); el framework controla la reproducción. →variables-and-media.md- Cada
iddebe ser único en la página ensamblada; dentro de una subcomp, prefijar los IDs con el id de composición (#<id>-hero). Los IDs duplicados de<video>/<img>se renderizan en blanco — el productor inyecta fotogramas mediantegetElementById, y los duplicados entre archivos pasan desapercibidos paralint. →composition-patterns.md - Un relleno de escena a pantalla completa se coloca en un hijo a sangre completa (
position:absolute; inset:0), nunca en la propia raíz de la composición — la composición de fotogramas del productor puede eliminar elbackgrounddel propio elemento raíz (el fotograma se renderiza negro) aunque la vista previa/snapshotlo muestren correctamente. →composition-patterns.md
Editando composiciones existentes
- Lee los archivos primero. Preserva la temporización, pistas, IDs, variables, rutas de medios no relacionados.
- Coincide con los IDs de composición existentes y las claves de línea de tiempo.
- Para agregar un clip: elige un
data-track-indexque no se superponga o ajusta la temporización circundante intencionalmente. - Para agregar una subcomposición: verifica su
data-composition-idinterno antes de conectar el host.
Validación
Usa hyperframes-cli para detalles de comandos
-
npx hyperframes lintpasa (0 errores) -
npx hyperframes validatepasa (0 errores de consola) -
npx hyperframes inspectpasa (0 errores) - Proyectos con subcomposiciones:
npx hyperframes snapshot --at <midpoints>y revisa visualmente cada fotograma -
npx hyperframes previewpara revisión (el usuario puede editar cualquier cosa en la línea de tiempo de Studio) -
npx hyperframes rendersolo después de que el usuario lo apruebe