HyperFrames Core
HyperFrames renderiza video a partir de HTML. Una composición es un archivo HTML cuyo DOM declara el tiempo con atributos data-*, cuyo runtime de animación es buscable y cuya reproducción de medios es gestionada 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 se encuentran en references/ (índice a continuación), léelos bajo demanda. Otras preocupaciones se encuentran en los skills de dominio hermanos — hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. El mapa de capacidades en /hyperframes indica lo que 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 monolítico vs modular; estructurar un index.html modular; elegir un arquetipo de subcomposición |
references/data-attributes.md | consultar cualquier data-* (raíz / clip / host de subcomp / alias heredados); usar class="clip" |
references/tracks-and-clips.md | elegir data-track-index, manejar superposición / z-index en la misma pista, 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>, establecer volumen, recortar |
references/determinism-rules.md | construir una línea de tiempo buscable; prohibiciones de determinismo; lista blanca de propiedades animables; ajuste de diseño / texto |
references/full-screen-motion.md | crear movimiento a pantalla completa con fondos compartidos |
references/storyboard-format.md | escribir un plan STORYBOARD.md (+ el manifiesto analizado) |
references/review-loop.md | ejecutar los pases de revisión plan → boceto → construcción en un tablero en vivo — compartido por cada flujo de trabajo de planificación de storyboard |
references/production-loop.md | llevar un plan aprobado a un video entregado — las dependencias de etapa (audio, fotogramas, montaje, transiciones, subtítulos, verificar, entregar) una compilación libre sigue directamente |
references/brief-contract.md | las reglas básicas del brief — derivación de modo (colaborativo / autónomo), registro de campos compartidos, invariantes de preguntas (la pregunta en sí vive en /hyperframes → la capa de intención) |
references/brief-format.md | escribir BRIEF.md — el documento de intención confirmada que el Setup de un flujo de trabajo escribe y cada paso posterior lee |
references/script-format.md | escribir el opcional SCRIPT.md de narración bloqueada |
references/subagent-dispatch.md | mapear verbos de despacho de subagentes (fan-out paralelo / fondo / espera) a tu entorno |
references/frame-worker-core.md | el contrato compartido del rol de frame-worker — cada generador de paquetes de flujo de trabajo narrativo lo antepone al delta de sub-agents/frame-worker.md de ese flujo de trabajo |
references/tailwind.md | trabajar en un proyecto con Tailwind v4 (init --tailwind; el contrato en tiempo de ejecución difiere del v3 de Studio) |
Para detalles específicos del runtime de animación (API de GSAP, Lottie, Three.js, etc.) ve a hyperframes-animation → adapters/<runtime>.md.
Construir una composición
Dos formas raíz (no intercambiables)
- Independiente (
index.htmlde nivel superior) — un<div data-composition-id="…">raíz va 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 runtime solo clona el contenido 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 layout silencioso)
La raíz independiente necesita una caja 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/con 100% se colapsa a ~0 y el contenido se apila en la esquina superior izquierda. No confíes solo en las compuertas automatizadas para detectar esto; inspecciona una captura. 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 = data-composition-id de la raíz), construida sincrónicamente al cargar la página. La duración del renderizado = data-duration de la raíz, no la longitud de la línea de tiempo. No anides manualmente sublíneas de tiempo en el host. Contrato completo (incl. runtimes no GSAP) → references/determinism-rules.md + hyperframes-animation/adapters/.
Errores comunes del lint en la primera pasada (un fallo garantizado en la primera compilación)
Dos reglas que lint sí detecta, pero solo después del hecho — escríbelas correctamente la primera vez:
- El elemento raíz de la composición debe llevar
data-start="0"(junto condata-composition-id/data-width/data-height); omitirlo hace quelintfalle conroot_composition_missing_data_start. - Nunca combines un
transformCSS inicial con un tween de GSAP en la misma propiedad — el valor CSS y el inicio del tween entran en conflicto ylintlo rechaza congsap_css_transform_conflict. Establece el estado inicial dentro del tween congsap.fromTo(el, { x: -40 }, { x: 0 })en lugar de untransform: translateX(-40px)CSS.
Reglas no negociables (errores silenciosos que las compuertas automatizadas pueden pasar por alto)
Se exponen aquí; la justificación completa en la referencia vinculada. No las violes:
- Sin relojes en tiempo de renderizado /
Math.randomsin semilla / red / estado de entrada; sinrepeat: -1(usa un conteo finito). →determinism-rules.md - Anima solo la lista blanca de propiedades visuales; nunca apliques un tween a
displayovisibilitysin procesar.autoAlphade GSAP y los límites de línea de tiempo de duración cero son las únicas excepciones de visibilidad, y solo en elementos que no sean clips o envoltorios dentro de un clip. El framework solo controla la visibilidad de.clip. No usesgsap.seten clips de escenas posteriores al cargar la página. →determinism-rules.md - Sin
<br>en el texto del cuerpo; los elementos transformados deben ser de nivel de bloque + con tamaño; los elementos decorativos absolutos pulsantes necesitan espacio libre máximo. →determinism-rules.md <video>/<audio>funcionan a cualquier profundidad de anidamiento (incluso dentro de un<template>o envoltorio de subcomp); el framework posee la reproducción y busca/decodifica los medios donde sea que estén. La única salvedad son las líneas de tiempo, no la colocación: la línea de tiempo de una subcomp no puede animar elementos raíz del host. →variables-and-media.md- Cada
iddebe ser único en toda la página ensamblada; dentro de una subcomp, prefija los ids con el id de la composición (#<id>-hero). Losidduplicados 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 va en un hijo con sangría completa (
position:absolute; inset:0), nunca en la raíz de la composición misma — la composición de fotogramas del productor puede descartar elbackgroundpropio del elemento raíz (el fotograma se renderiza negro) aunque la vista previa/snapshotlo muestren correctamente. →composition-patterns.md
Editar composiciones existentes
- Lee los archivos primero. Preserva el tiempo, las pistas, los IDs, las variables y las rutas de medios no relacionados.
- Coincide con los IDs de composición y las claves de línea de tiempo existentes.
- Al agregar un clip: elige un
data-track-indexque no se superponga o ajusta el tiempo circundante intencionalmente. data-hiddenen cualquier elemento de la composición lo oculta TANTO en la vista previa como en el renderizado, anulando su ventana de tiempo; no es destructivo / reversible y se alterna con el icono de ojo de la línea de tiempo de Studio.- Al agregar una subcomposición: verifica su
data-composition-idinterno antes de conectar el host.
Validación
Usa hyperframes-cli para obtener detalles de comandos
-
npx hyperframes checkpasa (0 hallazgos en lint, runtime, layout, movimiento y contraste) - Proyectos con subcomposiciones:
npx hyperframes snapshot --at <puntos medios>y examina 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