HyperFrames
HTML es la fuente de verdad para el video. Una composición es un archivo HTML con atributos data-* para la sincronización, una línea de tiempo de GSAP para la animación y CSS para la apariencia. El marco maneja la visibilidad de los clips, la reproducción de medios y la sincronización de la línea de tiempo.
Integración con Open Design (esencial para esta superficie)
Cuando esta skill se ejecuta dentro de Open Design (es decir, $OD_PROJECT_DIR está configurado), el flujo de salida es fijo: solo el .mp4 renderizado debe terminar en la raíz del proyecto. Los archivos fuente de la composición (hyperframes.json, meta.json, index.html, assets) pertenecen a un directorio de caché oculto para no ensuciar el FileViewer del usuario ni los chips de "archivos producidos" del chat.
Flujo de trabajo de renderizado dentro de OD — ruta rápida:
Para la mayoría de las solicitudes de OD ("video de prueba", "presentación de producto de 5s", "clip demo"), NO escribas la composición HTML desde cero. Usa el andamio (scaffold) integrado de HyperFrames y edita solo lo que el mensaje realmente cambia. La ruta de "creación desde cero" cuesta minutos de salida del modelo y tiempo de herramientas de chat silenciosas; la ruta del andamio cuesta segundos.
# 1. Elige un espacio de caché oculto. El prefijo de punto (dotfile) hace que el listado de archivos del proyecto de OD lo omita, por lo que los archivos fuente nunca ensucian el chat.
COMP_REL=".hyperframes-cache/$(date +%s)-$(openssl rand -hex 2)"
COMP="$OD_PROJECT_DIR/$COMP_REL"
# 2. Obtén un andamio renderizable de inmediato (hyperframes.json,
# meta.json, index.html con CDN de GSAP + window.__timelines.main
# ya registrado). Esto se ejecuta en tu shell — copia de archivos pura,
# sin Chrome, sin red más allá del caché de npx.
npx hyperframes init "$COMP" --example blank --skip-skills --non-interactive
# 3. Edita SOLAMENTE $COMP/index.html — cambia `data-duration` en la raíz
# si necesitas una duración no predeterminada, reemplaza la paleta de
# marcador de posición en <style>, agrega 1 a 3 <div>s de clip para
# texto/imágenes, y agrega los tweens de GSAP correspondientes dentro
# del bloque existente de
# `window.__timelines["main"] = gsap.timeline({paused:true})`.
# Mantén las ediciones mínimas; el andamio ya es HF válido.
# 4. Despacha el renderizado a través del daemon de OD. NO ejecutes `npx hyperframes
# render` desde esta shell — el daemon lo ejecuta por ti en un proceso
# sin sandbox. (Muchas CLI de agentes, en particular Claude Code,
# envuelven Bash en sandbox-exec de macOS, bajo el cual el subproceso de Chrome
# de Puppeteer se cuelga a mitad de la captura de fotogramas. El proceso del daemon
# no tiene sandbox, por lo que los renderizados se completan de manera confiable).
#
# El despachador regresa en ~1s con un {taskId}; lleva el renderizado a
# completitud haciendo un bucle de llamadas `od media wait <taskId>`.
# Cada llamada espera hasta 25s (muy por debajo del límite predeterminado de 30s
# de tu herramienta de shell) y sale con 0/2/5 para indicar hecho/ejecutando/fallido.
out=$(node "$OD_BIN" media generate \
--project "$OD_PROJECT_ID" \
--surface video \
--model hyperframes-html \
--output "<nombre-descriptivo>.mp4" \
--composition-dir "$COMP_REL")
ec=$?
task_id=$(printf '%s\n' "$out" | tail -1 | jq -r '.taskId // empty')
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // 0')
while [ "$ec" -eq 2 ] && [ -n "$task_id" ]; do
out=$(node "$OD_BIN" media wait "$task_id" --since "$since")
ec=$?
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // '"$since")
done
[ "$ec" -ne 0 ] && { echo "$out" >&2; exit "$ec"; }
Cada llamada a generate y cada wait duran como máximo ~25s, por lo que el límite predeterminado de ~30s de la herramienta de shell del agente nunca se activa. Las líneas de progreso de HF (Capturing frame N/M) se transmiten a stderr en vivo durante todo el bucle. Cuando el renderizado finaliza, la última línea de stdout es {"file": { "name": "<output>", "size": …, "kind": "video", … }}: cita file.name en tu respuesta para que el usuario sepa qué se produjo.
Omite la Puerta de Identidad Visual dentro de OD. La sección HARD-GATE a continuación (bajo "Enfoque") te indica que leas DESIGN.md / visual-style.md o que te detengas y hagas 3 preguntas sobre el estado de ánimo antes de escribir cualquier composición. Esa puerta es para proyectos HF independientes. Los proyectos OD ya tienen su propia capa de sistema de diseño — el usuario eligió su dirección visual al crear el proyecto. Para un renderizado de prueba de OD, usa valores predeterminados: lienzo oscuro (#0b0b0f), un acento cálido (#ffb76b), un acento frío (#7da4ff), movimiento contenido. Solo pregunta por aportes estilísticos si el mensaje del usuario es demasiado vago para siquiera elegir un tema (muy raro).
Cuándo omitir el andamio y escribir desde cero: solo cuando el usuario solicite explícitamente algo que la plantilla en blanco claramente no puede alojar (por ejemplo, líneas de tiempo de múltiples composiciones, superposiciones reactivas al audio, subtítulos sincronizados con una pista de TTS que ya han generado). Para todo lo demás, la ruta predeterminada es init + editar.
Los subcomandos de HF más ligeros que AÚN PUEDES ejecutar desde tu propia shell (no necesitan generar Chrome):
npx hyperframes lint "$COMP"— validar composición antes de despacharnpx hyperframes transcribe <audio>— generar subtítulosnpx hyperframes tts <text>— generar narración
Reserva el despacho del daemon para render/inspect/preview (cualquier cosa vinculada a Chrome).
NO llames a od media generate --model hyperframes-html — esa ruta de despachador devuelve un 400 (AGENT_RENDERED) a propósito. HyperFrames se renderiza directamente por ti a través de npx.
NO coloques hyperframes.json / meta.json / index.html en la raíz del proyecto; el listado de archivos de OD escanea de forma recursiva y el usuario vería tres archivos no relacionados aparecer en el chat.
Para opciones de CLI más allá de render (lint, preview, transcribe, tts, inspect, benchmark), llámalas directamente desde tu herramienta de shell cuando la tarea lo justifique (por ejemplo, generar audio TTS en el caché antes de referenciarlo desde la composición).
Enfoque
Antes de escribir HTML, piensa a alto nivel:
- Qué — ¿qué debería experimentar el espectador? Identifica el arco narrativo, los momentos clave y los latidos emocionales.
- Estructura — cuántas composiciones, cuáles son subcomposiciones vs. en línea, qué pistas llevan qué (video, audio, superposiciones, subtítulos).
- Sincronización — qué clips determinan la duración, dónde caen las transiciones, cuál es el ritmo.
- Diseño — construye el estado final primero. Ver "Diseño antes de la animación" a continuación.
- Animar — luego agrega movimiento usando las reglas a continuación.
Para ediciones pequeñas (corregir un color, ajustar la sincronización, agregar un elemento), ve directamente a las reglas.
Puerta de Identidad Visual
Verifica en este orden:
- ¿Existe DESIGN.md en el proyecto? → Léelo. Usa sus colores, fuentes, reglas de movimiento y restricciones de "Qué NO hacer".
- ¿Existe visual-style.md? → Léelo. Aplica su
style_prompt_fully campos estructurados. (Nota:visual-style.mdes un archivo específico del proyecto.visual-styles.mdes la biblioteca de estilos con 8 presets con nombre — archivos diferentes). - ¿El usuario nombró un estilo (por ejemplo, "Swiss Pulse", "oscuro y tecnológico", "marca de lujo")? → Lee visual-styles.md para los 8 presets con nombre. Genera un DESIGN.md mínimo con:
## Style Prompt(un párrafo),## Colors(3-5 valores hex con roles),## Typography(1-2 familias de fuentes),## What NOT to Do(3-5 anti-patrones). - ¿Nada de lo anterior? → Haz 3 preguntas antes de escribir cualquier HTML:
- ¿Cuál es el estado de ánimo? (explosivo / cinematográfico / fluido / técnico / caótico / cálido)
- ¿Lienzo claro u oscuro?
- ¿Algún color de marca, fuente o referencia visual específica? Luego genera un DESIGN.md mínimo a partir de las respuestas.
Cada composición debe rastrear su paleta y tipografía hasta un DESIGN.md, visual-style.md o dirección explícita del usuario. Si estás utilizando #333, #3b82f6 o Roboto — omitiste este paso.
Para valores predeterminados de movimiento, tamaño, patrones de entrada y easing — sigue house-style.md. El estilo de la casa maneja CÓMO se mueven las cosas. El DESIGN.md maneja CÓMO SE VEN las cosas.
Diseño antes de la animación
Posiciona cada elemento donde debería estar en su momento más visible — el fotograma en el que ha entrado completamente, está colocado correctamente y aún no está saliendo. Escribe esto como HTML+CSS estático primero. Sin GSAP todavía.
Por qué esto es importante: Si posicionas elementos en su estado inicial animado (fuera de pantalla, escalados a 0, opacidad 0) y los interpolas hasta donde crees que deberían terminar, estás adivinando el diseño final. Las superposiciones son invisibles hasta que el video se renderiza. Al construir el estado final primero, puedes ver y solucionar problemas de diseño antes de agregar cualquier movimiento.
El proceso
- Identifica el fotograma héroe para cada escena — el momento en que la mayoría de los elementos son visibles simultáneamente. Este es el diseño que construyes.
- Escribe CSS estático para ese fotograma. El contenedor
.scene-contentDEBE llenar la escena completa usandowidth: 100%; height: 100%; padding: Npx;condisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Usa padding para empujar el contenido hacia adentro — NUNCA usesposition: absolute; top: Npxen un contenedor de contenido. Los contenedores de contenido con posición absoluta se desbordan cuando el contenido es más alto que el espacio restante. Reservaposition: absolutesolo para elementos decorativos. - Agrega entradas con
gsap.from()— anima DESDE fuera de pantalla/invisible HASTA la posición CSS. La posición CSS es la verdad absoluta; el tween describe el viaje para llegar allí. - Agrega salidas con
gsap.to()— anima HASTA fuera de pantalla/invisible DESDE la posición CSS.
Ejemplo
/* scene-content llena la escena, padding posiciona el contenido */
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
width: 100%;
height: 100%;
padding: 120px 160px;
gap: 24px;
box-sizing: border-box;
}
.title {
font-size: 120px;
}
.subtitle {
font-size: 42px;
}
/* El contenedor se adapta a cualquier tamaño de escena (1920x1080, 1080x1920, etc.).
El padding posiciona el contenido. Flex + gap maneja el espaciado. */
INCORRECTO — dimensiones codificadas y posicionamiento absoluto:
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// Paso 3: Animar HACIA esas posiciones
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
// Paso 4: Animar FUERA de esas posiciones
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
Cuando los elementos comparten espacio a lo largo del tiempo
Si el elemento A sale antes de que el elemento B entre en la misma área, ambos deben tener posiciones CSS correctas para sus respectivos fotogramas héroe. El orden de la línea de tiempo garantiza que nunca coexistan visualmente — pero si omites el paso de diseño, no detectarás el caso en que se superponen accidentalmente debido a un error de sincronización.
Qué cuenta como superposición intencional
Los efectos en capas (brillo detrás del texto, elementos de sombra, patrones de fondo) y los diseños apilados en Z (pilas de tarjetas, capas de profundidad) son intencionales. El paso de diseño se trata de detectar superposiciones no intencionales — dos titulares que caen uno sobre otro, una estadística que cubre una etiqueta, contenido que se sale del fotograma.
Atributos de Datos
Todos los Clips
| Atributo | Requerido | Valores |
|---|---|---|
id | Sí | Identificador único |
data-start | Sí | Segundos o referencia de ID de clip ("el-1", "intro + 2") |
data-duration | Requerido para img/div/composiciones | Segundos. Video/audio por defecto a la duración del medio. |
data-track-index | Sí | Entero. Los clips de la misma pista no pueden superponerse. |
data-media-start | No | Desplazamiento de recorte en el origen (segundos) |
data-volume | No | 0-1 (por defecto 1) |
data-track-index no afecta la superposición visual — usa CSS z-index.
Clips de Composición
| Atributo | Requerido | Valores |
|---|---|---|
data-composition-id | Sí | ID de composición único |
data-start | Sí | Hora de inicio (composición raíz: usa "0") |
data-duration | Sí | Tiene prioridad sobre la duración de la línea de tiempo de GSAP |
data-width / data-height | Sí | Dimensiones en píxeles (1920x1080 o 1080x1920) |
data-composition-src | No | Ruta al archivo HTML externo |
Estructura de la Composición
Las subcomposiciones cargadas a través de data-composition-src usan un wrapper <template>. Las composiciones independientes (el index.html principal) NO usan <template> — colocan el div data-composition-id directamente en <body>. Usar <template> en un archivo independiente oculta todo el contenido del navegador y rompe el renderizado.
Estructura de la subcomposición:
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- contenido -->
<style>
[data-composition-id="my-comp"] {
/* estilos con ámbito */
}
</style>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
// tweens...
window.__timelines["my-comp"] = tl;
</script>
</div>
</template>
Cargar en la raíz: <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>
Video
…
[truncado para traducción]