Instalación del plugin: Antes de ejecutar comandos de configuración o actualización, sigue las reglas de instalación del plugin cuando esta habilidad 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 (léelos primero):
- Centra con
flex/inset, no contransform: translate(-50%,-50%)de CSS en un nodo al que luego aplicas GSAPx/y. Lint:gsap_css_transform_conflict. UsafromTooxPercent/yPercent. - No agregues un
tl.set(..., {visibility:"hidden"})al final de la escena. El runtime ya oculta los clips temporizados. Los fundidos de opacidad en nodos internos (oopacityen.clip) son suficientes. Los cortes abruptos de subtítulos siguen otra regla. 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 buscable y cuya reproducción de medios es controlada por el framework.
Esta habilidad 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 según sea necesario. Los documentos de proceso (brief, storyboard, revisión, producción, despacho, frame-worker) viven en /hyperframes → references/. Otros temas viven en las habilidades de dominio hermanas: hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. El mapa de capacidades en /hyperframes dice 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; elegir un arquetipo de sub-composición |
references/data-attributes.md | buscar 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 relativo a otro; listar cada pista y clip con npx hyperframes timeline |
references/creator-editing-recipes.md | copiar recetas verdaderas de corte/recorte/reordenar/retemporizar/congelar/cámara/máscara/encadenado/edición de audio y sus límites |
references/sub-compositions.md | conectar una sub-composición (atributos de 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; 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 Studio v3) |
Para detalles específicos del runtime de animación (API de GSAP, Lottie, Three.js, etc.) ve a hyperframes-animation → adapters/<runtime>.md.
Construyendo una composición
Dos formas de 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 y recurre a su<body>, 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 el
<head><style>/<script>propio del archivo (packages/core/src/compiler/compositionAssembly.ts, la puertahasTemplate), por lo que debes poner<style>/<script>dentro de la plantilla.<link>se eleva de cualquier manera. ⚠ Convención de ID de host: dale a la ranura 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, cableado del host y lista de verificación previa al renderizado → references/sub-compositions.md.
La raíz debe tener tamaño (bug de diseño silencioso)
La raíz independiente usa width/height: 100%. El tamaño del lienzo es data-width/data-height. El runtime estampa esos píxeles en la raíz de la composición. No codifiques 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 de la raíz). Se admite construirla dentro de una llamada asíncrona (document.fonts.ready); lo que importa es que la 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 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 de la raíz y la longitud 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 no GSAP) → references/determinism-rules.md + hyperframes-animation/adapters/.
Errores comunes de lint de primera pasada (una falla de construcción inicial garantizada)
Reglas que lint sí detecta, pero solo después del hecho. Escríbelas bien desde el principio:
- Nunca combines un
transformCSS inicial con una interpolación GSAP en la misma propiedad — el valor CSS y el inicio de la interpolación luchan ylintlo rechaza congsap_css_transform_conflict. Establece el estado inicial dentro de la interpolación congsap.fromTo(el, { x: -40 }, { x: 0 })en lugar de untransform: translateX(-40px)de CSS. - 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 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 interpoles un
.clipconautoAlphaovisibility—lintlo rechaza congsap_animates_clip_element. Anima un hijo en su lugar. - Una
font-familyCSS nombrada necesita un@font-faceen el archivo a un archivo local enviado, olintdisparafont_family_without_font_face. - El
#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 se lee como 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 (bugs silenciosos que las puertas automáticas pueden pasar por alto)
Expuestas aquí; 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 interpoles
display,visibilityoautoAlphaen un elemento.clip. El framework posee 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-comp). Un límite estricto:lintda error si un<video data-start>está dentro de otro elemento simple que también tienedata-start, y la falla es real (fotogramas fuente incorrectos, luego el clip desaparece a mitad de la ranura), así que pon la temporización en el contenedor o en el video, nunca en ambos. Los hosts de sub-composiciones 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 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 tus propios CSS#idy las llamadasgetElementByIdse resuelvan. 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 reciben el estampado, por lo que los ids únicos todavía importan allí. →composition-patterns.md - Un relleno de pantalla completa en la raíz de la composición está bien en un renderizado normal. Se descarta solo en la ruta de composición en capas (contenido HDR, o una composición que usa transiciones de shader), donde el motor fuerza cada raíz de composición transparente 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
Editando composiciones existentes
- Lee los archivos primero. Preserva la temporización, pistas, IDs, variables y 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. - Haz coincidir los IDs de composición y las claves de línea de tiempo existentes.
- Agregar un clip: establece su
data-start/data-durationintencionalmente en relación con los clips circundantes.data-track-indexes un carril de visualización del 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 se alterna con el icono de ojo de la línea de tiempo del Studio.- Agregar una sub-composición: verifica su
data-composition-idinterno antes de cablear 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 visualmente cada fotograma -
npx hyperframes preview --backgroundpara revisión (el usuario puede editar cualquier cosa en la línea de tiempo del Studio, y el servidor sobrevive al comando invocador) -
npx hyperframes rendersolo después de que el usuario lo apruebe