heygen-com/hyperframes

Instalación de plugins: Antes de ejecutar comandos de configuración o actualización, sigue las reglas de ejecución de plugins cuando este skill esté dentro de un plugin de HyperFrames. Las instalaciones independientes deben seguir las instrucciones de actualización que aparecen a continuación.

Núcleo de HyperFrames

Errores comunes del agente (léelos primero):

• Centra con flex/inset, no con transform: translate(-50%,-50%) de CSS en un nodo al que luego apliques GSAP x/y. Lint: gsap_css_transform_conflict. Usa fromTo o xPercent/yPercent.
• No añadas un tl.set(..., {visibility:"hidden"}) de salida de escena. El runtime ya oculta los clips temporizados. Los fundidos de opacidad en nodos internos (o opacity en .clip) son suficientes. Los cortes bruscos de subtítulos siguen una regla diferente.
• window.__timelines["id"] debe coincidir con el data-composition-id raíz.
• Después de render, lee la segunda línea del resumen: beginframe vs screenshot, modo GPU, tiempos de escenario. screenshot + software gpu en Linux es la ruta lenta.

HyperFrames renderiza video a partir de HTML. Una composición es un archivo HTML cuyo DOM declara la temporización mediante atributos data-*, cuyo runtime de animación es desplazable (seekable) 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 siguiente es la guía de construcción; los detalles por tema viven en references/ (índice a continuación), léelos según sea necesario. Los documentos de proceso (brief, storyboard, revisión, producción, despacho, frame-worker) están en /hyperframes → references/. Otros aspectos viven 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; seleccionar un arquetipo de subcomp
references/data-attributes.md	buscar cualquier data-* (raíz / clip / host de subcomp / alias heredados); usar class="clip"
references/tracks-and-clips.md	entender qué controla (y qué no) data-track-index, índice z, temporizar un clip respecto a otro; listar cada pista y clip con npx hyperframes timeline
references/creator-editing-recipes.md	copiar recetas de edición fiables (cortar/recortar/reordenar/re-temporizar/congelar/cámara/máscara/encadenado/audio) y sus límites
references/sub-compositions.md	cablear una subcomposición (atributos 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 desplazable; prohibiciones de determinismo; ajuste de diseño / texto
references/full-screen-motion.md	crear movimiento a pantalla completa con fondos compartidos
references/tailwind.md	trabajar en un proyecto Tailwind v4 (init --tailwind; el contrato de runtime 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.

Construcción de 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>. Envolver una raíz independiente oculta todo el contenido y lint lo rechaza (standalone_composition_wrapped_in_template, error).
• Subcomposición (cargada mediante data-composition-src): envuelve la raíz en <template>. Esta es la forma recomendada: el cargador también acepta un documento completo y utiliza su <body> como fallback, pero la forma con template es la que asumen los ejemplos y las herramientas.

⚠ Regla de transporte: para una subcomposición con template, el ensamblador descarta el <head> <style>/<script> del archivo (packages/core/src/compiler/compositionAssembly.ts, la puerta hasTemplate), así que coloca <style>/<script> dentro del template. <link> se eleva en cualquier caso. ⚠ Convención de ID del host: asigna el mismo ID al slot del host, al template interno y a la clave window.__timelines["<id>"]. Se admite un ID local diferente (el ensamblador usa como fallback la primera raíz del archivo), pero la discrepancia es silenciosa, así que hazlos coincidir a menos que tengas un motivo para no hacerlo.

Forma del archivo, cableado del host y lista de verificación previa al renderizado → references/sub-compositions.md.

La raíz debe tener tamaño definido (error de maquetación silencioso)

La raíz independiente debe tener width/height: 100%. El tamaño del lienzo se define con data-width/data-height. El runtime asigna esos píxeles a la raíz de la composición. No uses valores fijos 1920px/1080px en #root. 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 raíz). Se admite construirla dentro de un callback asíncrono (document.fonts.ready); lo importante es que registres solo después de que la construcción haya finalizado. La duración del renderizado es la del data-duration raíz, no la duración de la línea de tiempo: una línea de tiempo que se extiende más allá se corta, y una que termina antes mantiene su último fotograma. Si omites el data-duration raíz, la duración se infiere (línea de tiempo, ventana de medios o adaptador). No necesitas window.__timelines = window.__timelines || {}: el runtime crea el registro antes de que se ejecuten tus scripts en línea, y lint ya no lo exige. No anides manualmente sublíneas de tiempo en el host; el runtime anida automáticamente las líneas de tiempo hijas registradas. Contrato completo (incluyendo runtimes que no son GSAP) → references/determinism-rules.md + hyperframes-animation/adapters/.

Errores comunes de lint de primera pasada (garantizan un fallo en la primera construcción)

Reglas que lint sí detecta, pero solo después del hecho. Escríbelas correctamente la primera vez:

• 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).
• Nunca coloques crossorigin en <video>/<audio>. lint lo rechaza incondicionalmente con media_crossorigin_breaks_preview (error), incluso para lectura de canvas/WebGL/WebAudio. No hay forma de suprimirlo.
• Nunca des a un <video data-start> un ancestro que también tenga data-start. lint lo rechaza con video_nested_in_timed_element (error). Temporiza el contenedor o el video, no ambos.
• Cada <audio> necesita un id. lint lo rechaza con media_missing_id, y un <audio> sin ID nunca es recogido por el mezclador, por lo que el renderizado será silencioso.
• Nunca apliques un tween a un .clip con autoAlpha o visibility: lint lo rechaza con gsap_animates_clip_element. Anima un elemento hijo en su lugar.
• Una font-family CSS con nombre necesita un @font-face en el archivo que apunte a un archivo local distribuido, o lint dispara font_family_without_font_face.
• El #root de una subcomposición usa width/height: 100% (o inset: 0), no valores fijos 1920px/1080px. El tamaño del lienzo es data-width/data-height.

Un error de lint también desactiva las auditorías de diseño y contraste: check entonces reporta 0 sample(s) y 0/0 text checks, lo que parece un archivo limpio pero significa que no se ejecutó nada. Corrige los errores de lint antes de confiar en esos números.

Reglas no negociables (bugs silenciosos que las compuertas automáticas pueden pasar por alto)

Se muestran aquí; la justificación completa está 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 recuento finito). → determinism-rules.md
• Nunca apliques tween a display, visibility o autoAlpha en un elemento .clip. El framework gestiona la visibilidad del clip, y lint lo rechaza (gsap_animates_clip_element). Anima un elemento hijo. → determinism-rules.md
• Sin <br> en el texto del cuerpo; los elementos transformados deben ser de nivel de bloque y tener tamaño definido; los elementos decorativos absolutos pulsantes necesitan espacio libre suficiente. → determinism-rules.md
• Los <video>/<audio> se encuentran mediante una consulta plana del documento, por lo que el framework los busca y decodifica a cualquier profundidad de anidamiento (incluso dentro de un <template> de subcomp o contenedor). Un límite estricto: lint da error si un <video data-start> está dentro de otro elemento simple que también tenga data-start, y el fallo es real (fotogramas de origen incorrectos, luego el clip desaparece a mitad del slot), así que coloca la temporización en el contenedor o en el video, nunca en ambos. Los hosts de subcomposición están exentos: los medios dentro de una subcomposición se renderizan correctamente. La otra advertencia son las líneas de tiempo, no la colocación: una línea de tiempo de subcomp no puede animar elementos raíz del host. → variables-and-media.md
• Mantén cada id único en toda la página ensamblada (prefija los IDs de las subcomposiciones con el ID de composición, #<id>-hero) para que tu propio CSS con #id y las llamadas getElementById funcionen. La inyección de fotogramas ya no depende de esto: el compilador estampa un data-hf-render-id único del documento en cada video[src]/audio[src]/img[src]. Los medios que usan hijos <source> en lugar de un atributo src no reciben esta estampa, por lo que los IDs únicos siguen siendo importantes allí. → composition-patterns.md
• Un relleno a pantalla completa en la raíz de la composición raíz está bien en un renderizado normal. Solo se descarta en la ruta de composite por capas (contenido HDR o una composición que use transiciones de shader), donde el motor fuerza que todas las raíces de composición sean transparentes para que la capa inferior se vea a través. Si tu composición usa transiciones de shader o medios HDR, coloca el relleno en un hijo a sangre completa (position:absolute; inset:0). → composition-patterns.md

Edición de composiciones existentes

• Lee primero los archivos. Conserva la temporización, pistas, IDs, variables y rutas de medios no relacionados.
• Para saber qué hay en la línea de tiempo de un proyecto (pistas, clips, inicios, fines, qué se reproduce), ejecuta npx hyperframes timeline [--json] en lugar de leer index.html y todos los archivos de subcomposición.
• Coincide con los IDs de composición y las claves de línea de tiempo existentes.
• Al añadir un clip: establece su data-start/data-duration de forma intencionada respecto a los clips circundantes. data-track-index es un carril de visualización de Studio, no una restricción de temporización, por lo que no necesita estar libre.
• Un clip que termina después del data-duration raíz se corta: extiende el data-duration raíz hasta el final del clip en la misma edición (lint advierte clip_ends_past_root_duration).
• data-hidden en cualquier elemento de composición lo oculta TANTO en la vista previa como en el renderizado, anulando su ventana de tiempo; es no destructivo/reversible y se alterna con el icono de ojo de la línea de tiempo de Studio.
• Al añadir una subcomposición: verifica su data-composition-id interno antes de cablear el host.

Validación

Usa hyperframes-cli para los detalles de los comandos

• npx hyperframes check pasa (0 hallazgos en lint, runtime, diseño, movimiento y contraste)
• Proyectos con subcomposiciones: npx hyperframes snapshot --at <midpoints> 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