Sma1lboy/rove

HyperFrames CLI

Tudo é executado através de npx hyperframes, a menos que as instruções do projeto especifiquem um wrapper local. Obedeça exatamente ao wrapper local. Requer Node.js >= 22 e FFmpeg.

Fluxo de Trabalho

1. Scaffold — npx hyperframes init my-video (ou capture a partir de uma URL)
2. Escrever — autor da composição HTML (veja ../core)
3. Lint — npx hyperframes lint
4. Validar — npx hyperframes validate (erros de runtime + contraste)
5. Inspeção visual — npx hyperframes inspect
6. Pré-visualizar — npx hyperframes preview abre o Studio, o editor de timeline onde o usuário pode editar manualmente qualquer coisa (não apenas assistir). Revise lá, depois pergunte antes de renderizar.
7. Renderizar — escolha a variante:
   • Iterar: npx hyperframes render --quality draft
   • Entregar: npx hyperframes render --quality high --output out.mp4
   • CI / reprodução cross-host: npx hyperframes render --docker --strict --output out.mp4
   • Nuvem (longo / grande): npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait (veja Lambda abaixo)

Execute lint, validate e inspect antes do preview. lint detecta data-composition-id ausente, trilhas sobrepostas e timelines não registradas. validate carrega a composição em um Chrome headless e relata erros de console de runtime, além de problemas de contraste WCAG. inspect percorre a timeline e relata texto que transborda de bolhas/containers ou sai do canvas — e, quando um sidecar *.motion.json está presente, verifica a intenção de movimento (entradas disparando durante a busca, ordem de stagger, dentro do quadro, vivacidade) contra essa mesma timeline percorrida.

Para trabalhos com muitos movimentos, prefira iteração baseada em snapshots e um sidecar *.motion.json — veja references/lint-validate-inspect.md para a disciplina e especificação de verificação de movimento.

Convenções para Agentes

Regras transversais que se aplicam a todos os comandos:

• --json está disponível em todos os comandos, exceto render, preview e play. Use-o para qualquer invocação de agente / CI dos comandos suportados; a saída inclui um envelope _meta (versão da CLI, mais recente disponível, conselho de atualização). render reporta status via stdout + código de saída apenas — verifique o sucesso com a verificação pós-renderização abaixo; preview / play são servidores, sem JSON.
• doctor --json sempre sai com código 0, mesmo quando o ambiente está quebrado. Avalie o campo ok do payload: npx hyperframes doctor --json | jq -e '.ok' > /dev/null. Isso isola os pipelines de mudanças na versão da CLI.
• O modo non-TTY é detectado automaticamente. Quando stdout não é um TTY (CI, agentes, saída pipeada) a CLI alterna automaticamente para não interativo; init então requer --example. Passe --non-interactive para forçar este modo mesmo em um TTY.
• Gating de CI na renderização: --strict falha em erros de lint, --strict-all também falha em avisos, --strict-variables falha em chaves --variables não declaradas.
• Caminhos em --json são redigidos — $HOME torna-se o literal $HOME para que a saída seja segura para colar em relatórios de bugs e contextos de agente.
• Renderização é controlada pelo usuário. Nunca renderize automaticamente após as verificações passarem. Pare no preview, informe ao usuário que o vídeo é editável no Studio, e renderize somente após a aprovação.
• Verificação pós-renderização. Após o render retornar código 0, confirme que o arquivo de saída existe e tem tamanho plausível antes de relatar sucesso: [ -s "$OUTPUT" ] || echo "render produced no output". A CLI imprime ◇ <caminho> em caso de sucesso; para renders longos, verifique também a duração com ffprobe -i "$OUTPUT" -show_format -v error.

Roteamento

