hyperframes-cli

HyperFrames CLI

Execute comandos como npx hyperframes ... a menos que as instruções do projeto forneçam um wrapper. Obedeça ao wrapper quando presente. A CLI requer Node.js 22 ou superior e FFmpeg.

Loop de desenvolvimento

1. Estruturar: npx hyperframes init <projeto> ou capture um site. Em modo não-TTY, passe --non-interactive --example=<nome>.
2. Encontrar o movimento: antes de criar movimentos manualmente, procure por uma primitiva que já faça o que você precisa: npx hyperframes catalog --query "revelar um título linha por linha". Peça o efeito que você deseja, não o mecanismo que tem em mente. Instale com npx hyperframes add <nome> (veja /hyperframes-registry). Crie manualmente apenas se nada se encaixar.
3. Criar: escreva a composição usando /hyperframes-core.
4. Obter feedback rápido durante a edição: execute npx hyperframes lint após a primeira passagem de HTML e após alterações estruturais.
5. Executar o portão final: execute npx hyperframes check; ele executa o lint novamente antes de abrir o navegador. Não preceda com uma invocação redundante de lint standalone. Adicione --snapshots para quadros de visão geral anotados e para encontrar cortes.
6. Inspecionar sub-composições: quando index.html monta data-composition-src, capture snapshots intermediários e inspecione cada cena montada.
7. Abrir a pré-visualização final do Studio: execute npx hyperframes preview --background, verifique se a URL retorna HTTP 200, entregue a URL do projeto da timeline ao usuário e pergunte se deseja revisar ou renderizar. Mantenha-o ativo até que a revisão termine.
8. Renderizar apenas após aprovação: use qualidade de rascunho para iteração e qualidade alta para entrega.
9. Verificar a saída: confirme que o arquivo existe, não está vazio e tem uma duração plausível.

Cross-references obrigatórias de edição do criador

• Antes de criar ou diagnosticar um zoom, close/abertura, reenquadramento, movimento de câmera ou qualquer movimento com keyframes, leia /hyperframes-keyframes primeiro.
• Antes de hyperframes keyframes, leia /hyperframes-keyframes; o comando exibe trajetórias de animação e não diagnostica cortes de clipe.
• Para um corte, trim, splice, reordenação ou edição de tempo de origem, leia /hyperframes-core e use seu contrato de clipe/timeline.
• Para fade-in/fade-out, crossfade, ganho de faixa, automação de volume, ducking, carving de narração ou FX em áudio colocado, leia /hyperframes-audio. Carregue o core junto quando o posicionamento do clipe ou o tempo da imagem também mudarem.
• Use /media-use apenas para obter/gerar mídia ou pré-processar um ativo derivado. Copie a marcação de edição do criador de /hyperframes-core → references/creator-editing-recipes.md.

# Verificação rápida de iteração; repita enquanto cria, conforme necessário.
npx hyperframes lint

# Portão final obrigatório; inclui lint.
npx hyperframes check
npx hyperframes preview --background
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4

check executa o lint primeiro, depois usa uma sessão do navegador e uma passagem de busca para auditar erros de runtime, requisições com falha, layout, asserções de *.motion.json e contraste WCAG. Descobertas persistentes bloqueiam o código de saída; descobertas transitórias de entrada ou saída são informativas. 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, apenas quando storyboard: yes	Revisar cartões de planejamento e esboços wireframe. Abra ?view=storyboard#project/<nome>.
Pré-visualização final da composição	Após check passar	Revisar a timeline montada antes da renderização. Abra #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 pegar todas as falhas de montagem. Quando o projeto usa sub-composições, capture pelo 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 da tela, elementos de herói ausentes ou timeouts de registro na 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

• Pesquise no catálogo antes de escrever movimento manualmente. npx hyperframes catalog --query "<a batida, em inglês simples>". A pesquisa é totalmente local: não há camada hospedada, nenhuma conta e o texto da consulta nunca é enviado a lugar nenhum. Por padrão, ele classifica com base no vocabulário compartilhado com o nome, título e descrição do item, o que perde qualquer frase que não reuse a própria redação do catálogo. Adicione --on-device para classificar por significado (veja a camada offline abaixo).

