hyperframes-core

HyperFrames Core

HyperFrames renderiza video desde HTML. Una composición es un archivo HTML cuyo DOM declara temporización con atributos data-*, cuyo tiempo de ejecución de animación es buscable y cuya reproducción de medios es controlada por el framework.

Esta skill es el contrato técnico: cómo construir un proyecto hyperframes. El cuerpo siguiente es la guía de construcción; los detalles por tema residen en references/ (índice a continuación), léelos bajo demanda. Otras preocupaciones viven en skills de dominio relacionadas: hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. El mapa de capacidades en /hyperframes indica qué cubre cada una.

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; seleccionar un arquetipo de sub-comp
references/data-attributes.md	consultar cualquier data-* (raíz / clip / host de sub-comp / alias heredados); usar class="clip"
references/tracks-and-clips.md	elegir data-track-index, manejar solapamiento / z-index en la misma pista, temporizar un clip relativo a otro
references/creator-editing-recipes.md	copiar recetas verdaderas de corte/recorte/reordenación/recronometraje/congelación/cámara/máscara/encadenado/edición de audio y sus límites
references/sub-compositions.md	conectar una sub-composició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; 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	redactar un plan STORYBOARD.md (+ el manifiesto analizado)
references/review-loop.md	ejecutar las pasadas de revisión plan → boceto → construcción en un tablero en vivo — compartido por todo flujo de planificación de guion gráfico
references/production-loop.md	llevar un plan aprobado a un video entregado — las dependencias de etapa (audio, fotogramas, ensamblaje, transiciones, subtítulos, verificación, entrega) que un montaje 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í reside en /hyperframes → la capa de intención)
references/brief-format.md	redactar BRIEF.md — el documento de intención confirmado que el Setup de un flujo de trabajo escribe y que todo paso posterior lee
references/script-format.md	redactar el SCRIPT.md opcional de narración fija
references/subagent-dispatch.md	mapear verbos de envío de subagentes (ramificación paralela / fondo / espera) a tu sistema
references/frame-worker-core.md	el contrato compartido del rol frame-worker — cada constructor de paquete de flujo narrativo lo antepone al delta de sub-agents/frame-worker.md de ese flujo
references/tailwind.md	trabajar en un proyecto Tailwind v4 (init --tailwind; el contrato en 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.

Construir una composición

Dos formas raíz (no intercambiables)

• Independiente (index.html de 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).
• Sub-composición (cargada via data-composition-src) — la raíz debe estar envuelta en <template>.

⚠ Regla de transporte: el runtime solo clona el contenido de <template>; todo lo externo (incluyendo estilos/scripts de <head>) se descarta — coloca <style>/<script> dentro de la plantilla. ⚠ Regla de ID de host: el data-composition-id del espacio del host debe coincidir exactamente con el data-composition-id de la plantilla interna y con la clave window.__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 cuadro 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 acumula en la esquina superior izquierda. No confíes solo en compuertas automatizadas para detectar esto; inspecciona una captura. Esqueleto → references/minimal-composition.md.

Una línea de tiempo en pausa

Cada composición registra exactamente una gsap.timeline({ paused: true }) en window.__timelines["<id>"] (clave = data-composition-id raíz), construida sincrónicamente al cargar la página. La duración del renderizado = data-duration raíz, no la longitud de la línea de tiempo. No anides manualmente sub-líneas de tiempo en el host. Contrato completo (incluyendo runtimes no GSAP) → references/determinism-rules.md + hyperframes-animation/adapters/.

Errores comunes del primer lint (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 con data-composition-id/data-width/data-height); omitirlo hace que lint falle con root_composition_missing_data_start.
• Nunca combines un transform CSS inicial con un tween de GSAP en la misma propiedad — el valor CSS y el inicio del tween entran en conflicto y lint lo rechaza con gsap_css_transform_conflict. Establece el estado inicial dentro del tween con gsap.fromTo(el, { x: -40 }, { x: 0 }) en lugar de un CSS transform: translateX(-40px).

Reglas no negociables (errores silenciosos que las compuertas automatizadas pueden pasar por alto)

Expuestas aquí; justificación completa en la referencia vinculada. No las violes:

• Sin relojes en tiempo de renderizado / Math.random sin semilla / red / estado de entrada; sin repeat: -1 (usa un conteo finito). → determinism-rules.md
• Anima solo la lista blanca de propiedades visuales; nunca apliques tween a display o visibility cruda. Las únicas excepciones de visibilidad son autoAlpha de GSAP y los límites de línea de tiempo de duración cero, y solo en elementos que no son clips o envoltorios dentro de un clip. El framework solo controla la visibilidad de .clip. No apliques gsap.set a 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 decorativos absolutos pulsantes necesitan espacio libre máximo. → determinism-rules.md
• <video>/<audio> funcionan a cualquier profundidad de anidamiento (incluyendo dentro de un <template> o envoltorio de sub-comp); el framework controla la reproducción y busca/decodifica medios donde sea que estén. La única advertencia son las líneas de tiempo, no la ubicación: una línea de tiempo de sub-comp no puede animar elementos raíz del host. → variables-and-media.md
• Cada id debe ser único en la página ensamblada; dentro de una sub-comp, prefija los ids con el id de la composición (#<id>-hero). Los ids duplicados de <video>/<img> se renderizan en blanco — el productor inyecta fotogramas mediante getElementById, y los duplicados entre archivos pasan desapercibidos para lint. → composition-patterns.md
• El relleno de una escena a pantalla completa va en un hijo que ocupe todo el espacio (position:absolute; inset:0), nunca en la raíz de la composición — la composición de fotogramas del productor puede eliminar el background del propio elemento raíz (el fotograma se renderiza negro) aunque la vista previa/snapshot lo muestren correctamente. → composition-patterns.md

Editar composiciones existentes

• Lee los archivos primero. Preserva la temporización, pistas, IDs, variables y rutas de medios no relacionadas.
• Coincide con los IDs de composición y claves de línea de tiempo existentes.
• Agregar un clip: elige un data-track-index que no se superponga o ajusta la temporización circundante intencionalmente.
• data-hidden en cualquier elemento de 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.
• Agregar una sub-composición: verifica su data-composition-id interno antes de conectar el host.

Validación

Usa hyperframes-cli para detalles de comandos

• npx hyperframes check pasa (0 hallazgos en lint, tiempo de ejecución, diseño, movimiento y contraste)
• Proyectos con sub-composiciones: npx hyperframes snapshot --at <puntos medios> y revisa visualmente cada fotograma
• npx hyperframes preview --background para revisión (el usuario puede editar cualquier cosa en la línea de tiempo de Studio, y el servidor sobrevive al comando invocador)
• npx hyperframes render solo después de que el usuario lo apruebe