Deseja…	Leia
Criar um projeto (init, capture, skills)	references/init-and-scaffold.md
Verificar correção (lint, validate, inspect, snapshot)	references/lint-validate-inspect.md
Pré-visualizar ou renderizar (preview, play, render, publish)	references/preview-render.md
Diagnosticar o ambiente (doctor, browser)	references/doctor-browser.md
Renderizar em nuvem no AWS Lambda (lambda deploy / render / progress / destroy / policies)	references/lambda.md
Todo o resto (info, upgrade, compositions, docs, benchmark, telemetry, pré-processamento de assets)	references/upgrade-info-misc.md

Hand-Offs de Seção

• Projetos Tailwind (init --tailwind) → veja ../core/references/tailwind.md antes de editar classes ou tokens de tema.
• Blocos/componentes do Registry (hyperframes add, hyperframes catalog) → veja ../registry para caminhos de instalação, fiação de sub-composições e mesclagem de snippets.
• Renderizações parametrizadas (--variables) → declaradas via data-composition-variables no <html>; veja ../core/references/variables-and-media.md para o esquema completo.

Lambda (Renderização em Nuvem)

hyperframes lambda implanta renderização distribuída no AWS Lambda e executa renders a partir do seu laptop ou CI. O processo completo são três comandos:

npx hyperframes lambda deploy                                             # provisiona stack SAM (Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy                                            # desmonta (o bucket S3 é mantido)

Use Lambda quando uma renderização for muito longa / muito grande para um único host (vídeos de vários minutos, 4K, grandes lotes paralelos) e você tiver credenciais AWS configuradas. Para iteração no ciclo de desenvolvimento, mantenha-se na renderização local (render).

Veja references/lambda.md para pré-requisitos, todos os 6 subcomandos (deploy, sites create, render, progress, destroy, policies), validação de política IAM, arquivos de estado e regras de custo/limpeza.

Portão de Conclusão Mínimo

Portões estáticos

npx hyperframes lint
npx hyperframes validate

Adicione inspect para trabalhos sensíveis a layout e render --strict em CI para falhar em erros de lint.

Teste visual de fumaça — obrigatório quando o projeto usa sub-composições

lint / validate / inspect avaliam cada composição isoladamente. Eles nunca carregam o index.html e montam sub-composições via data-composition-src, portanto não conseguem detectar falhas de montagem entre arquivos (veja ../core/references/sub-compositions.md, "Armadilhas comuns"). O único portão que as detecta é aquele que realmente carrega o index.html e percorre a timeline.

Use hyperframes snapshot — ele carrega o projeto da mesma forma que render (portanto, exercita o mesmo caminho de montagem), mas captura apenas os timestamps solicitados, sendo uma questão de segundos em vez de uma renderização completa:

# Capture um quadro no ponto médio de cada sub-composição.
# Pontos médios = data-start + data-duration/2 para cada slot host no index.html.
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...

# Ou, se não precisar de segmentação por cena, uma amostra uniformemente espaçada:
npx hyperframes snapshot --frames 9

A saída vai para snapshots/frame-NN-at-Xs.png. Examine cada quadro em relação ao plano da cena.

Bandeiras vermelhas por quadro (cada uma mapeia um modo de falha específico que os portões estáticos perdem):

O que você vê	Causa raiz
Texto aparece minúsculo + sem estilo no canto superior esquerdo	Bloco <style> deixado no <head> fora do <template> (Armadilha 1) — nenhum CSS alcançou o DOM ativo
Elementos SVG/icone ampliados ao tamanho do canvas	Mesmo que acima — sem restrições de largura/altura aplicadas
Elemento principal da cena está completamente ausente; apenas fundo + marca d'água visíveis	Host-id ≠ template id (Armadilha 2) — a timeline nunca foi executada, quadro capturado no estado inicial
Comando de snapshot registra Sub-composition timelines not registered after 45000ms	Armadilha 2 — confirmação direta

snapshots/ pode ser excluído após a inspeção visual; a renderização final voltada ao usuário é uma passagem separada com npx hyperframes render.