Ponto de entrada HyperFrames
HyperFrames renderiza vídeo a partir de HTML — uma composição é um arquivo HTML cujo DOM declara o tempo com atributos data-*, cujo runtime de animação é buscável e cuja reprodução de mídia é de propriedade do framework. O contrato completo de autoria reside em /hyperframes-core; leia-o antes de escrever HTML de composição.
1. Iniciar a partir do estado do projeto
Aplique a primeira linha correspondente; não avalie linhas de estado inferiores:
| Estado | Ação |
|---|---|
| Porta explícita de uma fonte Remotion existente para HyperFrames | Leia references/routes/remotion-to-hyperframes.md e, em seguida, direcione diretamente para esse fluxo de trabalho. Pule a camada de intenção. |
| Operação específica em um projeto HyperFrames existente: inspecionar, diagnosticar, validar, visualizar, renderizar, publicar ou renderizar em lote | Execute apenas essa operação. Pule o roteamento de intenção e fluxo de trabalho; carregue /hyperframes-cli e quaisquer skills 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 fluxo de trabalho; flow: companion sempre executa em /general-video. Não faça perguntas do brief. |
Sem brief, mas hyperframes.json ou STORYBOARD.md existe | Retome dos arquivos do projeto e preferências registradas. Infira o fluxo de trabalho proprietário dos artefatos existentes. Se não puder ser determinado exclusivamente, faça uma pergunta apenas de roteamento; não execute a entrevista de intenção. |
| Criação nova | Execute a camada de intenção — references/intent-interview.md — e então direcione 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 direcionar. 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 scaffoldado fixa hyperframes@<version> em seus scripts package.json para que as renderizações permaneçam reproduzíveis; a fixação nunca avança por conta própria, e uma execução fixada de um CLI mais antigo não imprime nenhum aviso sobre isso. Ao retomar um projeto cujos scripts carregam uma fixação, verifique uma vez antes do primeiro comando que afeta a renderização:
npx hyperframes@latest upgrade --project . --check
A verificação é somente leitura e reporta a fixação em relação ao último lançamento; mantenha o . explícito — em versões mais antigas do CLI, um --project simples seguido por outra flag consome essa flag como seu valor de diretório. Quando reportar que o projeto está desatualizado — ou qualquer saída do CLI já o mostrar (o aviso 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 ., e então 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 à fixação antiga — 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 do 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 uma fixação aumentada sem verificação.
2. Direcionar criação nova
Use a primeira linha correspondente. Combine o entregável solicitado, não uma palavra ou tipo de arquivo mencionado de passagem.
| Prioridade | Solicitação | Fluxo de trabalho |
|---|---|---|
| 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 filmagens existentes de cabeça falante sem alterá-las | /embedded-captions |
| 4 | Adicionar sobreposições gráficas projetadas a filmagens existentes de cabeça falante, entrevista ou podcast sem alterar a filmagem | /talking-head-recut |
| 5 | Construir um vídeo sincronizado com batida a partir de uma faixa musical, sem narração ou captura de site | /music-to-video |
| 6 | Criar uma unidade explicitamente curta, sem narração, focada em movimento, tipicamente abaixo de 10s | /motion-graphics |
| 7 | Explicar uma pull request do GitHub ou alteração de código a partir de uma referência de PR | /pr-to-video |
| 8 | Comercializar ou mostrar um site, site de produto, aplicativo ou empresa a partir de uma URL ou brief 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/acionador (disponível antes de skills de fluxo de trabalho instaladas lazy) mais a entrada de entrevista dessa rota. Se o candidato não satisfizer seu contrato, continue roteando em vez de forçar a correspondência. Leia apenas o arquivo da rota correspondente.
Resolver ambiguidades comuns
- Uma curta animação de título, sting de logotipo, acerto de estatística, acerto de gráfico, acerto de mapa ou terço inferior autônomo é
/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 gráfico em movimento explicitamente curto pode usar uma URL, tweet, artigo ou captura de tela como material de origem. Uma solicitação genérica "faça um vídeo deste site" é
/product-launch-video. - Filmagem existente com legendas direciona para
/embedded-captions; filmagem com cartões de informação projetados direciona para/talking-head-recut. Re-temporização, reordenação, recoloração, reenquadramento ou remixagem de filmagem é uma edição personalizada e cai em/general-video. - Um arquivo de música seleciona
/music-to-videoapenas quando sua grade de batida impulsiona a peça. Música usada como fundo não substitui a rota correspondente ao assunto. - "Quero um storyboard" altera o processo de revisão, não o fluxo de trabalho. Sem outro sinal de roteamento, use
/general-video. Um storyboard esboçado confirmado pode ser o próprio entregável solicitado; o loop de revisão define esse ponto de parada. - Fluxos de trabalho narrativos especializados suportam até cerca de 3 minutos e são mais fortes em torno de 30–90s. Direcione uma peça claramente mais longa para
/general-video. O comprimento nunca substitui um port, deck, legenda, sobreposição ou entregável orientado por música explícito.
3. Direcione 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 de execução, hand-off — e termina escrevendo BRIEF.md. O brief é o único artefato de roteamento que o fluxo de trabalho lê; nada depois reabre esta skill ou a entrevista. Responda a qualquer pergunta posterior "o que a rota exigiu?" a partir de BRIEF.md.
4. Instalar e entrar no fluxo de trabalho
Antes de ler o fluxo de trabalho selecionado, instale-o ou atualize-o e as skills de domínio principal:
npx hyperframes skills update <workflow-name>
Use o nome simples sem /. Se o comando falhar, exiba o erro; não reconstrua o fluxo de trabalho a partir da memória. Todo o resto sobre instalação — a divisão core-vs-lazy, o que init atualiza, diagnóstico, opt-out de CI e o fallback sem CLI — reside em references/skill-lifecycle.md.
5. Carregar skills de domínio sob demanda
| Necessidade | Skill |
|---|---|
| Estrutura da composição, atributos de tempo, 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 |
| Gravação de narraçã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 de registro | /hyperframes-registry |
| Ativos, tokens, componentes ou quadros de storyboard do Figma como movimento reconstruído | /figma |
Frases de edição do criador são solicitações entre domínios. Carregue cada skill nomeada na linha correspondente:
| Solicitação do criador | Domínios necessários |
|---|---|
| "cortar esta filmagem", corte seco, aparar, emendar, reordenar ou usar um intervalo de origem | /general-video + /hyperframes-core; core possui data-start, data-duration, data-media-start e layout de faixa. |
| ampliar aqui, zoom-in / zoom-out, zoom multiestado suave ou reenquadramento, Ken Burns ou movimento de câmera | /general-video + /hyperframes-core + /hyperframes-keyframes; anime o wrapper visual/interno de corte, não o clipe temporizado. |
| corte de correspondência ou transição de câmera whip pan | /general-video + /hyperframes-animation + /hyperframes-keyframes + /hyperframes-registry; procure/instale uma primitiva de transição antes de criar manualmente. |
| fade, crossfade, ganho/volume de faixa, automação, duck/carve ou efeitos de áudio | /general-video + /hyperframes-core + /hyperframes-audio; core posiciona clipes, áudio mixa faixas posicionadas. |
| edições de imagem e som que combinam cortes com movimento de câmera ou mixagem | /general-video + /hyperframes-core + /hyperframes-keyframes quando houver movimento visual + /hyperframes-audio quando o som for desvanecido, mixado, ducked, automatizado ou processado. |
| origem ou geração de mídia, ou pré-processamento de uma rampa de velocidade/congelamento de meia fonte não suportada | /media-use; apenas origem/geração/pré-processamento, nunca mixagem de faixa posicionada. |
data-playback-rate constante é segura para renderização de imagem e som com preservação de tom. Não torna rampas de velocidade de origem passíveis de keyframe; pré-processe rampas. Para contratos de edição copiáveis, carregue /hyperframes-core → references/creator-editing-recipes.md.
Feedback amplo sobre como a mídia fotográfica parece ou se comporta também direciona para /media-use, mesmo quando o usuário nunca diz "correção de cor" ou "efeito".