ONIKOSIOLA/kit-de-edição-de-vídeo

Portões de Qualidade HyperFrames

Visão Geral

A diferença entre uma ótima execução HyperFrames e uma medíocre não é a criatividade — é a disciplina de verificação. Execuções excelentes tratam cada quadro como não comprovado até que seus pixels tenham sido inspecionados em múltiplos momentos. Execuções medíocres confiam no verificador e entregam a primeira coisa que passa no lint.

Princípio central: o linter verifica retângulos e atributos; apenas os pixels renderizados contam a verdade. Nunca declare um quadro como concluído sem vê-lo.

Portões inegociáveis

Trabalhe nestes EM ORDEM para cada quadro que você construir ou editar. Pular um portão porque "é uma mudança pequena" é como a qualidade cai.

1. Leia o bloco ## Direção de vídeo do próprio storyboard e obedeça-o em vez do boilerplate predefinido. Quando o storyboard diz letras minúsculas e o frame.md predefinido diz maiúsculas, o storyboard vence. Direção do projeto > padrões predefinidos.
2. Um movimento dominante por quadro. Se seu quadro tiver dois elementos se resolvendo ao mesmo tempo, corte um. Tanto o carregamento frontal de tudo seguido de congelamento ("modo slideshow") quanto tudo flutuando ("modo screensaver") são falhas.
3. Auto-verifique as armadilhas mecânicas (tabela abaixo) pesquisando em seu próprio arquivo antes de declará-lo concluído.
4. Faça o seek-test em um navegador antes de relatar como concluído. Clone o <template>, registre a linha do tempo e timeline.seek(t, false) em: t=0, cada limite de cena ±0,05s, e o quadro final. Capture a tela de cada um. OLHE para eles. Um relatório de quadro sem um seek-test é uma afirmação não verificada.
   • Armadilha suppressEvents: .seek(t) simples suprime callbacks onUpdate — contadores/digitação parecem quebrados em seu ambiente de teste mas funcionam bem no renderizador. Sempre passe false.
5. Após QUALQUER reajuste, recalcule data-start/data-duration nos clipes afetados. Tempos de tween GSAP e janelas de visibilidade de clipe são dois sistemas separados; reajustar um sem o outro cria elementos invisíveis ou lacunas de silêncio. Esta é a fonte #1 de regressões.
6. Após a montagem, capture um snapshot do vídeo completo em cada limite de corte e no ponto médio de cada quadro, e leia a imagem da folha de contato você mesmo. Corrija o que parecer errado, faça novo snapshot, só então renderize.

Tabela de armadilhas mecânicas (pesquise estas em seu próprio arquivo)

Armadilha	Sintoma	Correção
id começa com dígito + querySelector("#...")	SyntaxError mata silenciosamente o registro da linha do tempo → quadro em branco	Prefixe ids com uma letra, ou use getElementById primeiro
CSS transform: em um elemento animado pelo GSAP	GSAP sobrescreve o deslocamento CSS no primeiro tween	Incorpore o deslocamento em left/top; transformações pertencem apenas ao GSAP
Ausência de box-sizing: border-box em cartões com padding	Larguras inflam, centralização desvia, cartões colidem	Defina-o em cada cartão com padding
@font-face apontando para fonts.gstatic.com / qualquer CDN	Renderização não determinística; quebra offline	Arquivos locais em assets/fonts/, relativos à raiz do projeto
Sobreposição calculada a olho	Cartões posteriores enterram o texto dos cartões anteriores	Calcule retângulos com getBoundingClientRect() no tempo de espera; verifique se o texto CHAVE de CADA elemento empilhado está visível em uma captura de tela
Resultados de sobreposição do verificador em texto com espaçamento apertado/cortado	Falso positivo (retângulos se sobrepõem, glifos não)	Verifique pixels primeiro, depois data-layout-allow-overlap — nunca suprima cegamente
Captura de tela esticada/recolorida em maquete de telefone	Dispositivo estranho	Proporção nativa sempre; corte com overflow:hidden, nunca escale não uniformemente
Arquivos ._* AppleDouble em volumes externos	Quebra builds/renderizações	find . -name '._*' -delete antes de montar/renderizar
Node < 22	CLI falha	Prefixo: export PATH="$HOME/.nvm/versions/node/v22*/bin:$PATH" (ou nvm use 22)

Padrão de orquestração (builds com múltiplos quadros)

• Um worker por quadro, um arquivo por worker; workers nunca tocam em arquivos compartilhados.
• Prepare assets compartilhados (fontes, logos, capturas de tela) ANTES de despachar workers; pacotes nomeiam caminhos exatos.
• Cada pacote carrega: o bloco do storyboard do quadro na íntegra, o bloco global de Direção de Vídeo, a tabela de armadilhas acima e o requisito de seek-test.
• O orquestrador reexecuta lint + verificação + inspeção da folha de contato após a montagem, independentemente do que os workers relataram — auto-relatos de workers são afirmações, não provas.

Bandeiras vermelhas — pare e verifique

• "Lint e verificação passaram, então o quadro está correto" → verificações não veem texto enterrado ou silêncio. Olhe para os pixels.
• "Eu reajustei os tweens; pronto" → você reajustou as janelas data-* do clipe também?
• "Vou pular o seek-test, o código é direto" → o bug do quadro em branco (seletor de id com dígito) estava em código direto e apenas um seek-test o pegou.
• "O cartão provavelmente não cobre o outro" → calcule os retângulos; depois capture a tela.
• "Fonte CDN está tudo bem só desta vez" → não está; renderizações devem ser livres de rede.

Todos estes significam: execute o portão que você estava prestes a pular.