Hyperframes Bridge
Orquestado por: SKILL. Envoltorio de dependencia externa. El monorepo real de Hyperframes vive en
../../external/hyperframes/(clonado por/amw-initpaso 6 si el usuario lo acepta, O por este skill en el primer render como respaldo). Este skill documenta el patrón de shell-out; NO incluye el monorepo.
Resumen
Renderiza composiciones HTML a video MP4 ejecutando comandos en el monorepo Hyperframes (external/hyperframes/). Acepta un único archivo HTML de escena o un directorio de proyecto Hyperframes completo. Ejecuta la puerta de pre-renderizado obligatoria (lint → validar → inspeccionar → renderizar) antes de llamar a npx hyperframes render --output <mp4>. Devuelve la ruta del MP4 y un informe de finalización del trabajo. No se reimplementa el pipeline de Hyperframes dentro del plugin — solo shell-out.
Instrucciones
- Verificar el repositorio externo con dos comprobaciones: debe existir
external/hyperframes/package.json, ynpx hyperframes render --helpdebe responder; fallar rápidamente si alguna comprobación falla. - Resolver el directorio del proyecto: usar
project_dirsi se proporciona, o crear un proyecto temporal a partir dehtml_scene_path; fallar inmediatamente si no se proporciona ninguno. - Ejecutar la secuencia de la puerta de pre-renderizado en orden:
lint → validar → inspeccionar → renderizar(abortar si algún paso devuelve un código distinto de cero). - Ejecutar
cd "$HF_PROJ_DIR" && npx hyperframes render --output <mp4>; recolectar la ruta de salida. - Confirmar que el archivo MP4 existe y no está vacío; informar la ruta de salida y cualquier advertencia de
inspeccionar. - Consultar la sección
## Patrón de invocaciónmás abajo para los pasos de ejecución autorizados.
Activación
Sin comando de barra dedicado — este skill no tiene un acceso directo /amw-*. Es invocado por el orquestador design-principles como el paso final de la Fase B en modo agente principal cuando el diseño aprobado requiere salida de video MP4. El orquestador puede aplicar el pipeline completo de shell-out de Hyperframes y las técnicas de composición de este skill sin restricción de capa de comandos.
Este skill es autónomo y auto-contenido — cualquier agente (el agente principal, un sub-agente o un orquestador externo) puede usarlo leyendo este SKILL.md y sus referencias. Las técnicas del skill NO están limitadas a lo que exponen los comandos coincidentes.
Posición en el flujo
SALIDA (Fase B — terminal). Pipeline de renderizado de HTML a video MP4. Se activa solo cuando el usuario quiere explícitamente rasterizar una composición HTML a un archivo de video. Se ejecuta al final, después de que la autoría de la composición esté completa.
Condiciones de activación
Invoca este skill SOLO cuando la solicitud coincida con uno de:
- "renderizar este HTML como video" / "renderizar a MP4"
- "HTML a MP4" / "sitio web a video" / "página a video"
- "crear un video a partir de esta composición HTML"
- "rasterizar la composición a video"
- Mención explícita de Hyperframes /
hyperframes render/.hf.html
NO invocar en menciones genéricas de "animación", "movimiento", "reproducción de video" o "componente animado" — esos pertenecen a:
../amw-design-principles/starter-components/animations.html(línea de tiempo Stage + Sprite en navegador)../amw-pretext/(movimiento tipográfico —pretext-art/es un redireccionamiento obsoleto)- El pipeline propio del usuario
Prerrequisitos
-
runtime_binaries (prerrequisitos del sistema): Node.js >= 22, git
-
runtime_binaries (instalados por
/amw-init): Bun (gestor de paquetes de Hyperframes), FFmpeg. Chrome es gestionado por Hyperframes internamente mediantehyperframes browser ensure(usa Puppeteer +@puppeteer/browsersinternamente — NO Playwright). -
fuente externa:
../../external/hyperframes/— el monorepo Hyperframes clonado desdehttps://github.com/heygen-com/hyperframes. Fijar a v0.4.30 o posterior para soporte deinspect,--hdrydata-variable-values. Si la carpeta no existe,/amw-inito este skill DEBEN clonarla antes de continuar:git clone --branch v0.4.30 --depth 1 https://github.com/heygen-com/hyperframes.git external/hyperframes cd external/hyperframes && bun install
Contrato de entrada
El puente acepta dos entradas mutuamente excluyentes. Proporciona exactamente una:
| Campo | Tipo | Descripción |
|---|---|---|
html_scene_path | string (opcional) | Ruta absoluta a un único archivo HTML. El puente crea un directorio de proyecto hyperframes temporal mediante mktemp -d -t hf-XXXXXX (portátil POSIX), escribe el HTML como index.html, renderiza y luego limpia después de escribir el informe. |
project_dir | string (opcional) | Ruta absoluta a un directorio de proyecto hyperframes preexistente (contiene index.html y opcionalmente compositions/, assets/). El puente hace cd directamente en él — sin andamiaje. Soporta subcomposiciones, audio y assets externos. |
Si se proporcionan ambos, project_dir gana. Si no se proporciona ninguno, fallar inmediatamente.
Patrón de invocación
-
Verificar repositorio externo — dos comprobaciones requeridas:
# Comprobación 1 — package.json presente (monorepo clonado) test -f "external/hyperframes/package.json" || exit-fail "monorepo no encontrado" # Comprobación 2 — CLI responde (instalación funcional) # @hyperframes/cli NO está publicado en npm — debe ejecutarse desde dentro del workspace del monorepo (cd external/hyperframes && npx hyperframes render --help) >/dev/null 2>&1 || exit-fail "CLI de hyperframes no funcional — ejecuta bun install dentro de external/hyperframes/"Si alguna comprobación falla, fallar rápidamente. No continuar.
-
Resolver el directorio del proyecto.
- Si se proporciona
project_dir: usarlo directamente. EstablecerHF_PROJ_DIR="$project_dir". - Si se proporciona
html_scene_path: crear un proyecto temporal:HF_PROJ_DIR="$(mktemp -d -t hf-XXXXXX)" cp "$html_scene_path" "$HF_PROJ_DIR/index.html" - De lo contrario: fallar inmediatamente.
- Si se proporciona
-
Ejecutar la secuencia de la puerta de pre-renderizado:
lint → validar → inspeccionar → renderizar.cd "$HF_PROJ_DIR" npx hyperframes lint npx hyperframes validate npx hyperframes inspect --json # abortar si hay errores (código de salida distinto de cero con --strict)Ver TECH-hyperframes-cli-lint, TECH-hyperframes-cli-validate, TECH-hyperframes-cli-inspect.
[TECH-hyperframes-cli-inspect.md] Qué hace · Cuándo usarlo · Cómo funciona · Banderas · Salida (modo JSON) · Ejemplo mínimo · Atributos de exclusión voluntaria · Errores comunes · Referencias cruzadas [TECH-hyperframes-cli-validate.md] Qué hace · Cuándo usarlo · Cómo funciona · Salida · Cuándo aparecen advertencias · Ejemplo mínimo · Errores comunes · Referencias cruzadas [TECH-hyperframes-cli-lint.md] Qué hace · Cuándo usarlo · Cómo funciona · Ejemplo mínimo · Errores comunes · Referencias cruzadas
Nota sobre la secuencia de la puerta: La secuencia del puente (
lint → validar → inspeccionar → renderizar) extiende intencionalmente la del upstream (lint → inspeccionar → previsualización → renderizar— ver el SKILL.md de la CLI de Hyperframes dentro del monorepoexternal/hyperframes/) añadiendovalidarpara pipelines de Fase B no supervisados y eliminandoprevisualización(un primitivo del bucle de desarrollo).
- Renderizar. Desde dentro del directorio del proyecto resuelto:
Banderas adicionales según sea necesario (cd "$HF_PROJ_DIR" npx hyperframes render --output <ruta-absoluta-mp4>--fps,--quality,--format,--hdr, etc.) — ver TECH-hyperframes-cli-render.
[TECH-hyperframes-cli-render.md] Qué hace · Cuándo usarlo · Cómo funciona · Banderas · Guía de calidad · Video transparente · Ejemplo mínimo · Ajuste de workers · Errores comunes · Referencias cruzadas
- Devolver la ruta del MP4 al llamante. Si el directorio del proyecto fue un andamiaje temporal (ruta
html_scene_path), eliminarlo después de escribir el informe.
Reglas de composición HTML (específicas de Hyperframes)
Las composiciones usan HTML plano con atributos de línea de tiempo data-* en una raíz #stage y sus hijos (pistas / clips / superposiciones). Este es el mismo modelo mental Stage + Sprite que ../amw-design-principles/starter-components/animations.html — Hyperframes lo extiende con mezcla de audio/video multipista y render determinista fuera de pantalla.
Atributos clave (el esquema autorizado vive en external/hyperframes/packages/core/ una vez clonado):
data-composition-id— identificador a nivel de stagedata-start,data-duration— segundos, por clipdata-track-index— orden de capas (pistas de video / superposición / audio)data-width,data-height— dimensiones del lienzo a nivel de stage
NO introduzcas Framer Motion, GSAP-como-dependencia, ni ningún runtime de animación de terceros en el puente. Hyperframes tiene su propio patrón Frame Adapter; si el usuario quiere GSAP dentro de una composición, eso es responsabilidad de Hyperframes, no del puente.
Referencias
Índice completo de referencias: INDEX.md — 32 archivos TECH-*.md agrupados por pipeline de Captura (7 pasos), comandos CLI (12), Autoría de composiciones (7), Registro (4). Cada archivo tiene su propia Tabla de Contenidos; carga solo el que necesites.
Ejemplos
Ver los ejemplos trabajados en los archivos de referencia por paso bajo ./references/TECH-hyperframes-capture-step-*.md (pipeline de 7 pasos de sitio web a video) y la guía de autoría de composiciones en TECH-hyperframes-composition-core.
[TECH-hyperframes-composition-core.md] Qué hace · Cuándo usarlo · Cómo funciona · Enfoque (orden narrativo) · Esqueleto de un solo archivo · Puerta de Identidad Visual (OBLIGATORIO — antes de escribir HTML) · Errores comunes · Referencias cruzadas
Salida
Un archivo de video MP4 renderizado más un informe de finalización del trabajo. El MP4 es producido por npx hyperframes render --output <mp4> desde el directorio del proyecto resuelto; el puente confirma que el archivo existe y no está vacío antes de informar éxito. Contrato completo a continuación.
Lista de verificación de salida y finalización
El contrato completo de salida (reglas de inferencia de ruta de artefactos, forma del informe de finalización del trabajo, lista de verificación obligatoria) vive en TECH-output-contract. Dos salidas son obligatorias:
- Artefactos — carpeta del proyecto hyperframes + MP4 renderizado. La ruta se infiere del proyecto (ruta de usuario → convención del framework →
./design/<subtipo>/→ respaldo./design/videos/). - Informe de finalización del trabajo en
$MAIN_ROOT/reports/webdesigner/<ts±tz>-amw-video-producer-<slug>-<hash-8-caracteres>.mdlistando cada artefacto + el veredicto de la lista de verificación por elemento.
Antes de reportar como completo: cada elemento de la lista de verificación en TECH-output-contract DEBE ser PASS o N/A. Cualquier FAIL desencadena un bucle de corrección.
Recursos
../amw-design-principles/starter-components/animations.html— el motor de línea de tiempo Stage + Sprite de ~50 LOC usado para previsualizaciones en navegador; Hyperframes comparte el mismo ritmo.../../bin/amw-html-export.py— NO es un sustituto.html-exportrenderiza un solo fotograma a PNG/PDF; Hyperframes renderiza un MP4 multifotograma usando Puppeteer + Chrome (gestionado porhyperframes browser ensure) + FFmpeg.../amw-dev-browser/— NO es un sustituto.dev-browseres para entrada/automatización; Hyperframes es el rasterizador de salida./amw-init— instala Bun, FFmpeg y clonaexternal/hyperframes/en el primer uso. Chrome para renderizado es aprovisionado por Hyperframes mismo mediantehyperframes browser ensure.- Repositorio externo:
https://github.com/heygen-com/hyperframes
No negociables
- Usar el monorepo externo mediante shell-out. NO reimplementar su pipeline dentro del plugin.
- NO incluir el código fuente de Hyperframes en
skills/— 500+ archivos es un ámbito incorrecto para un skill. - NO sustituir
dev-browserpor Hyperframes — resuelven problemas opuestos (entrada vs. salida). - NO sustituir
html-export.py— PNG de un solo fotograma no es video. - El usuario DEBE ejecutar
/amw-initantes del primer uso para instalar Bun + FFmpeg y clonar el repositorio externo. Chrome se aprovisiona ejecutando(cd external/hyperframes && npx hyperframes browser ensure)una vez después de la clonación.
Manejo de errores
Los modos de fallo comunes y los pasos de corrección viven en TECH-error-handling. Cubre: repositorio externo faltante, aprovisionamiento de Bun / FFmpeg / Chrome, errores de análisis de atributos HTML, fallos de codificación de video, clones obsoletos.