Protocolo de Promo Motion
Visão Geral
Esta skill renderiza um vídeo promocional dinâmico de nível profissional de um produto real, não uma gravação de tela nem uma maquete. Ela controla o aplicativo real em um navegador headless contra um ambiente de demonstração, captura imagens nítidas de cada tela e compõe uma edição de motion design sobre elas: tipografia cinética, close-ups cinematográficos, destaques spotlight que acompanham o zoom, molduras de telefone para telas mobile, cortes de cena rítmicos e uma trilha sonora. A saída é um mestre 16:9 e um corte vertical 9:16.
É a contraparte de renderização de launch-feature: launch-feature escreve um video-script.md (o roteiro/momentos em prosa); motion-promo transforma uma lista de momentos no vídeo finalizado e com trilha sonora. Quando ambos são executados, encadeie-os — script de launch-feature → momentos de motion-promo.
Por que HyperFrames (HTML→MP4) e não gravação de tela: determinístico, reexecutável, controlável pela marca e evita os modos de falha da captura de navegação ao vivo (consulte Regras). O aplicativo é usado apenas para produzir imagens + tokens de design; todo o movimento é criado.
Quando Usar
- Uma página de destino / de vendas precisa de uma demonstração do produto ou de um vídeo herói.
- Anunciar um recurso e você quer o vídeo renderizado, não apenas o script.
- Você tem um locatário de demonstração/sandbox com dados minimamente realistas para mostrar.
Não usar para: tutoriais internos onde a fidelidade não importa (uma captura de tela bruta é mais barata) ou aplicativos sem um ambiente de demonstração executável.
Pré-requisitos e segredos
Nenhuma chave de API / segredo é necessária. A renderização do HyperFrames é sem chave (HTML local→MP4), e as fontes (Google Fonts) + a música padrão (incompetech) são URLs públicas. A única credencial é o login de demonstração do aplicativo alvo, que reside no promo.config.mjs do repositório alvo — nunca nesta skill. A autenticação é uma receita conectável: authInject() retorna valores a serem injetados (token no localStorage, cookie, chave de API, seleção de locatário em várias etapas), ou authFlow(page) DIRIGE uma interface de login interativa (Azure AD / Entra, Okta, Google SSO) e o mecanismo captura o estado da sessão (localStorage + sessionStorage + cookies, incluindo HttpOnly). As credenciais SSO vêm do ambiente, não do arquivo. Headless não pode passar por MFA interativa — use uma conta de demonstração isenta de MFA (exceção de Acesso Condicional) ou uma senha de aplicativo.
Dependências do sistema (você as instala — a skill não pode): Node 20+, Chrome do sistema (google-chrome/Chromium), ffmpeg + ffprobe. Saída de rede para fontes/música.
Dependências automáticas/sob demanda: hyperframes é obtido sob demanda via npx (sem pré-instalação). puppeteer-core é uma dependência npm scaffolding — ele usa o Chrome do sistema e não baixa um Chromium.
Configuração: scaffolding dos templates/ em video/<slug>/ (inclui hyperframes.json; meta.json é gerado pelo compose-gen), renomeie gitignore → .gitignore, depois npm install e npm run preflight (verifica Chrome, ffmpeg/ffprobe e puppeteer-core; falha ruidosamente se algum estiver faltando). Execute o pipeline passo a passo ou npm run build.
- Uma demonstração/sandbox executável do aplicativo alvo.
Entradas
Tudo específico do projeto reside no repositório alvo, nunca nesta skill:
promo.config.mjs— o contrato (consultetemplates/promo.config.example.mjs). URL do app / como servir, receita de autenticação, conta/locatário de demonstração, caminhos de saída e preferência de música. Os tokens de design são extraídos automaticamente (etapa 2), mas podem ser substituídos aqui.beats.json— a lista ordenada de tomadas (consultetemplates/beats.schema.json). Cada batida = uma tela (rota ou imagem capturada) + destino de destaque opcional + texto de chamada + viewport (desktop/mobile).
Faça scaffolding de ambos em video/<slug>/ no repositório alvo a partir de templates/.
Protocolo
Trabalhe dentro de video/<slug>/ no repositório alvo. Cada etapa tem uma verificação.
0. Cure os dados de demonstração (faça isso primeiro — isso faz ou quebra o vídeo)
Os dados de demonstração/sandbox geralmente estão desatualizados ou zerados para o período atual (faturas não pagas do mês corrente, funis vazios), o que aparece como "R$ 0 de receita" ao lado de "no piloto automático" — ativamente fora da mensagem. Antes de capturar, escreva uma semente idempotente relativa à data atual que forneça números saudáveis para cada momento (consulte Regras → Dados de demonstração zerados). Verifique consultando as métricas que cada momento mostrará.
1. Sirva o aplicativo contra a API de demonstração, em uma origem com CORS permitido
Construa/sirva o aplicativo apontando para a API de demonstração. A origem de serviço deve estar na lista de permissões CORS da API ou cada busca de dados será bloqueada e as telas renderizarão vazias (consulte Regras → Origem CORS). Investigue a lista de permissões da API e sirva em uma porta permitida. Verifique: uma rota profunda retorna 200 e uma requisição autenticada /api/... dessa origem retorna 2xx.
2. Extraia o sistema de design do aplicativo alvo
Execute templates/engine/extract-design.mjs contra o aplicativo autenticado e servido. Ele amostra estilos computados (fundo da página, cor primária/destaque de botões/links, famílias de fontes de título e mono, raio) → design.tokens.json. Esses alimentam a composição como variáveis CSS para que as sobreposições cinéticas, destaque e fontes correspondam automaticamente à marca do aplicativo. Revise + substitua em promo.config se um token amostrado estiver errado.
3. Capture imagens limpas por momento
Execute templates/engine/capture.mjs. Ele autentica (via a receita authInject da configuração), navega para a rota de cada momento em seu viewport, aguarda o carregamento de dados reais (não apenas network-idle — consulte Regras) e tira screenshots para assets/<beat>.png. Verifique se cada imagem mostra conteúdo carregado (tamanho > ~10 KB, verifique se o elemento alvo está presente).
4. Defina os momentos + gere a composição
Preencha beats.json (rota/imagem, destaque {x,y,w,h,label} no espaço de pixels da imagem — ou {selector,label,padding?}, medido automaticamente pelo capture.mjs e preferido em relação a coordenadas ajustadas manualmente, chamada {kicker,headline,sub}, viewport, durações). Execute templates/engine/compose-gen.mjs → index.html a partir de templates/composition.html, injetando tokens + momentos. Mantenha impactante: 3–5 s por momento, cortes secos, uma ideia por momento.
5. Obtenha uma faixa de música gratuita
Execute templates/engine/fetch-music.mjs → assets/music.mp3. A fonte padrão é CC-BY (incompetech); CC-BY requer atribuição (registre-a para a descrição do LP). Prefira uma faixa fornecida pelo projeto/CC0 quando disponível.
6. Renderize
npx hyperframes render → MP4 silencioso. Execute hyperframes lint/inspect primeiro; trate o estouro decorativo/de animação de saída fora da tela como ruído, o recorte de texto real como uma correção.
7. Revise os quadros + corrija o alinhamento do destaque
Extraia quadros no início e no final de cada push-in e examine-os. O #1 defeito: o destaque spotlight se desvia do alvo durante o zoom — porque a caixa de destaque deve ser um filho do container escalado (consulte Regras → Rastreamento de destaque). Verifique também: sem telas vazias/loading, telas mobile posicionadas corretamente dentro da moldura do telefone, texto legível.
8. Multiplexe a música
Execute templates/engine/mux.mjs → MP4 final com trilha sonora (loudnorm, fade in/out, -shortest). Verifique se a saída possui um stream de áudio e corresponde à duração do vídeo.
9. Derive o corte 9:16
mux.mjs --reframe produz um corte 1080×1920. Não corte centralizado (corta chamadas ancoradas na parte inferior) — use uma letterbox desfocada que preserve todo o quadro; os momentos mobile já estão centralizados.
Regras (conquistadas com esforço — não as reaprenda)
- Rastreamento de destaque. Um retângulo spotlight/destaque sobre uma tela que faz push-in DEVE ser um filho do mesmo elemento que recebe a transformação
scale, no espaço de coordenadas de pixels da imagem. Como irmão, ele permanece fixo enquanto a imagem dá zoom e se desvia do alvo ao longo do plano. - Dados de demonstração zerados. O período atual geralmente não foi pago / está vazio. Cure-o com uma semente que seja idempotente (ids determinísticos, delete-then-insert) e relativa a
current_datepara que se auto-corrija a cada período. - Origem CORS. Uma compilação servida localmente chamando uma API de demonstração implantada é de origem cruzada. Sirva em uma origem que a API permite (investigue) — nunca desative a segurança do navegador para contornar isso.
- Aguarde dados reais.
networkidle2pode resolver antes da requisição de dados do aplicativo chegar → você captura um spinner. Aguarde adicionalmente por uma resposta/api/...bem-sucedida (ou pelo seletor de conteúdo alvo) antes de tirar o screenshot. - HyperFrames em vez de captura ao vivo. A transmissão CDP para de emitir quadros em uma página visualmente estática e roda abaixo do fps nominal; a criação em HTML (GSAP) evita ambos. Se você alguma vez precisar gravar ao vivo, agite o cursor e codifique no fps efetivo.
- Licenciamento de música. CC-BY (incompetech/Kevin MacLeod) precisa de atribuição na descrição do LP; CC0 (Pixabay etc.) não precisa. Nunca envie um clipe raspado sem licença em uma página publicada.
- Concatenar com o filtro, não com o demuxer se os segmentos tiverem fps variáveis — o demuxer descarta quadros silenciosamente.
Extração do sistema de design (branding agnóstico)
A composição é neutra em relação à marca; extract-design.mjs preenche suas variáveis CSS a partir do próprio aplicativo alvo: --bg (fundo do body), --accent (cor primária/link), --fg (cor do título), --font-hero/--font-mono (famílias de fontes computadas), --radius. Isso é o que faz uma única skill produzir vídeos promocionais alinhados à marca para qualquer aplicativo sem selecionar tokens manualmente. Sempre revise os tokens amostrados — uma cor de baixo contraste ou ad-hoc ocasionalmente amostra errado; substitua em promo.config.design.
Erros
- O aplicativo não autentica em headless → a receita
authInjectda configuração está errada; verifique se os tokens caem nolocalStorage/cookies antes da primeira navegação. - Telas renderizam vazias → Origem CORS (etapa 1) ou aguardar dados (Regra) perdido.
- Erros de renderização fora da tela → recorte de texto real precisa de fonte menor / quebra de linha; estouro decorativo/de saída é ruído.
- Destaque desalinhado → não é filho do container escalado (Regra).
Composição com o papel do profissional de marketing
Use o papel de profissional de marketing para o texto: chamadas, manchetes e o enquadramento de valor por momento devem seguir a voz do projeto (voice.md / marketer-hooks.md de launch-feature, quando presente). Mantenha o texto na tela em uma chamada + uma manchete curta + uma sub-linha por momento.