Ponto de entrada do HyperFrames
HyperFrames renderiza vídeo a partir de HTML — uma composição é um arquivo HTML cujo DOM declara temporização com atributos data-*, cuja runtime de animação é buscável e cuja reprodução de mídia é gerenciada pelo framework. O contrato completo de autoria está em /hyperframes-core; leia-o antes de escrever o HTML da composição.
1. Comece pelo estado do projeto
Aplique a primeira linha correspondente; não avalie linhas de estado inferiores:
| Estado | Ação |
|---|---|
| Port explícito de uma fonte Remotion existente para HyperFrames | Leia references/routes/remotion-to-hyperframes.md, depois roteie diretamente para esse workflow. Pule a camada de intenção. |
| Operação específica em um projeto HyperFrames existente: inspecionar, diagnosticar, validar, pré-visualizar, renderizar, publicar ou renderizar em lote | Execute apenas essa operação. Pule intenção e roteamento de workflow; carregue /hyperframes-cli e quaisquer habilidades de domínio necessárias. |
| Edição específica em um projeto existente | Faça a edição. Não execute a camada de intenção. |
BRIEF.md existe | Leia workflow e flow. Execute esse workflow; flow: companion sempre executa em /general-video. Não faça perguntas de briefing. |
Sem briefing, mas hyperframes.json ou STORYBOARD.md existe | Retome a partir dos arquivos do projeto e preferências registradas. Infira o workflow proprietário dos artefatos existentes. Se não puder ser determinado exclusivamente, faça uma única pergunta de roteamento; não execute a entrevista de intenção. |
| Criação nova | Execute a camada de intenção — references/intent-interview.md — depois roteie uma vez usando a tabela da § 2. |
Se uma solicitação nova não identificar o assunto ou a entrada, pergunte sobre o que é o vídeo antes de rotear. Verifique preferências e receitas antes de perguntar qualquer coisa (references/intent-interview.md, passo 1). Uma entrada figma.com ou uma receita nomeada altera a captação, não o roteamento — a seção "Adaptar entradas ortogonais" da entrevista lida com ambas.
Mantenha o CLI do projeto atualizado
Um projeto scaffolding fixa hyperframes@<versão> em seus scripts package.json para que as renderizações permaneçam reproduzíveis; o pino nunca avança sozinho, e uma execução fixada de um CLI antigo não imprime nenhum aviso sobre isso. Ao retomar um projeto cujos scripts carregam um pino, teste uma vez antes do primeiro comando que afeta a renderização:
npx hyperframes@latest upgrade --project . --check
O teste é somente leitura e relata o pino em relação à versão mais recente; mantenha o . explícito — em versões mais antigas do CLI, um --project solto seguido por outra flag consome essa flag como seu valor de diretório. Quando ele relatar que o projeto está desatualizado — ou qualquer saída do CLI já mostrar isso (o aviso em stderr This project pins hyperframes@… (latest …), ou _meta.updateAvailable: true em um resultado --json de um script fixado) — aplique com npx hyperframes@latest upgrade --project ., depois verifique com npx hyperframes check. Uma verificação bem-sucedida confirma que as composições do projeto ainda validam na nova versão — não que a saída renderizada seja idêntica quadro a quadro ao pino antigo — portanto, um aumento bem-sucedido nunca é silencioso: nomeie a versão antiga e a nova no resumo da execução. Um projeto sem composição ainda não precisa de verificação. Se a verificação falhar, reverta a alteração no package.json, continue na versão fixada e relate em qual versão o projeto permanece e por quê. Aja com base no sinal, em vez de retransmiti-lo ao usuário; nunca deixe um pino aumentado sem verificação.
2. Roteie a criação nova
Use a primeira linha correspondente. Corresponda à entrega solicitada, não a uma palavra ou tipo de arquivo mencionado de passagem.
| Prioridade | Solicitação | Workflow |
|---|---|---|
| 1 | Portar explicitamente uma fonte Remotion existente | /remotion-to-hyperframes |
| 2 | Criar uma apresentação, pitch deck ou deck interativo navegável | /slideshow |
| 3 | Adicionar legendas ou subtítulos simples a uma gravação existente de pessoa falando sem alterá-la | /embedded-captions |
| 4 | Adicionar sobreposições gráficas projetadas a uma gravação existente de pessoa falando, entrevista ou podcast sem alterar a gravação | /talking-head-recut |
| 5 | Construir um vídeo sincronizado com batida a partir de uma faixa de música, sem narração ou captura de site | /music-to-video |
| 6 | Criar uma unidade explicitamente curta, sem narração e focada em movimento, tipicamente com menos de 10s | /motion-graphics |
| 7 | Explicar um pull request do GitHub ou alteração de código a partir de uma referência de PR | /pr-to-video |
| 8 | Mercadologizar ou apresentar um site, site de produto, aplicativo ou empresa a partir de um URL ou briefing específico do site | /product-launch-video |
| 9 | Explicar um tópico, artigo ou anotações com visuais inventados e sem captura de produto ou site | /faceless-explainer |
| 10 | Qualquer outro vídeo ou composição personalizada | /general-video |
Antes de finalizar a rota, leia references/routes/<workflow>.md — um arquivo pequeno por rota: o contrato canônico de entrada/saída/gatilho (disponível antes das habilidades de workflow instaladas de forma lazy) mais a entrada de entrevista dessa rota. Se o candidato não atender ao seu contrato, continue roteando em vez de forçar a correspondência. Leia apenas o arquivo da rota correspondente.
Resolva ambiguidades comuns
- Um título animado curto, logotipo de abertura, número impactante, gráfico de mapa ou terço inferior independente é
/motion-graphicsquando não é narrado e o movimento é a mensagem. Um cartão de título estático, sequência narrada, montagem mais longa ou loop personalizado é/general-video. - Um motion graphic explicitamente curto pode usar um URL, tweet, artigo ou captura de tela como material de origem. Uma solicitação genérica "faça um vídeo a partir deste site" é
/product-launch-video. - Gravação existente com legendas roteia para
/embedded-captions; gravação com cartões de informação projetados roteia para/talking-head-recut. Re-temporizar, reordenar, recolorir, reenquadrar ou remixar a gravação é uma edição personalizada e cai em/general-video. - Um arquivo de música seleciona
/music-to-videoapenas quando sua grade de batidas impulsiona a peça. Música usada como fundo não substitui a rota correspondente ao assunto. - "Eu quero um storyboard" altera o processo de revisão, não o workflow. Sem outro sinal de roteamento, use
/general-video. Um storyboard esboçado confirmado pode ser a própria entrega solicitada; o loop de revisão define esse ponto de parada. - Workflows narrativos especializados suportam até cerca de 3 minutos e são mais fortes em torno de 30–90s. Roteie uma peça claramente mais longa para
/general-video. O comprimento nunca substitui um port explícito, deck, legenda, overlay ou entrega orientada por música.
3. Roteie uma vez, depois saia
Para criação nova, a camada de intenção (references/intent-interview.md) executa a conversa completa — memória, triagem, rodada de pitch, itens obrigatórios, formato da execução, passagem de bastão — e termina escrevendo BRIEF.md. O briefing é o único artefato de roteamento que o workflow lê; nada posterior reabre este skill ou a entrevista. Responda a qualquer pergunta posterior sobre "o que a rota exigiu?" a partir de BRIEF.md.
4. Instale e entre no workflow
Antes de ler o workflow selecionado, instale ou atualize-o juntamente com as habilidades de domínio principais:
npx hyperframes skills update <nome-do-workflow>
Use o nome simples sem /. Se o comando falhar, exiba o erro; não reconstrua o workflow de memória. Todo o resto sobre instalação — a divisão entre habilidades principais e lazy, o que init atualiza, diagnóstico, exclusão de CI e fallback sem CLI — está em references/skill-lifecycle.md.
5. Carregue habilidades de domínio sob demanda
| Necessidade | Habilidade |
|---|---|
| Estrutura da composição, atributos de temporização, faixas, variáveis, determinismo | /hyperframes-core |
| Regras de movimento, blueprints de cena, transições, adaptadores de runtime | /hyperframes-animation |
GSAP seguro para busca, CSS, Anime.js, WAAPI, FLIP, caminhos, máscaras, SVG, keyframes 3D ou diagnóstico hyperframes keyframes | /hyperframes-keyframes |
| Especificações de design, conceito, paleta, tipografia, narração, planejamento de batida | /hyperframes-creative |
| Imagens, ícones, logotipos, áudio, legendas, gradações, LUTs, mídia reutilizável | /media-use |
| Corte de locução, cadeias de efeitos de áudio ou envelopes de automação em uma faixa | /hyperframes-audio |
| Init, lint, check, snapshots, compare, renderização em lote, Studio, renderizar, publicar ou diagnóstico | /hyperframes-cli |
| Blocos e componentes do registro | /hyperframes-registry |
| Ativos, tokens, componentes ou quadros de storyboard do Figma como movimento reconstruído | /figma |
Feedback geral sobre como a mídia fotográfica parece ou se comporta também roteia para
/media-use, mesmo quando o usuário nunca diz "correção de cor" ou "efeito": corrija
gravação escura/plana/entediante, estilize um clipe, esconda um rosto ou melhore uma revelação
de mídia. Leia ../media-use/references/media-treatments.md antes de editar um
tratamento; ele rege como a gravação é tratada, nunca se a mídia pode ser usada.
Não substitua um LUT genérico, filtro/sobreposição CSS ou interpolação de opacidade por um
primitivo de tratamento canônico existente. Mantenha edições apenas de texto/layout/movimento em
seu domínio proprietário.
Durante uma construção com mídia fotográfica importante, inclua uma varredura fundamentada
de polimento de mídia na passagem de qualidade final; deixar mídia adequada inalterada é
um resultado válido.
Habilidades de domínio nunca assumem a propriedade da entrega de ponta a ponta. Carregue apenas o que o workflow ativo precisa.