Communitygithub.com

sq-cm/claude-template

Loop de desenvolvimento CLI do HyperFrames — `npx hyperframes` para scaffolding (init), validação (lint, validate, inspect), preview, render e diagnóstico do ambiente (doctor, browser, info, upgrade). Use ao executar qualquer um desses comandos ou ao solucionar problemas do ambiente de build/render do HyperFrames. Para comandos de pré-processamento de assets (`tts`, `transcribe`, `remove-background`, invoque a skill `hyperframes-media`.

O que é claude-template?

A skill **sq-cm/claude-template** fornece um loop de desenvolvimento completo para o HyperFrames via CLI, centralizado no comando `npx hyperframes`. Ela permite criar (scaffold) novos projetos com `init`, validar a estrutura e o layout com `lint`, `validate` e `inspect`, pré-visualizar com hot-reload via `preview` e exportar vídeos finais com `render`, suportando parâmetros como qualidade, FPS e formato (MP4/WebM). Também inclui comandos de diagnóstico (`doctor`, `browser`, `info`, `upgrade`) para verificar dependências como Node.js >=22 e FFmpeg. A skill é útil para desenvolvedores que precisam iterar rapidamente na criação de composições visuais animadas, garantindo que elementos como balões de fala, cards e texto não ultrapassem os contêineres definidos. Ela é suportada nos agentes Claude Code, Cursor e Codex, e seu fluxo de trabalho segue uma sequência lógica: scaffold → lint → validate → inspect → preview → render, com ênfase em feedback visual e detecção de erros antes da renderização final.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/sq-cm/claude-template/tree/HEAD/.claude/skills/hyperframes-cli

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

CLI HyperFrames

Tudo roda através de npx hyperframes. Requer Node.js >= 22 e FFmpeg.

Fluxo de Trabalho

  1. Scaffold — npx hyperframes init meu-video
  2. Escrever — autoriza a composição HTML (veja a skill hyperframes)
  3. Lint — npx hyperframes lint
  4. Validação em tempo de execução — npx hyperframes validate
  5. Inspeção visual — npx hyperframes inspect
  6. Pré-visualização — npx hyperframes preview
  7. Renderizar — npx hyperframes render

Execute lint e inspect antes do preview. lint detecta data-composition-id ausente, faixas sobrepostas e timelines não registradas. inspect abre a composição renderizada no Chrome headless, percorre a timeline e relata texto que ultrapassa balões/contêineres ou sai da tela.

Scaffolding

npx hyperframes init meu-video                        # assistente interativo
npx hyperframes init meu-video --example warm-grain   # escolher um exemplo
npx hyperframes init meu-video --video clip.mp4        # com arquivo de vídeo
npx hyperframes init meu-video --audio track.mp3       # com arquivo de áudio
npx hyperframes init meu-video --example blank --tailwind # com runtime Tailwind v4 no navegador
npx hyperframes init meu-video --non-interactive       # pular prompts (CI/agentes)

Templates: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.

init cria a estrutura de arquivos correta, copia mídia, transcreve áudio com Whisper e instala skills de codificação por IA. Use-o em vez de criar arquivos manualmente.

Ao usar --tailwind, observe que o scaffold usa Tailwind v4.2 via runtime do navegador, não a configuração Tailwind v3 do Studio — verifique a sintaxe de classes e tokens de tema na documentação v4 antes de editar.

Linting

npx hyperframes lint                  # diretório atual
npx hyperframes lint ./meu-projeto    # projeto específico
npx hyperframes lint --verbose        # descobertas em nível de informação
npx hyperframes lint --json           # legível por máquina

Verifica index.html e todos os arquivos em compositions/. Relata erros (devem ser corrigidos), avisos (devem ser corrigidos se possível) e informações (com --verbose).

Validação em Tempo de Execução

npx hyperframes validate                  # diretório atual
npx hyperframes validate ./meu-projeto    # projeto específico
npx hyperframes validate --json           # legível por máquina
npx hyperframes validate --timeout 5000   # scripts/mídia lentos (padrão 3000 ms)

Carrega a composição no Chrome headless e relata erros do console JS, assets ausentes e problemas de contraste WCAG (--no-contrast para pular a verificação de contraste). Execute-o após lint, antes de inspect.

validate está depreciado no upstream em favor de npx hyperframes check, que executa lint, validação em tempo de execução, layout, animação e verificação de contraste em uma única sessão do navegador — qualquer uma das abordagens satisfaz um item de checklist "lint e validate".

Inspeção Visual

npx hyperframes inspect                 # inspeciona o layout renderizado ao longo da timeline
npx hyperframes inspect ./meu-projeto   # projeto específico
npx hyperframes inspect --json          # descobertas legíveis por agente
npx hyperframes inspect --samples 15    # varredura mais densa da timeline
npx hyperframes inspect --at 1.5,4,7.25 # timestamps explícitos de quadros-chave

Use após lint e validate, especialmente para composições com balões de fala, cards, legendas ou tipografia apertada. Ele relata:

  • Texto se estendendo para fora do contêiner visual ou balão mais próximo
  • Texto cortado pela sua própria caixa de largura/altura fixa
  • Texto se estendendo para fora da tela da composição
  • Filhos escapando de contêineres de corte

Erros devem ser corrigidos antes da renderização. Avisos são exibidos para revisão do agente; adicione --strict para falhar também em avisos. Problemas estáticos repetidos são colapsados por padrão para que a saída JSON permaneça compacta para janelas de contexto LLM. Se o estouro for intencional para uma animação de entrada/saída, marque o elemento ou ancestral com data-layout-allow-overflow. Se um elemento decorativo nunca deve ser auditado, marque-o com data-layout-ignore.

npx hyperframes layout continua disponível como um alias de compatibilidade para a mesma passagem de inspeção visual.

Pré-visualização

npx hyperframes preview                   # serve o diretório atual
npx hyperframes preview --port 4567       # porta personalizada (padrão 3002)

Recarrega automaticamente em alterações de arquivos. Abre o studio no seu navegador automaticamente.

Ao devolver um projeto ao usuário, use a URL do projeto do Studio, não o caminho do index.html fonte:

http://localhost:<port>/#project/<nome-do-projeto>

Use a porta real da saída do preview e o nome do diretório do projeto. Por exemplo, após npx hyperframes preview --port 3017 em codex-openai-video, relate http://localhost:3017/#project/codex-openai-video.

Trate index.html apenas como contexto de código-fonte. É aceitável vinculá-lo como um arquivo de implementação, mas não o rotule como o projeto ou a superfície de pré-visualização.

Renderização

npx hyperframes render                                # MP4 padrão
npx hyperframes render --output final.mp4             # saída nomeada
npx hyperframes render --quality draft                # iteração rápida
npx hyperframes render --fps 60 --quality high        # entrega final
npx hyperframes render --format webm                  # WebM com transparência
npx hyperframes render --docker                       # byte-idêntico
FlagOpçõesPadrãoNotas
--outputcaminhorenders/nome_timestamp.mp4Caminho de saída
--fps24, 30, 603060fps dobra o tempo de renderização
--qualitydraft, standard, highstandarddraft para iterar
--formatmp4, webmmp4WebM suporta transparência
--workers1-8 ou autoautoCada um inicia uma instância do Chrome
--dockerflagoffSaída reproduzível
--gpuflagoffCodificação acelerada por GPU
--strictflagoffFalhar em erros de lint
--strict-allflagoffFalhar em erros E avisos
--variablesobjeto JSON—Substitui valores de variáveis declaradas em data-composition-variables
--variables-filecaminho—Arquivo JSON com valores de variáveis (alternativa a --variables)
--strict-variablesflagoffFalhar na renderização em chaves não declaradas ou incompatibilidades de tipo em --variables

Orientação de qualidade: draft enquanto itera, standard para revisão, high para entrega final.

Renderizações parametrizadas: a composição declara suas variáveis na raiz <html> com data-composition-variables — um array JSON de declarações ({id, type, label, default} por entrada) que define o esquema. Scripts internos leem os valores resolvidos via window.__hyperframes.getVariables(). O CLI --variables '{"title":"Relatório Q4"}' é um objeto JSON indexado por id que substitui os valores padrão declarados para uma renderização; chaves ausentes caem para o padrão, então a mesma composição é executada inalterada no preview de desenvolvimento e em produção. (Hosts de sub-composição também podem substituir por instância com data-variable-values — mesma forma de objeto, com escopo para uma montagem da sub-composição. Veja a skill hyperframes para o padrão completo.)

Pré-processamento de Assets

npx hyperframes tts, transcribe e remove-background produzem assets (áudio de narração, transcrições palavra por palavra, vídeo com transparência) que são inseridos em uma composição. Cada um baixa seu próprio modelo na primeira execução. Para seleção de voz, regras do modelo Whisper (a pegadinha .en que traduz não-inglês), escolha de formato de saída (VP9 alpha WebM vs ProRes) e a cadeia TTS → transcrever → legendas, invoque a skill hyperframes-media.

Solução de Problemas

npx hyperframes doctor       # verificar ambiente (Chrome, FFmpeg, Node, memória)
npx hyperframes browser      # gerenciar Chrome incluído
npx hyperframes info         # detalhes da versão e ambiente
npx hyperframes upgrade      # verificar atualizações

Execute doctor primeiro se a renderização falhar. Problemas comuns: FFmpeg ausente, Chrome ausente, pouca memória.

Outros

npx hyperframes compositions   # listar composições no projeto
npx hyperframes docs           # abrir documentação
npx hyperframes benchmark .    # benchmark de desempenho de renderização

Habilidades Relacionadas