Instalación de plugins: Antes de los 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 mantienen las instrucciones de actualización a continuación.
HyperFrames Core
Errores comunes del agente (leer primero):
- Centrar con flex/
inset, no con CSStransform: translate(-50%,-50%)en un nodo al que luego aplicas GSAPx/y. Lint:gsap_css_transform_conflict. UsafromTooxPercent/yPercent. - No agregues un
tl.set(..., {visibility:"hidden"})de salida de escena. El runtime ya oculta los clips temporizados. Los fundidos de opacidad en nodos internos (oopacityen.clip) son suficientes. Los cortes de títulos son una regla diferente. window.__timelines["id"]debe coincidir con eldata-composition-idraíz.- Después de
render, lee la segunda línea del resumen:beginframevsscreenshot, modo GPU, tiempos de etapa.screenshot+software gpuen 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 con atributos data-*, cuyo runtime de animación es reproducible posicionalmente (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 a continuación es la guía de construcción; los detalles por tema viven en references/ (índice a continuación), léelos bajo demanda. Los documentos de proceso (brief, storyboard, revisión, producción, envío, frame-worker) viven en /hyperframes → references/. Otros temas viven en los skills de dominio relacionados — hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. El mapa de capacidades en /hyperframes dice lo que cubre cada uno.
Referencias
| Archivo | Léelo para… |
|---|---|
references/minimal-composition.md | comenzar con 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 sub-composición |
references/data-attributes.md | consultar cualquier data-* (raíz / clip / host de sub-composición / alias heredados); usar class="clip" |
references/tracks-and-clips.md | entender qué controla data-track-index (y qué no), z-index, temporizar un clip relativo a otro; listar cada pista y clip con npx hyperframes timeline |
references/creator-editing-recipes.md | copiar recetas de edición (cortar/recortar/reordenar/retemporizar/congelar/cámara/máscara/encadenado/fundido/audio) verdaderas 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 reproducible posicionalmente; prohibiciones de determinismo; diseño / ajuste de 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.
Construir 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>. Envolver una raíz independiente oculta todo el contenido ylintlo rechaza (standalone_composition_wrapped_in_template, error). - Sub-composición (cargada vía
data-composition-src): envuelve la raíz en<template>. Esta es la forma a escribir: el cargador también acepta un documento completo simple y usa su<body>como fallback, pero la forma con plantilla es la que asumen los ejemplos y las herramientas.
⚠ Regla de transporte: para una sub-composición con plantilla, el ensamblador descarta los
<style>/<script>del<head>del archivo (enpackages/core/src/compiler/compositionAssembly.ts, la compuertahasTemplate), así que coloca<style>/<script>dentro de la plantilla.<link>se eleva de cualquier manera. ⚠ Convención de ID del host: da al slot del host, a la plantilla interna y a la clavewindow.__timelines["<id>"]el mismo id. Se admite un id local diferente (el ensamblador recurre a la primera raíz en el archivo), pero el desajuste es silencioso, así que hazlos coincidir a menos que tengas una razón para no hacerlo.
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 aplica width/height: 100%. El tamaño del lienzo es data-width/data-height. El runtime asigna esos píxeles a la raíz de la composición. No codifiques 1920px/1080px en #root. 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). Construirla dentro de un callback asíncrono (document.fonts.ready) está permitido; lo que importa es que registres solo después de que la construcción se complete. La duración del renderizado es el data-duration de la 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. Omite el data-duration raíz y la duración se infiere en su lugar (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 solicita. No anides manualmente sub-lí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 en la primera pasada (un primer error de construcción garantizado)
Reglas que lint sí detecta, pero solo después del hecho. Escríbelas bien desde el principio:
- 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 un CSStransform: translateX(-40px). - Nunca pongas
crossoriginen<video>/<audio>.lintlo rechaza incondicionalmente conmedia_crossorigin_breaks_preview(error), incluso para lectura de canvas/WebGL/WebAudio. No hay supresión. - Nunca le des a un
<video data-start>un ancestro que también tengadata-start.lintlo rechaza convideo_nested_in_timed_element(error). Temporiza el contenedor o el video, no ambos. - Cada
<audio>necesita unid.lintlo rechaza conmedia_missing_id, y un<audio>sin id nunca es recogido por el mezclador, por lo que el renderizado es silencioso. - Nunca apliques tween a un
.clipconautoAlphaovisibility—lintlo rechaza congsap_animates_clip_element. Anima un elemento hijo en su lugar. - Un
font-familyCSS con nombre necesita un@font-faceen el archivo que apunte a un archivo local enviado, olintlanzafont_family_without_font_face. - La
#rootde una sub-composición usawidth/height: 100%(oinset: 0), no1920px/1080pxcodificados. El tamaño del lienzo esdata-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. Limpia los errores de lint antes de confiar en esos números.
Reglas no negociables (errores silenciosos que las compuertas automatizadas pueden pasar por alto)
Se muestran 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;repeat: -1solo bajo undata-durationraíz finito (exporta clips a él — de lo contrario usa un conteo finito). →determinism-rules.md - Nunca apliques tween a
display,visibilityoautoAlphaen un elemento.clip. El framework gestiona la visibilidad del clip, ylintlo rechaza (gsap_animates_clip_element). Anima un hijo en su lugar. →determinism-rules.md - Sin
<br>en el texto del cuerpo; los elementos transformados deben ser de nivel de bloque y tener tamaño; los decorativos absolutos pulsantes necesitan espacio libre máximo. →determinism-rules.md <video>/<audio>se encuentran mediante una consulta plana del documento, por lo que el framework los busca y decodifica a cualquier profundidad de anidamiento (incluyendo dentro de un<template>o contenedor de sub-composición). Un límite estricto:lintda error si un<video data-start>está dentro de otro elemento simple que también tienedata-start, y el fallo es real (fotogramas fuente incorrectos, luego el clip desaparece a mitad de la ranura), así que coloca la temporización en el contenedor o en el video, nunca en ambos. Los hosts de sub-composición están exentos: los medios dentro de una sub-composición se renderizan correctamente. La otra advertencia son las líneas de tiempo, no la ubicación: una línea de tiempo de sub-composición 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 sub-composición con el id de la composición,#<id>-hero) para que tus CSS#idy las llamadasgetElementByIdse resuelvan. La inyección de fotogramas ya no depende de esto: el compilador asigna undata-hf-render-idúnico en el documento a cadavideo[src]/audio[src]/img[src]. Los medios que usan hijos<source>en lugar de un atributosrcno reciben esta asignación, 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 está bien en un renderizado normal. Se elimina solo en la ruta de composición en capas (contenido HDR, o una composición que usa transiciones de shader), donde el motor fuerza que cada raíz de composición sea transparente para que la capa inferior se vea. 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
Editar composiciones existentes
- Lee los archivos primero. Conserva la temporización, pistas, IDs, variables, rutas de medios no relacionadas.
- 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 leerindex.htmly cada archivo de sub-composición. - Coincide con los IDs de composición y claves de línea de tiempo existentes.
- Añadir un clip: establece su
data-start/data-durationintencionalmente en relación con los clips circundantes.data-track-indexes 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-durationraíz se corta: extiende eldata-durationraíz hasta el final del clip en la misma edición (lintadvierteclip_ends_past_root_duration). data-hiddenen cualquier elemento de la 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 ícono de ojo en la línea de tiempo de Studio.- Añadir una sub-composición: verifica su
data-composition-idinterno antes de conectar el host.
Validación
Usa hyperframes-cli para detalles de comandos
-
npx hyperframes checkpasa (0 hallazgos en lint, runtime, diseño, movimiento y contraste) - Proyectos con sub-composiciones:
npx hyperframes snapshot --at <midpoints>y revisa cada fotograma visualmente -
npx hyperframes preview --backgroundpara revisión (el usuario puede editar cualquier cosa en la línea de tiempo de Studio, y el servidor sobrevive al comando de invocación) -
npx hyperframes rendersolo después de la aprobación del usuario