HyperFrames Core
Errores comunes del agente (léelos primero):
- Centra con flex/
inset, no con CSStransform: translate(-50%,-50%)en un nodo al que luego 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 título siguen 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 escenario.screenshot+software gpuen Linux es la ruta lenta.
HyperFrames renderiza vídeo 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 seekable, y cuya reproducción multimedia es gestionada por el framework.
Esta habilidad 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, dispatch, frame-worker) viven 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 indica 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 monolítico vs modular; estructurar un index.html modular; elegir un arquetipo de subcomposición |
references/data-attributes.md | consultar cualquier data-* (raíz / clip / host de subcomposición / alias heredados); usar class="clip" |
references/tracks-and-clips.md | entender qué controla data-track-index (y qué no), el 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 de edición (cortar/recortar/reordenar/retemporizar/congelar/cámara/máscara/encadenado/audio) verdaderas y sus límites |
references/sub-compositions.md | cablear 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>, establecer volumen, recortar |
references/determinism-rules.md | construir un timeline seekable; prohibiciones de determinismo; layout / 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). - Subcomposición (cargada mediante
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 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 el propio
<head><style>/<script>del archivo (packages/core/src/compiler/compositionAssembly.ts, la puertahasTemplate), así que coloca<style>/<script>dentro de la plantilla.<link>se eleva de cualquier manera. ⚠ Convención de id del host: dale 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, cableado del host y lista de verificación previa al render → references/sub-compositions.md.
La raíz debe tener tamaño (bug de layout silencioso)
La raíz independiente establece width/height: 100%. El tamaño del lienzo es data-width/data-height. El runtime imprime esos píxeles en la raíz de la composición. No codifiques 1920px/1080px en #root. Esqueleto → references/minimal-composition.md.
Un timeline en pausa
Cada composición registra exactamente un gsap.timeline({ paused: true }) en window.__timelines["<id>"] (clave = data-composition-id raíz). Construirlo dentro de un callback asíncrono (document.fonts.ready) es compatible; lo importante es que registres solo después de que la construcción se complete. La duración del render es el data-duration de la raíz, no la duración del timeline: un timeline que se extiende más allá se corta, y uno que termina antes mantiene su último fotograma. Omite el data-duration de la raíz y la duración se infiere en su lugar (timeline, ventana multimedia o adaptador). No necesitas window.__timelines = window.__timelines || {}: el runtime crea el registro antes de que tus scripts inline se ejecuten, y lint ya no lo requiere. No anides manualmente subtimelines en el host; el runtime anida automáticamente los timelines hijos registrados. Contrato completo (incluyendo runtimes que no son GSAP) → references/determinism-rules.md + hyperframes-animation/adapters/.
Errores comunes de lint en la primera pasada (un fallo de construcción garantizado)
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), 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 vídeo, 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 render 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 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 layout y contraste: check entonces reporta 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 (bugs silenciosos que las compuertas automatizadas pueden pasar por alto)
Expuestas aquí; justificación completa en la referencia vinculada. No las violes:
- Sin relojes en tiempo de render /
Math.randomsin semilla / red / estado de entrada; sinrepeat: -1(usa un contador finito). →determinism-rules.md - Nunca apliques un tween a
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 + 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 subcomposición o envoltorio). 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 de origen incorrectos, luego el clip desaparece en medio del slot), así que coloca la temporización en el envoltorio o en el vídeo, nunca en ambos. Los hosts de subcomposición están exentos: el multimedia dentro de una subcomposición se renderiza correctamente. La otra advertencia son los timelines, no la colocación: un timeline de subcomposició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 subcomposición 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 esto: el compilador sella 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 sellan, 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 render 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 que cada raíz de composición sea 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
Editar composiciones existentes
- Lee los archivos primero. Preserva la temporización, pistas, IDs, variables y rutas de medios no relacionadas.
- Para saber qué hay en el timeline de un proyecto (pistas, clips, inicios, fines, 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 existentes y las claves de timeline.
- 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. data-hiddenen cualquier elemento de composición lo oculta TANTO en la vista previa como en el render, anulando su ventana de tiempo; es no destructivo/reversible y se alterna con el icono de ojo del timeline de Studio.- 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, layout, motion y contraste) - Proyectos con subcomposiciones:
npx hyperframes snapshot --at <midpoints>y examina cada fotograma -
npx hyperframes preview --backgroundpara revisión (el usuario puede editar cualquier cosa en el timeline de Studio, y el servidor sobrevive al comando invocador) -
npx hyperframes rendersolo después de que el usuario lo apruebe