Communitygithub.com

Emasoft/ai-maestro-webdesign

Composición HTML a renderizado de video MP4 mediante el monorepo externo Hyperframes. Se activa con 'render HTML as video', 'HTML to MP4', 'website to video', 'create video from HTML', 'rasterize composition to mp4'. NO se activa con términos genéricos como 'animation' / 'video' — esos van a pretext o al pipeline del usuario. Úsalo cuando quieras renderizar HTML a MP4 a través de Hyperframes. Actívalo con 'render HTML as video' o 'HTML to MP4'.

¿Qué es ai-maestro-webdesign?

Este skill, **Hyperframes Bridge**, es un envoltorio externo que permite renderizar composiciones HTML a video MP4 mediante el monorepo Hyperframes (alojado en `external/hyperframes/`). Su función principal es ejecutar un pipeline de pre-renderizado (lint → validar → inspeccionar → renderizar) antes de llamar a `npx hyperframes render --output <mp4>`, asegurando que la composición pase todas las verificaciones de calidad. Está diseñado para ser autónomo y auto-contenido, pudiendo ser utilizado por cualquier agente (principal, sub-agente u orquestador externo) que lea este SKILL.md. Se activa únicamente cuando el usuario solicita explícitamente convertir HTML a MP4, y no interfiere con otros flujos de animación o video. Requiere Node.js >= 22, git, Bun y FFmpeg como prerrequisitos, y Chrome es gestionado internamente por Hyperframes. El skill acepta como entrada un archivo HTML individual o un directorio de proyecto Hyperframes completo, y devuelve la ruta del MP4 generado junto con un informe de finalización.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Emasoft/ai-maestro-webdesign/tree/HEAD/skills/amw-hyperframes-bridge

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Hyperframes Bridge

Orquestado por: SKILL. Envoltorio de dependencia externa. El monorepo real de Hyperframes vive en ../../external/hyperframes/ (clonado por /amw-init paso 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

  1. Verificar el repositorio externo con dos comprobaciones: debe existir external/hyperframes/package.json, y npx hyperframes render --help debe responder; fallar rápidamente si alguna comprobación falla.
  2. Resolver el directorio del proyecto: usar project_dir si se proporciona, o crear un proyecto temporal a partir de html_scene_path; fallar inmediatamente si no se proporciona ninguno.
  3. 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).
  4. Ejecutar cd "$HF_PROJ_DIR" && npx hyperframes render --output <mp4>; recolectar la ruta de salida.
  5. Confirmar que el archivo MP4 existe y no está vacío; informar la ruta de salida y cualquier advertencia de inspeccionar.
  6. Consultar la sección ## Patrón de invocación má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 mediante hyperframes browser ensure (usa Puppeteer + @puppeteer/browsers internamente — NO Playwright).

  • fuente externa: ../../external/hyperframes/ — el monorepo Hyperframes clonado desde https://github.com/heygen-com/hyperframes. Fijar a v0.4.30 o posterior para soporte de inspect, --hdr y data-variable-values. Si la carpeta no existe, /amw-init o 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:

CampoTipoDescripción
html_scene_pathstring (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_dirstring (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

  1. 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.

  2. Resolver el directorio del proyecto.

    • Si se proporciona project_dir: usarlo directamente. Establecer HF_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.
  3. 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 monorepo external/hyperframes/) añadiendo validar para pipelines de Fase B no supervisados y eliminando previsualización (un primitivo del bucle de desarrollo).

  1. Renderizar. Desde dentro del directorio del proyecto resuelto:
    cd "$HF_PROJ_DIR"
    npx hyperframes render --output <ruta-absoluta-mp4>
    
    Banderas adicionales según sea necesario (--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

  1. 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 stage
  • data-start, data-duration — segundos, por clip
  • data-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:

  1. 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/).
  2. Informe de finalización del trabajo en $MAIN_ROOT/reports/webdesigner/<ts±tz>-amw-video-producer-<slug>-<hash-8-caracteres>.md listando 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-export renderiza un solo fotograma a PNG/PDF; Hyperframes renderiza un MP4 multifotograma usando Puppeteer + Chrome (gestionado por hyperframes browser ensure) + FFmpeg.
  • ../amw-dev-browser/ — NO es un sustituto. dev-browser es para entrada/automatización; Hyperframes es el rasterizador de salida.
  • /amw-init — instala Bun, FFmpeg y clona external/hyperframes/ en el primer uso. Chrome para renderizado es aprovisionado por Hyperframes mismo mediante hyperframes 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-browser por 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-init antes 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.

Skills relacionados