Ponte Hyperframes
Orquestrado por: SKILL. Wrapper de dependência externa. O monorepo Hyperframes real reside em
../../external/hyperframes/(clonado por/amw-initpasso 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
- Verifique o repositório externo com duas verificações:
external/hyperframes/package.jsondeve existir, enpx hyperframes render --helpdeve responder; falhe rapidamente se qualquer verificação falhar. - Resolva o diretório do projeto: use
project_dirse fornecido, ou crie um projeto temporário a partir dehtml_scene_path; falhe imediatamente se nenhum for fornecido. - Execute a sequência de pré-renderização na ordem:
lint → validate → inspect → render(aborte se qualquer etapa retornar código não-zero). - Execute
cd "$HF_PROJ_DIR" && npx hyperframes render --output <mp4>; colete o caminho de saída. - Confirme que o arquivo MP4 existe e não está vazio; relate o caminho de saída e quaisquer avisos do
inspect. - Consulte a seção
## Padrão de invocaçãoabaixo 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 viahyperframes browser ensure(usa Puppeteer +@puppeteer/browsersinternamente — NÃO Playwright). -
fonte externa:
../../external/hyperframes/— o monorepo Hyperframes clonado dehttps://github.com/heygen-com/hyperframes. Fixe na v0.4.30 ou posterior para suporte ainspect,--hdredata-variable-values. Se a pasta não existir,/amw-initou 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:
| Campo | Tipo | Descrição |
|---|---|---|
html_scene_path | string (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_dir | string (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
-
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.
-
Resolver o diretório do projeto.
- Se
project_dirfor fornecido: use diretamente. DefinaHF_PROJ_DIR="$project_dir". - Se
html_scene_pathfor 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.
- Se
-
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 vendidoexternal/hyperframes/) adicionandovalidatepara pipelines não supervisionados da Fase B e removendopreview(uma primitiva do ciclo de desenvolvimento).
- Renderizar. De dentro do diretório do projeto resolvido:
Flags adicionais conforme necessário (cd "$HF_PROJ_DIR" npx hyperframes render --output <caminho-absoluto-mp4>--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
- 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 stagedata-start,data-duration— segundos, por clipedata-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:
- 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/). - Relatório de conclusão do job em
$MAIN_ROOT/reports/webdesigner/<ts±tz>-amw-video-producer-<slug>-<8-char-hash>.mdlistando 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-exportrenderiza um único quadro para PNG/PDF; Hyperframes renderiza um MP4 multi-quadro usando Puppeteer + Chrome (gerenciado porhyperframes 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 clonaexternal/hyperframes/no primeiro uso. O Chrome para renderização é provisionado pelo próprio Hyperframes viahyperframes 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-browserpelo 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-initantes 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.