JoaoIurovschi/faisca

FAÍSCA

Palavra de disparo: faísca. A pessoa escreve "faísca" e descreve o vídeo (tema, frases, formato); esta skill cria o projeto, monta a linha do tempo e renderiza o MP4.

SKILL_DIR = pasta deste arquivo. A composição é HyperFrames (HTML + GSAP), com a linha do tempo esticada SLOW vezes e renderizada a 60 fps; o render-faisca.sh tira a média de cada SLOW subquadros, e o resultado é desfoque de movimento de verdade, com cara de After Effects.

• Catálogo dos efeitos prontos, tempos e onde ficam no código: referencias/efeitos.md.
• Estudar um vídeo de referência (decupar, medir fonte e cor, comparar): referencias/recriar-referencia.md.
• Trilha original composta por código e motion que reage ao áudio: referencias/trilha-propria.md, moldes em trilha/.
• Contrato do HyperFrames: se a skill hyperframes estiver instalada, ler antes de mexer na estrutura; npx hyperframes docs gsap e npx hyperframes docs data-attributes também ajudam.

Antes de tudo

1. De quem é a peça. Use a cor e as fontes da marca de quem vai publicar. Sem marca definida, fica o verde-limão do modelo.
2. O que dizer. Frases curtas de impacto (2 a 4 palavras por tela) e uma legenda corrida. Conteúdo só do que a pessoa pediu; nada inventado.
3. Formato e duração. 16:9 por padrão; Reels e TikTok em 9:16 (ver fim de referencias/efeitos.md). Sem narração, o estilo rende 4 a 15 s; com narração, dá para ir além, desde que cada tela troque a cada 0,4 a 0,8 s.
4. Pasta. Uma pasta por vídeo, fora de pastas sincronizadas (iCloud, Dropbox) se possível.
5. Sem crédito. Tudo roda local.

Etapa 1 · Criar o projeto

SKILL_DIR/scripts/novo-faisca.sh <pasta-do-projeto>

Roda hyperframes init, copia o modelo (composição de 4 s funcionando, fontes locais) e confere que o lint sai com 0 erros. Sem OK:, parar e consertar.

Etapa 2 · Identidade

• Cor de destaque: as quatro variáveis --acento, --acento-rgb, --acento-claro, --acento-escuro no :root. Tudo (brilho, faíscas, laser, pílula, placa, 3D) deriva delas.
• Fontes em assets/fonts/ com @font-face no próprio arquivo (o lint exige arquivo local). Trocar a do título só por uma pesada e condensada; medir antes (ver recriar-referencia).
• HUD (#hudBrand): nome da marca da peça. Nunca a marca de outra empresa.

Etapa 3 · Roteiro e linha do tempo

1. Escrever a decupagem: lista de eventos com instante (segundos reais), texto e efeito do catálogo. Uma ideia a cada 0,4 a 0,8 s.
2. Ajustar DUR e, junto, o data-duration do #root e do #stage para DUR × SLOW (render-faisca.sh recusa se não bater).
3. Trocar textos e instantes no bloco // ---------- linha do tempo. Para cena nova, copiar o padrão de um efeito do catálogo. Efeito que segue posição a cada instante vai em draw(t).
4. SLOW = 8 atende quase tudo. Zoom ou travessia muito rápida mostra "anéis" com 8 amostras: subir para 16 (dobra o tempo de render).
5. Com narração: tirar o tempo de cada palavra (Whisper ou similar) e prender os efeitos a esses instantes, em vez de chutar.

Etapa 4 · Revisão por quadros

SKILL_DIR/scripts/quadros.sh <projeto> 0.3,0.9,1.3,1.6,2.3,2.7,3.2,3.6,3.9

Instantes em segundos reais (o script multiplica pelo SLOW). Olhar a folha: texto cortado, palavra fora do lugar, efeito que não aparece. Os quadros são amostra única, sem desfoque.

Etapa 5 · Render e verificação

SKILL_DIR/scripts/render-faisca.sh <projeto> <projeto>/renders/<nome>.mp4 [--audio trilha.wav]
SKILL_DIR/scripts/render-faisca.sh <projeto> /tmp/sabotagem.mp4 --sabotar   # tem que FALHAR

O render confere três coisas: data-duration = DUR × SLOW, número de quadros a 60 fps e presença do desfoque (o vídeo final precisa diferir da amostra única nos trechos com movimento). O --sabotar gera sem desfoque e precisa terminar em ERRO: sem desfoque: é a prova de que a conferência sabe falhar. 4 s levam cerca de 1 a 4 min, conforme a máquina.

npx hyperframes check também roda, mas a auditoria de layout acusa por desenho: palavras da legenda que ainda vão aparecer (transparentes, text_not_painted) e camadas 3D sobrepostas (content_overlap). Exigido: lint com 0 erros; esses achados de layout são esperados.

Etapa 6 · Entrega

• Entregar o MP4 e dizer onde ele está.
• Contar o que ficou diferente do pedido, sem esconder.
• Estudo de vídeo de outra pessoa: o comparativo lado a lado é só para estudo; não publicar.

Armadilhas já pagas

Sintoma	Causa e conserto
Efeito procedural some ou trava em quadros soltos	draw(t) guardava estado ou media o DOM. Tem que ser função pura de t; medir no build()
Barra treme e para de subir	draw escrevia style.transform no mesmo elemento que o GSAP anima. Tremida vai num filho (#rbInner)
Elemento escondido nunca aparece no render	fromTo com opacity: 1 só no "de". Pôr opacity: 1 também no destino
Pílula da legenda invisível	z-index: -1 sem contexto de empilhamento. isolation: isolate na palavra
Quadro de prova no instante errado	--at do snapshot é tempo da linha do tempo esticada. Usar quadros.sh, que multiplica pelo SLOW
Anéis no zoom final	8 amostras não bastam para escala exponencial. SLOW = 16 (e data-duration junto)
Cor de referência filmada parece outra	câmera filmando uma tela estoura a cor. Usar a cor de origem, não a amostra
Quadros de prova todos iguais (só o fundo)	a ferramenta fotografou antes do build() terminar. O quadros.sh já espera 20 s
Render lento ou travando	partes temporárias em pasta sincronizada. Os scripts usam MOTION_TMP ou a pasta temporária do sistema
Render pede dezenas de GB de disco	captura paralela gravando cada quadro. O render-faisca.sh já liga HF_CAPTURE_PARALLEL_STREAM=true
className ou textContent não mudam pelo GSAP	o GSAP 3 não aplica essas propriedades por set. Mudar no draw(t), como função de t
Elemento centralizado com translateX(-50%) sai do lugar	a escala do GSAP reescreve o transform. Centralizar com xPercent: -50