Communitygithub.com

Emasoft/ai-maestro-webdesign

Composição HTML para renderização de vídeo MP4 via o monorepo externo Hyperframes. Aciona em 'renderizar HTML como vídeo', 'HTML para MP4', 'site para vídeo', 'criar vídeo a partir de HTML', 'rasterizar composição para MP4'. NÃO aciona em 'animação' ou 'vídeo' genéricos — estes vão para pretext ou pipeline do usuário. Use ao renderizar HTML para MP4 via Hyperframes. Acione com 'renderizar HTML como vídeo' ou 'HTML para MP4'.

O que é ai-maestro-webdesign?

Esta skill fornece uma ponte para o monorepo Hyperframes (https://github.com/heygen-com/hyperframes), permitindo que qualquer agente (agente principal, subagente ou orquestrador externo) renderize composições HTML para vídeo MP4 sem reimplementar o pipeline do Hyperframes. Ela aceita como entrada um único arquivo HTML (scene) ou um diretório de projeto Hyperframes completo, executa uma sequência de pré-renderização obrigatória (lint → validate → inspect → render) e, em seguida, chama `npx hyperframes render --output <mp4>` para produzir o vídeo final. A skill é autônoma e independente: não requer comandos de barra dedicados, sendo invocada pelo orquestrador `design-principles` (ou manualmente lendo este SKILL.md) na Fase B do pipeline, quando o design aprovado exige saída de vídeo. Ela é útil para desenvolvedores e agentes de IA que precisam converter rapidamente composições HTML em vídeos MP4 de alta qualidade, aproveitando o pipeline robusto do Hyperframes (com Puppeteer, Chrome e FFmpeg) sem se preocupar com a instalação ou configuração complexa. A skill trata de pré-requisitos como Node.js >= 22, Bun, FFmpeg e clonagem do repositório externo, e garante que o arquivo MP4 gerado exista e não esteja vazio antes de relatar sucesso.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Ponte Hyperframes

Orquestrado por: SKILL. Wrapper de dependência externa. O monorepo Hyperframes real reside em ../../external/hyperframes/ (clonado por /amw-init passo 6 se o usuário optar, OU por esta skill na primeira renderização como fallback). Esta skill documenta o padrão de shell-out; ela NÃO contém o monorepo.

Visão Geral

Renderiza composições HTML para vídeo MP4 por meio de shell-out para o monorepo Hyperframes (external/hyperframes/). Aceita um único arquivo HTML de cena ou um diretório de projeto Hyperframes completo. Executa a sequência de pré-renderização obrigatória (lint → validate → inspect → render) antes de chamar npx hyperframes render --output <mp4>. Retorna o caminho do MP4 e um relatório de conclusão do job. Nenhuma reimplementação do pipeline Hyperframes dentro do plugin — apenas shell-out.

Instruções

  1. Verifique o repositório externo com duas verificações: external/hyperframes/package.json deve existir, e npx hyperframes render --help deve responder; falhe rapidamente se qualquer verificação falhar.
  2. Resolva o diretório do projeto: use project_dir se fornecido, ou crie um projeto temporário a partir de html_scene_path; falhe imediatamente se nenhum for fornecido.
  3. Execute a sequência de pré-renderização na ordem: lint → validate → inspect → render (aborte se qualquer etapa retornar código não-zero).
  4. Execute cd "$HF_PROJ_DIR" && npx hyperframes render --output <mp4>; colete o caminho de saída.
  5. Confirme que o arquivo MP4 existe e não está vazio; relate o caminho de saída e quaisquer avisos do inspect.
  6. Consulte a seção ## Padrão de invocação abaixo para as etapas de execução autoritativas.

Ativação

Nenhum comando de barra dedicado — esta skill não possui atalho /amw-* correspondente. Invocada pelo orquestrador design-principles como a etapa final da Fase B no modo Agente Principal quando o design aprovado requer saída de vídeo MP4. O orquestrador pode aplicar o pipeline completo de shell-out Hyperframes e as técnicas de composição desta skill sem restrições de camada de comando.

Esta skill é autônoma e autocontida — qualquer agente (o agente principal, um subagente ou um orquestrador externo) pode usá-la lendo este SKILL.md e suas referências. As técnicas da skill NÃO são limitadas ao que os comandos correspondentes expõem.

Posição no fluxo

SAÍDA (Fase B — terminal). Pipeline de renderização de HTML para vídeo MP4. Acionada somente quando o usuário explicitamente deseja uma composição HTML rasterizada em um arquivo de vídeo. Executa por último, após a conclusão da autoria da composição.

Condições de acionamento

Invoque esta skill SOMENTE quando a solicitação corresponder a uma destas:

  • "renderizar este HTML como vídeo" / "renderizar para MP4"
  • "HTML para MP4" / "site para vídeo" / "página para vídeo"
  • "criar um vídeo a partir desta composição HTML"
  • "rasterizar a composição para vídeo"
  • Menção explícita de Hyperframes / hyperframes render / .hf.html

NÃO invoque em menções genéricas de "animação", "movimento", "reprodução de vídeo" ou "componente animado" — estes pertencem a:

  • ../amw-design-principles/starter-components/animations.html (linha do tempo Stage + Sprite no navegador)
  • ../amw-pretext/ (movimento tipográfico — pretext-art/ é um redirecionamento obsoleto)
  • O próprio pipeline do usuário

Pré-requisitos

  • runtime_binaries (pré-requisitos do sistema): Node.js >= 22, git

  • runtime_binaries (instalados por /amw-init): Bun (gerenciador de pacotes do Hyperframes), FFmpeg. O Chrome é gerenciado pelo próprio Hyperframes via hyperframes browser ensure (usa Puppeteer + @puppeteer/browsers internamente — NÃO Playwright).

  • fonte externa: ../../external/hyperframes/ — o monorepo Hyperframes clonado de https://github.com/heygen-com/hyperframes. Fixe na v0.4.30 ou posterior para suporte a inspect, --hdr e data-variable-values. Se a pasta não existir, /amw-init ou esta skill DEVE cloná-la antes de prosseguir:

    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

A ponte aceita duas entradas mutuamente exclusivas. Forneça exatamente uma:

CampoTipoDescrição
html_scene_pathstring (opcional)Caminho absoluto para um único arquivo HTML. A ponte cria um diretório temporário de projeto hyperframes via mktemp -d -t hf-XXXXXX (portável POSIX), escreve o HTML como index.html, renderiza e limpa após o relatório ser escrito.
project_dirstring (opcional)Caminho absoluto para um diretório de projeto hyperframes pré-existente (contém index.html e opcionalmente compositions/, assets/). A ponte cd diretamente para ele — sem scaffolding. Suporta sub-composições, áudio e ativos externos.

Se ambos forem fornecidos, project_dir vence. Se nenhum for fornecido, falhe imediatamente.

Padrão de invocação

  1. Verificar repositório externo — duas verificações necessárias:

    # Verificação 1 — package.json presente (monorepo clonado)
    test -f "external/hyperframes/package.json" || exit-fail "monorepo não encontrado"
    # Verificação 2 — CLI responde (instalação funcional)
    # @hyperframes/cli NÃO está publicado no npm — deve executar de dentro do workspace do monorepo
    (cd external/hyperframes && npx hyperframes render --help) >/dev/null 2>&1 || exit-fail "CLI hyperframes não funcional — execute bun install dentro de external/hyperframes/"
    

    Se qualquer verificação falhar, falhe rapidamente. Não prossiga.

  2. Resolver o diretório do projeto.

    • Se project_dir for fornecido: use diretamente. Defina HF_PROJ_DIR="$project_dir".
    • Se html_scene_path for fornecido: crie um projeto temporário:
      HF_PROJ_DIR="$(mktemp -d -t hf-XXXXXX)"
      cp "$html_scene_path" "$HF_PROJ_DIR/index.html"
      
    • Caso contrário: falhe imediatamente.
  3. Executar a sequência de pré-renderização: lint → validate → inspect → render.

    cd "$HF_PROJ_DIR"
    npx hyperframes lint
    npx hyperframes validate
    npx hyperframes inspect --json  # aborte se houver erros (saída não-zero com --strict)
    

    Consulte TECH-hyperframes-cli-lint, TECH-hyperframes-cli-validate, TECH-hyperframes-cli-inspect.

[TECH-hyperframes-cli-inspect.md] O que faz · Quando usar · Como funciona · Flags · Saída (modo JSON) · Exemplo mínimo · Atributos de exclusão · Armadilhas · Referências cruzadas [TECH-hyperframes-cli-validate.md] O que faz · Quando usar · Como funciona · Saída · Quando avisos aparecem · Exemplo mínimo · Armadilhas · Referências cruzadas [TECH-hyperframes-cli-lint.md] O que faz · Quando usar · Como funciona · Exemplo mínimo · Armadilhas · Referências cruzadas

Nota sobre a sequência: A sequência da ponte (lint → validate → inspect → render) intencionalmente estende a sequência upstream (lint → inspect → preview → render — veja o SKILL.md da CLI Hyperframes dentro do monorepo vendido external/hyperframes/) adicionando validate para pipelines não supervisionados da Fase B e removendo preview (uma primitiva do ciclo de desenvolvimento).

  1. Renderizar. De dentro do diretório do projeto resolvido:
    cd "$HF_PROJ_DIR"
    npx hyperframes render --output <caminho-absoluto-mp4>
    
    Flags adicionais conforme necessário (--fps, --quality, --format, --hdr, etc.) — consulte TECH-hyperframes-cli-render.

[TECH-hyperframes-cli-render.md] O que faz · Quando usar · Como funciona · Flags · Orientação de qualidade · Vídeo transparente · Exemplo mínimo · Ajuste de workers · Armadilhas · Referências cruzadas

  1. Retornar o caminho do MP4 para o chamador. Se o diretório do projeto foi um scaffold temporário (caminho html_scene_path), remova-o após o relatório ser escrito.

Regras de composição HTML (específicas do Hyperframes)

As composições usam HTML simples com atributos de linha do tempo data-* em uma raiz #stage e seus filhos (faixas / clipes / sobreposições). Este é o mesmo modelo mental Stage + Sprite de ../amw-design-principles/starter-components/animations.html — o Hyperframes o estende com mixagem de áudio/vídeo multi-faixa e renderização determinística fora da tela.

Atributos principais (o esquema autoritativo reside em external/hyperframes/packages/core/ uma vez clonado):

  • data-composition-id — identificador no nível do stage
  • data-start, data-duration — segundos, por clipe
  • data-track-index — ordenação de camadas (faixas de vídeo / sobreposição / áudio)
  • data-width, data-height — dimensões do canvas no nível do stage

NÃO introduza Framer Motion, GSAP como dependência ou qualquer runtime de animação de terceiros na ponte. Hyperframes tem seu próprio padrão Frame Adapter; se o usuário quiser GSAP dentro de uma composição, isso é responsabilidade do Hyperframes, não da ponte.

Referências

Índice completo de referências: INDEX.md — 32 arquivos TECH-*.md agrupados por pipeline Capture (7 etapas), comandos CLI (12), autoria de composição (7), Registry (4). Cada arquivo tem seu próprio Índice; carregue apenas o que precisar.

Exemplos

Consulte os exemplos práticos nos arquivos de referência por etapa em ./references/TECH-hyperframes-capture-step-*.md (pipeline de site-para-vídeo de 7 etapas) e o guia de autoria de composição em TECH-hyperframes-composition-core.

[TECH-hyperframes-composition-core.md] O que faz · Quando usar · Como funciona · Abordagem (ordem narrativa) · Esqueleto de arquivo único · Portão de Identidade Visual (OBRIGATÓRIO — antes de escrever HTML) · Armadilhas · Referências cruzadas

Saída

Um arquivo de vídeo MP4 renderizado mais um relatório de conclusão do job. O MP4 é produzido por npx hyperframes render --output <mp4> a partir do diretório do projeto resolvido; a ponte confirma que o arquivo existe e não está vazio antes de relatar sucesso. Contrato completo abaixo.

Saída e lista de verificação de conclusão

O contrato completo de saída (regras de inferência de caminho de artefato, formato do relatório de conclusão do job, lista de verificação obrigatória) reside em TECH-output-contract. Duas saídas são obrigatórias:

  1. Artefatos — pasta do projeto hyperframes + MP4 renderizado. O caminho é inferido do projeto (caminho do usuário → convenção do framework → ./design/<subtipo>/ → fallback ./design/videos/).
  2. Relatório de conclusão do job em $MAIN_ROOT/reports/webdesigner/<ts±tz>-amw-video-producer-<slug>-<8-char-hash>.md listando cada artefato + o veredito da lista de verificação por item.

Antes de relatar conclusão: cada item da lista de verificação em TECH-output-contract DEVE ser PASS ou N/A. Qualquer FAIL aciona um loop de remediação.

Recursos

  • ../amw-design-principles/starter-components/animations.html — o motor de linha do tempo Stage + Sprite de ~50 linhas usado para prévias no navegador; Hyperframes compartilha o mesmo ritmo.
  • ../../bin/amw-html-export.py — NÃO é um substituto. html-export renderiza um único quadro para PNG/PDF; Hyperframes renderiza um MP4 multi-quadro usando Puppeteer + Chrome (gerenciado por hyperframes browser ensure) + FFmpeg.
  • ../amw-dev-browser/ — NÃO é um substituto. dev-browser é para entrada/automação; Hyperframes é o rasterizador de saída.
  • /amw-init — instala Bun, FFmpeg e clona external/hyperframes/ no primeiro uso. O Chrome para renderização é provisionado pelo próprio Hyperframes via hyperframes browser ensure.
  • Repositório externo: https://github.com/heygen-com/hyperframes

Inegociáveis

  • Use o monorepo externo via shell-out. NÃO reimplemente seu pipeline dentro do plugin.
  • NÃO coloque o código-fonte do Hyperframes em skills/ — 500+ arquivos é escopo errado para uma skill.
  • NÃO substitua dev-browser pelo Hyperframes — eles resolvem problemas opostos (entrada vs. saída).
  • NÃO substitua html-export.py — PNG de quadro único não é vídeo.
  • O usuário DEVE executar /amw-init antes do primeiro uso para instalar Bun + FFmpeg e clonar o repositório externo. O Chrome é provisionado executando (cd external/hyperframes && npx hyperframes browser ensure) uma vez após a clonagem.

Tratamento de Erros

Modos de falha comuns e etapas de remediação residem em TECH-error-handling. Abrange: repositório externo ausente, provisionamento de Bun / FFmpeg / Chrome, erros de análise de atributos HTML, falhas de codificação de vídeo, clones desatualizados.

Habilidades Relacionadas