HyperFrames Core
Trampas para agentes (léase primero):
- Centrar con
flex/inset, no con CSStransform: 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. Las eliminaciones forzadas 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 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 bajo demanda. Los documentos de proceso (brief, storyboard, revisión, producción, despacho, frame-worker) viven en /hyperframes → references/. Otros temas viven en los skills de dominio hermanos — hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. El mapa de capacidades en /hyperframes detalla lo que cubre cada uno.
Referencias
| Archivo | Léelo para… |
|---|---|
references/minimal-composition.md | empezar con 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; escoger un arquetipo de subcomposición |
references/data-attributes.md | buscar cualquier data-* (raíz / clip / host de subcomp / alias legacy); 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; lista cada pista y clip con npx hyperframes timeline |
references/creator-editing-recipes.md | copiar recetas veraces de cortar/recortar/reordenar/retemporizar/congelar/cámara/máscara/encadenamiento/edición de audio y sus límites |
references/sub-compositions.md | cablear una subcomposició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 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.
Construir una composición
Dos formas raíz (no intercambiables)
- Independiente (
index.htmlde nivel superior): el<div data-composition-id="…">raíz va 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 recurre a su<body>, pero la forma con template es la que asumen los ejemplos y las herramientas.
⚠ Regla de transporte: para una subcomposición con template, el ensamblador descarta el
<head><style>/<script>del archivo (packages/core/src/compiler/compositionAssembly.ts, por la puertahasTemplate), así que coloca<style>/<script>dentro del template.<link>se eleva de cualquier forma. ⚠ Convención de id de host: dale al slot del host, al template interno y a la clavewindow.__timelines["<id>"]el mismo id. Se soporta 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 diseño silencioso)
La raíz independiente usa 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.
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 permite construirla dentro de un callback asíncrono (document.fonts.ready); lo importante es que registres solo después de que la construcción termine. La duración del render 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 duración se infiere (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 pide. No anides manualmente subtl 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 de lint de primera pasada (fallo garantizado en el primer build)
Reglas que lint sí detecta, pero solo después de los hechos. Escríbelas correctamente la primera vez:
- 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 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 recogido por el mezclador, por lo que el render es silencioso. - Nunca hagas tween a un
.clipconautoAlphaovisibility—lintlo rechaza congsap_animates_clip_element. Anima un elemento hijo en su lugar. - Una
font-familyCSS con nombre necesita un@font-faceen el archivo que apunte a un archivo local enviado, olintdisparafont_family_without_font_face. - La
#rootde una subcomposición usawidth/height: 100%(oinset: 0), no valores fijos1920px/1080px. 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 puertas automáticas pueden pasar por alto)
Se exponen aquí; la justificación completa está en la referencia enlazada. No violes:
- Sin relojes en tiempo de render /
Math.randomsin semilla / red / estado de entrada; sinrepeat: -1(usa un recuento finito). →determinism-rules.md - Nunca hagas tween a
display,visibilityoautoAlphaen un elemento.clip. El framework es dueño de la visibilidad del clip, ylintlo rechaza (gsap_animates_clip_element). Anima un hijo. →determinism-rules.md - Sin
<br>en el texto del cuerpo; los elementos transformados deben ser de nivel de bloque + con tamaño; los elementos decorativos absolutos pulsantes necesitan espacio 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 del<template>o envoltorio de una subcomp). Un límite firme: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 medio 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 colocació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 propios CSS#idy llamadasgetElementByIdresuelvan. La inyección de fotogramas ya no depende de ello: el compilador imprime 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 la 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 render normal. Solo se elimina en la ruta de composición en capas (contenido HDR, o una composición que usa transiciones de shader), donde el motor fuerza transparente cada raíz de composición para que la capa inferior se vea. Si tu composición usa transiciones de shader o medios HDR, pon el relleno en un hijo a sangre (
position:absolute; inset:0). →composition-patterns.md
Editar composiciones existentes
- Lee primero los archivos. Preserva la temporización, pistas, IDs, variables y rutas de medios no relacionados.
- 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 subcomposición. - Coincide con los IDs de composición y las claves de línea de tiempo existentes.
- Al añadir un clip: establece
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 la composición lo oculta tanto en la vista previa como en el render, anulando su ventana de tiempo; es no destructivo/reversible y se activa/desactiva mediante 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 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 invocador) -
npx hyperframes rendersolo después de la aprobación del usuario