AntlersSam/saas-launch-video-kit

Instalación del plugin: Antes de los comandos de configuración o actualización, sigue las reglas de ejecución del plugin 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 con CSS transform: translate(-50%,-50%) en un nodo al que luego aplicas GSAP x/y. Lint: gsap_css_transform_conflict. Usa fromTo o xPercent/yPercent.
• No agregues una salida de escena tl.set(..., {visibility:"hidden"}). El runtime ya oculta los clips temporizados. Los desvanecimientos de opacidad en nodos internos (u opacity en .clip) son suficientes. Los cortes duros de subtítulos son una regla diferente.
• window.__timelines["id"] debe coincidir con el data-composition-id raíz.
• Después de render, lee la segunda línea del resumen: beginframe vs screenshot, modo GPU, tiempos de etapa. screenshot + software gpu en 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 multimedia es gestionada por el framework.

Este skill 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 bajo demanda. Los documentos de proceso (brief, storyboard, revisión, producción, envío, frame-worker) viven en /hyperframes → references/. Otras preocupaciones viven en los skills de dominio hermanos — hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. El mapa de capacidades en /hyperframes dice lo que cubre cada uno.

Referencias

Archivo	Léelo para…
references/minimal-composition.md	comenzar 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 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 (y qué no) data-track-index, 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 cortar/recortar/reordenar/retemporizar/congelar/cámara/máscara/encadenado/edición de audio y sus límites
references/sub-compositions.md	cablear una sub-composició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 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 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.html de nivel superior): el <div data-composition-id="…"> raíz se sitúa directamente en <body>, sin envoltorio <template>. Envolver una raíz independiente oculta todo el contenido y lint lo rechaza (standalone_composition_wrapped_in_template, error).
• Sub-composició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 sub-composición con plantilla, el ensamblador descarta los <style>/<script> del <head> propio del archivo (packages/core/src/compiler/compositionAssembly.ts, la compuerta hasTemplate), por lo que debes poner <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 clave window.__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 (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 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 raíz). Se admite construirla dentro de un callback asíncrono (document.fonts.ready); lo que importa es que registres solo después de que la construcción se complete. 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 duración 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 sub-líneas de tiempo en el host; el runtime anida automáticamente las líneas de tiempo hijas registradas. Contrato completo (incl. runtimes que no son GSAP) → references/determinism-rules.md + hyperframes-animation/adapters/.

Errores comunes de lint en la primera pasada (fallo garantizado en la primera compilación)

Reglas que lint sí detecta, pero solo después del hecho. Escríbelas correctamente la primera vez:

• Nunca combines un transform CSS inicial con un tween de GSAP en la misma propiedad — el valor CSS y el inicio del tween entran en conflicto y lint lo rechaza con gsap_css_transform_conflict. Establece el estado inicial dentro del tween con gsap.fromTo(el, { x: -40 }, { x: 0 }) en lugar de un CSS transform: translateX(-40px).
• Nunca pongas crossorigin en <video>/<audio>. lint lo rechaza incondicionalmente con media_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 lleve data-start. lint lo rechaza con video_nested_in_timed_element (error). Temporiza el envoltorio o el video, no ambos.
• Cada <audio> necesita un id. lint lo rechaza con media_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 .clip con autoAlpha o visibility — lint lo rechaza con gsap_animates_clip_element. Anima un hijo en su lugar.
• Un font-family CSS nombrado necesita un @font-face en el archivo que apunte a un archivo local enviado, o lint dispara font_family_without_font_face.
• La #root de la sub-composición usa width/height: 100% (o inset: 0), no 1920px/1080px codificados. El tamaño del lienzo es data-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 (errores silenciosos que las compuertas 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.random sin semilla / red / estado de entrada; sin repeat: -1 (usa un recuento finito). → determinism-rules.md
• Nunca apliques tween a display, visibility o autoAlpha en un elemento .clip. El framework es dueño de la visibilidad del clip, y lint lo rechaza (gsap_animates_clip_element). Anima un hijo en su lugar. → determinism-rules.md
• Sin <br> en 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> o envoltorio de sub-comp). Un límite estricto: lint falla si un <video data-start> está dentro de otro elemento simple que también tiene data-start, y el fallo es real (marcos de origen incorrectos, luego el clip desaparece a mitad de ranura), así que pon la temporización en el envoltorio 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, ej. #<id>-hero) para que tus propias llamadas a CSS #id y getElementById se resuelvan. La inyección de fotogramas ya no depende de esto: el compilador estampa un data-hf-render-id único del documento en cada video[src]/audio[src]/img[src]. Los medios que usan hijos <source> en lugar de un atributo src no 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 elimina solo en la ruta de composición 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 se vea la capa inferior. Si tu composición usa transiciones de shader o medios HDR, pon 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 no relacionada, pistas, IDs, variables, rutas de medios.
• 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 leer index.html y cada archivo de sub-composición.
• Coincide con los IDs de composición existentes y las claves de línea de tiempo.
• Agregar un clip: establece su data-start/data-duration intencionalmente en relación con los clips circundantes. data-track-index es 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-duration raíz se corta: extiende el data-duration raíz hasta el final del clip en la misma edición (lint advierte clip_ends_past_root_duration).
• data-hidden en cualquier elemento de la 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 de Studio.
• Agregar una sub-composición: verifica su data-composition-id interno antes de cablear el host.

Validación

Usa hyperframes-cli para detalles de comandos

• npx hyperframes check pasa (0 hallazgos en lint, runtime, diseño, movimiento y contraste)
• Proyectos con sub-composiciones: npx hyperframes snapshot --at <midpoints> y examina visualmente cada fotograma
• npx hyperframes preview --background para 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 render solo después de que el usuario lo apruebe