• Consulte em inglês mesmo quando o vídeo não estiver. Ambas as camadas indexam um catálogo em inglês, portanto, uma consulta em outra escrita não produz termos pesquisáveis ​​e não retorna nada. Descreva o movimento em inglês; o texto na tela permanece no idioma que o vídeo precisar. Nenhuma palavra pesquisável na consulta significa exatamente isso e não é um componente ausente, portanto, não o relate como uma lacuna no catálogo.

• Leia qual camada respondeu; nunca a inferi a partir dos resultados que aparecem. Com --json o envelope carrega query, tier (on-device ou words), tier_detail, dropped, unindexed, shown, total e results, além de top_score quando a camada respondedora produz um e warnings quando uma camada foi solicitada e não pôde ser executada. Um resultado fraco em words é esperado; o mesmo resultado em on-device é um bug. top_score é apenas on-device e não tem um limite por trás dele: o ranker retorna todo o catálogo em alguma ordem para cada consulta, portanto, leia-o como evidência em vez de aprovação ou reprovação.

• dropped e unindexed são distorções opostas entre o registro e o índice no dispositivo, e reformular a consulta não corrige nenhum dos dois. dropped conta nomes classificados que este registro não pode instalar, portanto, as correspondências mais fortes são as que estão sendo perdidas. unindexed conta movimentos do registro que o índice não consegue ver, que nenhuma consulta pode retornar. Atualizar o registro não é a resposta para nenhum dos dois: seu manifesto tem um TTL de 24h e se auto-recupera, enquanto os vetores são um artefato publicado separadamente, obtido em ~/.hyperframes/catalog/. Reexecutar com --on-device busca novamente esse índice quando unindexed estiver acima de zero, portanto, esse é o remédio a ser entregue ao usuário. Uma distorção pura de sobre-cobertura (dropped acima de zero enquanto unindexed é zero) não aciona a nova busca; limpar ~/.hyperframes/catalog/ é a única saída para essa. Ambas as contagens são de nomes em vez de resultados, portanto, qualquer uma pode exceder total.

• Quando uma pesquisa voltar sem nada que valha a pena instalar, diga isso. npx hyperframes feedback --search-miss "<a consulta que você executou>" --wanted "<o movimento que você precisava>" --tier <a camada que respondeu>. Você não precisa montar essa linha: catalog --query a imprime pré-preenchida, e todo envelope de pesquisa --json a carrega como report_gap com a consulta e a camada já corretas — preencha --wanted e envie. Este é o único caminho que envia uma consulta para qualquer lugar, e é um comando deliberado separado precisamente para que catalog --query simples mantenha sua promessa de não enviar nada. Reporte em qualquer camada, sempre que os resultados não fizerem o que deveriam; não espere pela camada on-device, que precisa de um download consentido de 33 MB e, portanto, está desligada na maioria das execuções de agente — esperar por ela significa nunca reportar. A camada viaja junto no relatório, então uma falha de vocabulário permanece distinguível de uma falha de significado sem que você precise julgar qual você acertou. O que volta é uma lista de movimentos que o catálogo ainda não tem, lida diretamente em vez de adivinhada a partir de contagens de instalação, então a redação que importa é o efeito que você queria, não o nome do item que você imaginou. Não carrega nenhuma classificação e nunca cai na métrica de classificação.

• Ofereça a camada offline; nunca a ative silenciosamente. Um download único de ~33 MB (um build ONNX quantizado do bge-small-en-v1.5 mais seu tokenizador, fixado em uma revisão fixa) e os vetores do catálogo do registro, ambos armazenados em cache em ~/.hyperframes/, nenhum adicionado ao projeto ou a qualquer pacote. Uma vez em cache, ele classifica por significado sem nada enviado. Diga o tamanho em voz alta e deixe a pessoa decidir, depois passe --on-device (com -y para pular o prompt) assim que eles concordarem. A oferta interativa só é acionada em um TTY, e sob --json nada sobre ela é impresso, portanto, em uma execução de agente, você mesmo deve levantá-la com o usuário.

