Instalación de plugins: Antes de los comandos de configuración o actualización, sigue las reglas de instalación de plugins cuando este skill esté dentro de un plugin de HyperFrames. Las instalaciones independientes conservan las instrucciones de actualización a continuación.
HyperFrames Core
Errores comunes del agente (léase primero):
- Centrar con flex/
inset, no contransform: translate(-50%,-50%)en un nodo al que luego se aplique GSAPx/y. Lint:gsap_css_transform_conflict. UsafromTooxPercent/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 (oopacityen.clip) son suficientes. Los cortes de caption 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 sincronización con atributos data-*, cuyo runtime de animación es buscable y cuya reproducción multimedia es gestionada por el framework.
Este 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 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) viven 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 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 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 | entender qué controla data-track-index (y qué no), z-index, temporizar un clip en relación a otro; listar cada pista y clip con npx hyperframes timeline |
references/creator-editing-recipes.md | copiar recetas exactas de cortar/recortar/reordenar/retemporizar/congelar/cámara/máscara/encadenado/edición de audio y sus límites |
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; ajuste de diseño / texto |
references/full-screen-motion.md | crear animaciones a pantalla completa con fondos compartidos |
references/tailwind.md | trabajar en un proyecto Tailwind v4 (init --tailwind; el contrato en tiempo de ejecución difiere del Studio con v3) |
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). - Subcomposición (cargada mediante
data-composition-src): envuelve la raíz en<template>. Esta es la forma que se debe escribir: el cargador también acepta un documento completo y recurre a su<body>, pero la forma con plantilla es la que asumen los ejemplos y las herramientas.
⚠ Regla de transporte: para una subcomposición con plantilla, el ensamblador descarta los propios
<head><style>/<script>del archivo (packages/core/src/compiler/compositionAssembly.ts, la puertahasTemplate), así que coloca<style>/<script>dentro del template.<link>se eleva de cualquier forma. ⚠ Convención de ID del host: dale a la ranura del host, al template interno y a la clavewindow.__timelines["<id>"]el mismo id. Se admite un id local diferente (el ensamblador recurre a la primera raíz del archivo), pero la discrepancia es silenciosa, así que hazlos coincidir a menos que tengas una razón para no hacerlo.
Forma del archivo, cableado del host y la lista de verificación previa al renderizado → references/sub-compositions.md.
La raíz debe tener tamaño definido (error de diseño silencioso)
La raíz independiente usa width/height: 100%. El tamaño del lienzo es data-width/data-height. El runtime aplica 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). 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 esté completa. La duración del renderizado es el data-duration raíz, no la longitud 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 longitud se infiere en su lugar (línea de tiempo, ventana multimedia 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 sublíneas de tiempo en el host; el runtime anida automáticamente las líneas de tiempo hijas registradas. Contrato completo (incluyendo runtimes no GSAP) → references/determinism-rules.md + hyperframes-animation/adapters/.
Errores comunes de lint en la primera pasada (fallo garantizado en la primera construcción)
Reglas que lint sí detecta, pero solo después del hecho. Escríbelas correctamente 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), incluyendo 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 envoltorio o el video, no ambos. - Cada
<audio>necesita unid.lintlo rechaza conmedia_missing_id, y un<audio>sin id nunca es captado por el mezclador, por lo que el renderizado es silencioso. - Nunca apliques un tween a un
.clipconautoAlphaovisibility:lintlo rechaza congsap_animates_clip_element. Anima un 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 la subcomposició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 informa entonces 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 (errores silenciosos que las puertas automatizadas 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.randomsin semilla / red / estado de entrada;repeat: -1solo bajo undata-durationraíz finito (exporta clips a él; de lo contrario, usa un recuento finito). →determinism-rules.md - Nunca apliques un 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 definido; 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 envoltorio de sub-comp). Un límite estricto:lintda error si un<video data-start>está dentro de otro elemento simple que también tengadata-start, y el fallo es real (fotogramas de origen incorrectos, luego el clip desaparece a mitad de ranura), así que coloca la temporización en el envoltorio o en el video, nunca 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 sub-comp no puede animar elementos raíz del host. →variables-and-media.md- Mantén cada
idúnico en la página ensamblada (prefija los ids de sub-comp con el id de la composición,#<id>-hero) para que tu propio CSS#idy las llamadasgetElementByIdfuncionen. La inyección de fotogramas ya no depende de ello: el compilador estampa undata-hf-render-idúnico del documento en cadavideo[src]/audio[src]/img[src]. Los medios que usan hijos<source>en lugar de un atributosrcno se estampan, 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 descarta solo en la ruta de composite en capas (contenido HDR, o una composición que usa transiciones de shader), donde el motor fuerza todas las raíces de composición 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
Editar composiciones existentes
- Lee los archivos primero. Conserva la temporización, pistas, IDs, variables y rutas multimedia no relacionadas.
- Para saber qué hay en la línea de tiempo de un proyecto (pistas, clips, inicios, finales, qué se reproduce), ejecuta
npx hyperframes timeline [--json]en lugar de leerindex.htmly cada archivo de subcomposición. - Haz coincidir los IDs de composición y las claves de línea de tiempo existentes.
- Al añadir un clip: establece su
data-start/data-durationintencionadamente 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 composición lo oculta TANTO en la vista previa como en el renderizado, anulando su ventana de tiempo; no es destructivo/reversible y es alternado por el icono de ojo de la línea de tiempo de Studio.- Al añadir una subcomposición: verifica su
data-composition-idinterno antes de conectar el host.
Validación
Usa hyperframes-cli para los detalles del comando
-
npx hyperframes checkpasa (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 --backgroundpara 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 rendersolo después de que el usuario lo apruebe