repo-cinema

Habilidade de Diretor repo-cinema

Crie vídeos de demonstração de produto em 60fps com qualidade de Screen Studio diretamente a partir de um código-fonte. Em vez de gravações de tela improvisadas ou movimentação aleatória do cursor, o repo-cinema executa um pipeline determinístico de 5 estágios: analisar -> planejar -> encenar -> renderizar -> verificar.

Princípios Arquiteturais Centrais

1. Casos de Uso Primeiro da Persona (analisar): Nunca mostre estatísticas internas de depuração ou telas de configuração brutas. Leia pontos de entrada, comandos CLI, rotas, componentes e testes para sintetizar cenas concretas de Persona -> Ponto de Dor -> Ação do Usuário -> Resultado Duradouro.
2. Enquadramento Causal (planejar): Enquadre a caixa delimitadora de união bbox(disparador ∪ resultado) em vez de seguir o ponteiro do mouse. Trave o foco horizontal fx = viewport.width / 2 sempre que a largura do conteúdo ocupar >= 70% do palco para que eixos, cabeçalhos e colunas da direita nunca sejam cortados para fora da tela.
3. Pausas de Leitura Estacionárias: Aproxime o zoom da câmera antes de uma ação, depois mantenha (zoom, fx, fy) 100% congelado durante a interação + compreensão para que os espectadores possam realmente ler gráficos e notificações toast.
4. 60fps Determinístico com Relógio Virtual (renderizar): Injete o Shim de Relógio Virtual (Date, performance.now, requestAnimationFrame) antes do carregamento da página para que transições CSS, animações ECharts, trajetórias mínimas de salto do cursor C2 (arcos sin^3(pi * u), inchaço de velocidade <=12%, inclinação de +/-6 graus, morfismo seta <-> mão apontadora), e duplos cliques com ondas sejam processados deterministicamente quadro a quadro no FFmpeg.
5. Autoinspeção com Folha de Contato (verificar): Gere uma contact-sheet.png 3x3 + verify-report.json (validação de fluxo ffprobe + zero cliques fora da tela) e inspecione visualmente cada painel antes de enviar.

Comandos Utilitários da CLI (repo-cinema)

Quando instalado globalmente ou executado a partir do repositório (npx repo-cinema ... ou node dist/cli.js ...), cada estágio gera arquivos estruturados:

# 1. Leia qualquer repositório e extraia cenários de caso de uso (opcionalmente execute repomix primeiro)
repo-cinema analyze --repo ./meu-projeto --output ./out/dossier.json [--repomix]

# 2. Construa storyboard causal de câmera/cursor em JSON + visualização HTML
repo-cinema plan --dossier ./out/dossier.json --output ./out/storyboard.json --html ./out/storyboard.html --tema aurora-indigo

# 3. Construa palco 4-em-1 (web-url | plugin-ou-componente | cli-terminal | hibrido)
repo-cinema stage --dossier ./out/dossier.json --plan ./out/storyboard.json --output ./out/stage.html [--url http://localhost:3000]

# 4. Captura CDP determinística em 60fps + SFX estéreo de 48kHz (ou TTS opcional)
repo-cinema render --plan ./out/storyboard.json --stage ./out/stage.html --output ./out/demo.mp4 --gif ./out/demo.gif --audio sfx

# 5. Valide fluxos, limites de telemetria e construa folha de contato visual 3x3
repo-cinema verify --video ./out/demo.mp4 --telemetry ./out/demo.telemetry.json --contact-sheet ./out/contact-sheet.png --output ./out/verify.json

# Ou execute o pipeline completo de 5 estágios em um comando:
repo-cinema run --repo ./meu-projeto --out-dir ./out --tema aurora-indigo

Fluxo de Trabalho do Diretor

Passo 1: Analisar Repositório e Público-Alvo

Execute repo-cinema analyze --repo <caminho> --output <dossier.json>. Leia os useCases gerados:

• Verifique o archetype detectado (web-app, desktop-or-ide-plugin, cli-tool, ui-library, hybrid).
• Refine legendas ou adicione fixtures de amostra autênticas ao domínio se o repositório tiver fluxos de trabalho especializados (lembre-se: zero dados pessoais, zero contadores exclusivos de desenvolvedor).

Passo 2: Planejar Storyboard e Aprovar Enquadramento

Execute repo-cinema plan com --html e inspecione storyboard.html (ou revise beats, captionWarnings e cameraKeyframes):

• Corrija quaisquer avisos do Revisor de Legendas Anti-Slop (sem "sem precedentes", "próxima geração", "perfeitamente" ou legendas com >96 caracteres).
• Garanta que o quadro de abertura (t=0) e o quadro de fechamento (t=durationMs) estejam limpos em zoom: 1.0 para looping perfeito do GIF do README.

Passo 3: Selecionar Adaptador de Palco

• web-url: O aplicativo já está rodando localmente (http://localhost:PORT). O gravador injeta o Shim de Relógio Virtual + sobreposição não intrusiva de cursor/câmera/legenda diretamente na página ativa.
• plugin-or-component: Plugins de desktop (Obsidian, VS Code, Raycast) ou pacotes de componentes de IU renderizados dentro de um chrome macOS Studio escuro com módulos principais reais empacotados via esbuild.
• cli-terminal: Ferramentas de terminal exibidas em um terminal macOS transparente com saída de comando sincronizada, blocos de KPI e cartões de impacto de resultado.
• hybrid: Studio macOS multi-abas combinando execução CLI com saída visual ao vivo e diagramas de arquitetura.

Passo 4: Renderizar Mestre 60fps + GIF + Áudio

Execute repo-cinema render:

• O padrão --audio sfx sintetiza micro-SFX estéreo de 48kHz sem dependências (cliques panorâmicos alinhados com o cursor x, leve sopro de ar do zoom, som de confirmação de toast) — zero chaves de API externas necessárias.
• Opcional --audio tts --tts-provider <macos-say|edge-tts|openai|elevenlabs> mistura narração de forma limpa com micro-SFX.

Passo 5: Verificar e Inspecionar Visualmente

Execute repo-cinema verify e inspecione contact-sheet.png diretamente com seu visualizador de arquivos/imagens:

• Confirme passed: true, offscreenClicks: 0, e texto legível em todas as 9 miniaturas de keyframe.
• Se algum elemento cortar perto das bordas do viewport, aumente marginPx em computeCausalFraming ou reduza zoom em 0.06 e renderize novamente.

Guias de Referência

• Física de Câmera e Cursor
• Adaptadores de Palco 4-em-1
• Esquema de Storyboard
• Arquitetura de Código Aberto e Atribuições

Erros Comuns a Evitar

• Seguir o ponteiro quadro a quadro durante digitação/arraste: Causa enjoo. Sempre trave o enquadramento da câmera por batida durante pausas.
• Usar setTimeout com relógio real / captura de tela em tempo real: Perde quadros sempre que a CPU aumenta e produz gravações entrecortadas de 24–40fps. Sempre dirija animações via __rcStep(dtMs).
• Aplicar zoom muito agressivo (> 1.35x) em gráficos ou tabelas largas: Corta rótulos do eixo Y ou colunas de resumo mais à direita. Mantenha wideLockRatio em 0.70 para que fx = width / 2.
• Enviar binários .mp4 brutos grandes para o repositório GitHub: Rastreie .gif otimizado para paleta de cores leve + contact-sheet.png em docs/assets/ e anexe .mp4 aos Releases do GitHub ou ignore *.mp4 localmente.