• Prefira --json para chamadas de agente e CI. Os modos de servidor render, preview e play não fornecem saída JSON comum; preview --selection --json e preview --context --json são exceções no modo de consulta.

• doctor --json sempre sai com zero. Verifique seu payload:

  npx hyperframes doctor --json | jq -e '.ok' >/dev/null
  

• O modo não-TTY é automático. init requer --example lá; use --non-interactive para forçar o comportamento determinístico em um TTY.

• Use um HYPERFRAMES_RUN_ID para todos os comandos no mesmo loop de verificação.

• Use --strict, --strict-all e --strict-variables quando os avisos, variáveis ou condições de CI correspondentes devem bloquear a renderização.

• Os caminhos JSON redigem o diretório home como $HOME; não tente reverter a redação.

• Quando um projeto de nuvem hospedado se aproxima ou excede o limite de upload de 200 MB, use cloud render --dry-run --json e siga a investigação .hyperframesignore em references/cloud.md. Nunca ignore um ativo apenas por ser grande.

• Nunca renderize apenas porque as verificações passaram. Pause na pré-visualização final e aguarde a aprovação.

Edições direcionadas pelo Studio

Quando o usuário se refere 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 executar novamente. Solicite apenas as fatias de contexto que você precisa; use --context-detail full apenas para estilos computados ou metadados de texto editável. O comportamento completo e os códigos de falha estão em references/preview-render.md.

Escolhas de renderização

Necessidade	Comando
Iteração local rápida	npx hyperframes render --quality draft
Entrega local final	npx hyperframes render --quality high --output out.mp4
Renderização de contêiner reproduzível	npx hyperframes render --docker --strict --output out.mp4
Renderização em lote local orientada por variáveis	npx hyperframes render --batch rows.json --output "renders/{name}.mp4"
Renderização HeyGen hospedada 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

A atribuição de skill é automática — os exemplos acima não precisam de --skill. Um projeto estruturado por um workflow (hyperframes init --skill=<workflow>) registra sua skill proprietária em hyperframes.json, e toda renderização posterior a herda na telemetria anônima: re-renderizações, npm run render e --batch igualmente. Passe --skill=<slug> explicitamente apenas para marcar um projeto que não foi criado por meio de um workflow (sua primeira renderização então o persiste).

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 não participar:

npx hyperframes feedback --rating <0-10> --comment "<resultado específico ou atrito>"

Mantenha o feedback de execução limpa conciso. Para qualquer bug ou atrito, capture um pacote de reprodução antes de enviar; não envie apenas um resumo do sintoma. Inclua o comando reexecutável (relativo ao diretório do projeto — o feedback é enviado para um canal público, portanto, não cole caminhos absolutos, prefixos de diretório home ou identificadores de usuário/máquina), comportamento esperado versus real, erro exato (também remova caminhos absolutos de stack traces — mantenha o basename + linha, remova o diretório inicial), se a saída foi concluída/reduziu/falhou, solução alternativa e status do projeto de reprodução. Para uma classificação ≤ 7 que descreve 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 + forma da timeline) para que os mantenedores possam corresponder a padrões de famílias de bugs conhecidas sem o ZIP da composição. Os agentes preenchem isso automaticamente por meio do auxiliar de censo de composição; o usuário humano não o preenche manualmente. Se o problema não se reproduziu novamente, diga isso e ainda inclua o último comando com falha e os logs. Use --file-issue apenas com consentimento: ele publica uma reprodução mínima em uma URL pública. O formato do pacote obrigatório e o aviso de privacidade estão em references/preview-render.md.

Leia a referência correspondente antes de executar um comando

O material de referência a seguir deve ser lido antes do primeiro uso dos comandos associados: [hyperframes-core], [hyperframes-keyframes], [hyperframes-audio], [media-use], [preview-render.md], [cloud.md], [sub-compositions.md], [review-loop.md], [creator-editing-recipes.md].