Instalación de plugins: Antes de ejecutar comandos de configuración o actualización, sigue las reglas de ejecución de plugins cuando esta habilidad esté dentro de un plugin HyperFrames. Las instalaciones independientes conservan las instrucciones de actualización a continuación.
HyperFrames Core
Errores comunes del agente (léelos primero):
- Centrar con flex/
inset, no con CSStransform: translate(-50%,-50%)en un nodo al que luego le apliques 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 bruscos 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 (seekable), y cuya reproducción de medios es gestionada por el framework.
Esta habilidad es el contrato técnico: cómo construir un proyecto 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, envío, frame-worker) están en /hyperframes → references/. Otras preocupaciones viven en las habilidades de dominio hermanas: hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. El mapa de capacidades en /hyperframes dice lo que 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 monolítico vs modular; estructurar un index.html modular; elegir un arquetipo de subcomposición |
references/data-attributes.md | buscar cualquier data-* (raíz / clip / host de subcomp / alias heredados); usar class="clip" |
references/tracks-and-clips.md | entender lo que data-track-index controla (y 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 corte/recorte/reordenación/retemporización/congelación/cámara/máscara/encadenado/audio y sus límites |
references/sub-compositions.md | configurar 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 seekable; 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 en tiempo de ejecución 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.
Construyendo 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 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 usa su<body>como respaldo, 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
<style>/<script>propios del archivo (packages/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 usa como respaldo la primera raíz del 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 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 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 que importa es que la registres solo después de que la construcción se complete. La longitud 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 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 sublíneas de tiempo en el host; el runtime anida automáticamente las líneas de tiempo hijas registradas. Contrato completo (incl. runtimes no GSAP) → references/determinism-rules.md + hyperframes-animation/adapters/.
Errores comunes de lint en primera pasada (un fallo 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 envoltorio o el video, nunca 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 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. - El
#rootde una 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 entonces informa 0 sample(s) y 0/0 text checks, 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 (errores silenciosos que las compuertas automáticas pueden pasar por alto)
Aquí se muestran; 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 contador 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 cuerpo del texto; los elementos transformados deben ser de nivel 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>de subcomp o envoltorio). Un límite estricto:lintgenera error si un<video data-start>está dentro de otro elemento simple que también tienedata-start, y el fallo es real (fotogramas de origen incorrectos, luego el clip desaparece a mitad del slot), así que pon la temporización en el envoltorio 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 ubicació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 subcomp con el id de la composición,#<id>-hero) para que tus llamadas a#idCSS ygetElementByIdse resuelvan. La inyección de marcos ya no depende de esto: el compilador coloca undata-hf-render-idúnico en el documento en cadavideo[src]/audio[src]/img[src]. Los medios que usan hijos<source>en lugar de un atributosrcno reciben esta marca, 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 use transiciones con shaders), donde el motor fuerza que todas las raíces de composición sean transparentes para que la capa inferior se vea. Si tu composición usa transiciones con shaders o medios HDR, coloca el relleno en un hijo que ocupe toda la sangría (
position:absolute; inset:0). →composition-patterns.md
Editando composiciones existentes
- Lee los archivos primero. Conserva la temporización, pistas, IDs, variables y rutas de medios no relacionados.
- Para saber lo que hay en la línea de tiempo de un proyecto (pistas, clips, inicios, fines, lo que 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 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 activa/desactiva con el icono del ojo en la línea de tiempo de Studio.- Al añadir una subcomposició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 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 de invocación) -
npx hyperframes rendersolo después de que el usuario lo apruebe