CLI HyperFrames
Execute comandos como npx hyperframes ... a menos que as instruções do projeto forneçam um wrapper. Obedeça ao wrapper quando presente. O CLI requer Node.js 22 ou mais recente e FFmpeg.
Ciclo de desenvolvimento
- Scaffold:
npx hyperframes init <projeto>ou capture um site. No modo não-TTY, passe--non-interactive --example=<nome>. - Autor: escreva a composição usando
/hyperframes-core. - Obtenha feedback rápido enquanto edita: execute
npx hyperframes lintapós a primeira passagem em HTML e após mudanças estruturais. - Execute a gate final: execute
npx hyperframes check; ele reexecuta o lint antes de abrir o navegador. Não preceda com uma invocação de lint redundante. Adicione--snapshotspara quadros de visão geral anotados e localização de cortes. - Inspecione sub-composições: quando
index.htmlmontardata-composition-src, capture snapshots intermediários e inspecione cada cena montada. - Abra a pré-visualização final do Studio: execute
npx hyperframes preview, entregue a URL do projeto da timeline ao usuário e pergunte se deseja revisar ou renderizar. - Renderize somente após aprovação: use qualidade rascunho para iteração e qualidade alta para entrega.
- Verifique a saída: confirme que o arquivo existe, não está vazio e tem uma duração plausível.
# Verificação rápida de iteração; repita durante a autoria conforme necessário.
npx hyperframes lint
# Gate final obrigatória; inclui lint.
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4
check executa lint primeiro, depois usa uma sessão de navegador e uma passagem de busca para auditar erros de tempo de execução, requisições com falha, layout, asserções de *.motion.json e contraste WCAG. Achados persistentes bloqueiam o código de saída; achados transitórios de entrada ou saída são informativos. Use --strict para bloquear avisos. validate, inspect e layout permanecem como aliases para compatibilidade, mas não devem aparecer em novas instruções ou scripts.
Duas superfícies de pré-visualização diferentes
Não confunda estes estados:
| Superfície | Quando pode abrir | Propósito |
|---|---|---|
| Quadro de storyboard | Antes das verificações de composição, somente se storyboard: yes | Revisar cartões de plano e esboços wireframe. Abrir ?view=storyboard#project/<nome>. |
| Pré-visualização final da composição | Após o check passar | Revisar a timeline montada antes de renderizar. Abrir #project/<nome>. |
O quadro inicial não é aprovação do vídeo final. A renderização sempre requer a aprovação final definida por hyperframes-core/references/review-loop.md.
Teste de fumaça de sub-composição
Auditorias estáticas não conseguem capturar todas as falhas de montagem. Quando o projeto usa sub-composições, capture ao menos um ponto intermediário visível para cada slot hospedeiro:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Trate conteúdo pequeno sem estilo, ícones do tamanho do canvas, elementos de herói ausentes ou timeouts de registro de timeline como defeitos de montagem que bloqueiam a renderização. Veja hyperframes-core/references/sub-compositions.md para as correções correspondentes.
Convenções para agentes
-
Prefira
--jsonpara chamadas de agente e CI.render,previeweplayem modo servidor não fornecem saída JSON comum;preview --selection --jsonepreview --context --jsonsão exceções de modo consulta. -
doctor --jsonsempre sai com zero. Avalie com base em seu payload:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
O modo não-TTY é automático.
initrequer--examplelá; use--non-interactivepara forçar comportamento determinístico em um TTY. -
Use um único
HYPERFRAMES_RUN_IDpara todos os comandos no mesmo loop de verificação. -
Use
--strict,--strict-alle--strict-variablesquando os avisos, variáveis ou condições de CI correspondentes devem bloquear a renderização. -
Caminhos JSON redigem o diretório home como
$HOME; não tente reverter a redação. -
Nunca renderize apenas porque as verificações passaram. Pause na pré-visualização final e aguarde aprovação.
Edições orientadas pelo Studio
Quando o usuário se referir a “este elemento” ou à seleção atual, consulte o Studio em vez de adivinhar:
npx hyperframes preview --context --json --context-fields selection
Use selection.target.hfId quando disponível, caso contrário, seu seletor e arquivo de origem. Se o resultado relatar no-selection, peça ao usuário para clicar no elemento e reexecutar. Solicite apenas as fatias de contexto que você precisa; use --context-detail full apenas para estilos computados ou metadados de texto editável. Comportamento completo e códigos de falha estão em references/preview-render.md.
Opções de renderização
| Necessidade | Comando |
|---|---|
| Iteração local rápida | npx hyperframes render --quality draft |
| Entrega final local | npx hyperframes render --quality high --output out.mp4 |
| Renderização em contêiner reproduzível | npx hyperframes render --docker --strict --output out.mp4 |
| Renderização em lote orientada por variáveis | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| Renderização HeyGen sem infraestrutura | npx hyperframes cloud render |
| Renderização AWS distribuída autogerenciada | npx hyperframes lambda render <projeto> --width 1920 --height 1080 --wait |
| Renderização GCP distribuída autogerenciada | npx hyperframes cloudrun render <projeto> --width 1920 --height 1080 --wait |
Use renderização em nuvem quando o usuário quiser renderização hospedada sem Chrome local, FFmpeg ou AWS. Use Lambda apenas quando a propriedade da AWS for um requisito. Use Cloud Run apenas quando a propriedade do GCP for um requisito. Leia a referência correspondente antes de executar qualquer caminho de nuvem.
Após verificar uma renderização bem-sucedida, envie um relatório de feedback, a menos que a telemetria esteja desabilitada ou o usuário tenha optado por sair:
npx hyperframes feedback --rating <0-10> --comment "<resultado ou dificuldade específica>"
Mantenha o feedback de execução limpa conciso. Para qualquer bug ou dificuldade, capture um pacote de reprodução antes de enviar; não envie apenas um resumo de sintoma. Inclua o comando reexecutável e diretório de trabalho, comportamento esperado versus real, erro exato, se a saída foi concluída/usou fallback/ falhou, workaround e status do projeto de reprodução. Para uma classificação ≤ 7 que descreva um defeito visual (quadro preto, cintilação, saída corrompida, quadro errado, saída em branco, outra anomalia visual), inclua também um bloco COMPOSITION_STRUCTURE: — uma anatomia estrutural que preserva a privacidade (censo de elementos + presença de atributos + formato da timeline) para que mantenedores possam corresponder a famílias de bugs conhecidas sem o ZIP da composição. Agentes preenchem isso automaticamente via o helper de censo de composição; o usuário humano não preenche manualmente. Se o problema não se reproduziu novamente, diga isso e ainda inclua o último comando e logs com falha. Use --file-issue apenas com consentimento: ele publica uma reprodução mínima em uma URL pública. O formato obrigatório do pacote e aviso de privacidade estão em references/preview-render.md.
Leia a referência correspondente antes de executar um comando
As seguintes referências e skills proprietárias são contratos de comando obrigatórios, não leitura de fundo opcional. Antes de executar um comando na tabela, leia sua linha correspondente.
| Necessidade | Referência |
|---|---|
init, capture, skills | references/init-and-scaffold.md |
lint, check, sidecars de movimento, snapshot | references/lint-validate-inspect.md |
compare, grade-compare, render --batch orientado por variáveis | references/compare-and-batch.md |
beats para a grade de batidas do Studio de um projeto existente | references/beats.md |
preview, play, render, publish, contexto do Studio, feedback | references/preview-render.md |
doctor, gerenciamento de navegador | references/doctor-browser.md |
auth, renderização em nuvem HeyGen e variáveis de template | references/cloud.md |
| Implantação e renderização no AWS Lambda | references/lambda.md |
| Implantação e renderização no Google Cloud Run | references/cloudrun.md |
info, upgrade, compositions, docs, benchmark, telemetria, pré-processamento de mídia | references/upgrade-info-misc.md |
Para variáveis de composição, leia também /hyperframes-core → references/variables-and-media.md. Para hyperframes add e hyperframes catalog, use /hyperframes-registry. Antes de hyperframes present, leia /slideshow; antes de hyperframes keyframes, leia /hyperframes-keyframes. Para TTS, transcrição, legendas ou opções de remoção de fundo, use /media-use.
Os comandos especializados são deliberadamente documentados por seus fluxos de trabalho proprietários:
npx hyperframes present <dir-projeto> --port 3004 --no-open
npx hyperframes beats <dir-projeto> --json
npx hyperframes keyframes <dir-projeto> --json
present serve um deck navegável com sincronização de apresentador e audiência. beats é o utilitário independente de grade de batidas do Studio definido em references/beats.md. keyframes expõe diagnósticos de animação e caminho de movimento seguros para busca.