Movimento seguro para seek
O HyperFrames não reproduz a linha do tempo. Ele a busca: para cada frame, o renderizador define a linha do tempo para o tempo daquele frame e captura a página. Com HyperFrames 0.8.x, isso é feito com três workers em paralelo, cada um pegando cada terceiro frame, e cada passo de seek recua 1 ms e depois avança para estabilizar. Então, cada frame deve ser uma função pura do seu tempo. Qualquer coisa que dependa do que foi renderizado antes, do relógio ou do acaso renderiza de forma diferente em cada worker, e o resultado é um elemento que falta em cada terceiro frame.
Esse bug é invisível na prévia do Studio (que reproduz em ordem) e em snapshots individuais. Na produção de onde essas skills vêm, foi o único defeito que chegou ao revisor: o título de abertura "tremendo e piscando" durante os primeiros sete segundos.
Lint primeiro
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/seek-safe-motion/scripts/lint_motion.py" <video_dir>/video
Ele lê index.html, src/*.tpl e os *.js ao lado deles (apenas scripts inline), imprime file:line: severity RULE: why mais a correção, e sai com código 1 em qualquer erro (--strict faz avisos falharem também, --json para ferramentas). Execute-o após cada edição na linha do tempo e antes de cada renderização. Ele é estático: não consegue ver variáveis computadas em tempo de execução (conta-as como "não verificáveis") ou duas tweens sobrepostas no tempo. Essas ficam com você, com a reprodução abaixo. qa.py (render-qa) também o executa e falha o relatório em um erro.
As regras e por que cada uma existe
- Cada chave em um fromVars de um
fromTotambém aparece em seus toVars (SS001, erro). Quando o frame de um worker cai exatamente no início de uma tween, o passo de 1 ms para trás reverte a tween para antes de começar, e uma chave que só existe em fromVars nunca é escrita novamente. A tween do título erafromTo(sel, {yPercent: 110, opacity: 1}, {yPercent: 0}):opacity: 1vivia apenas em fromVars, então um worker manteve o título com opacidade 0 pelo resto da tween. Escreva{yPercent: 110, opacity: 1}para{yPercent: 0, opacity: 1}, ou umtl.set()seguido por umtl.to(). O mesmo vale parastartAtdentro de umto()(SS002). immediateRender: falseem cadafromToapós o tempo 0 (SS003, aviso). Caso contrário, a tween escreve seus valores iniciais quando a linha do tempo é construída, sobrescrevendo o que tweens anteriores definiram, e um seek para o meio da linha do tempo começa do estado errado.- Prefira
fromToafrom(SS004, aviso). Umfrom()termina no que quer que o elemento estivesse no momento da construção; assim que tweens anteriores tocam no elemento, os workers discordam sobre isso. - Nunca anime
displayouvisibility(SS005, erro). Eles não podem ser interpolados; eles mudam abruptamente em um ponto arbitrário da tween. Altere-os com umtl.set()de duração zero em um tempo explícito, e desvaneça comopacityouautoAlpha. - Sem relógio, sem acaso, sem timers (SS006, erro): sem
Date,performance.now(),Math.random(),setTimeout,setIntervalourequestAnimationFramepara nada visível. Uma variação de digitação ou uma forma de onda usa um gerador com semente; um timer de chamada exibido na tela é calculado a partir detl.time()dentro doonUpdateda linha do tempo. - Uma linha do tempo pausada, registrada, nunca reproduzida (SS007, SS011, SS012). Crie-a com
gsap.timeline({ paused: true }), construa-a completamente (dentro dedocument.fonts.readyquando posições dependerem de métricas de texto), e só então atribuawindow.__timelines["<id da composição>"] = tl. Registrar uma linha do tempo vazia antes da construção terminar renderiza um vídeo em branco;tl.play()luta contra os seeks do renderizador. - Rolagens são
fromTocom início e fim explícitos para que cada worker calcule o mesmo deslocamento, limitado ao conteúdo real para que nenhum corte de linha ou ícone pare em uma borda. - Nunca duas tweens na mesma propriedade do mesmo elemento ao mesmo tempo. Uma reinicialização de cursor que caiu dentro do próximo movimento deixou o ponteiro no lugar errado após um seek. Não verificado pelo lint: verifique a tabela de temporização da construção.
- Anime transformações, não layout (SS009, aviso):
x,y,scale,clip-pathem vez deleft,top,width,margin. Tweens de layout recalculam fluxo a cada frame ehyperframes checkas sinaliza comogsap_non_transform_motion. Uma pequena mudança de largura em um controle de produto real (uma barra lateral expandindo) pode ser aceita quando reproduz o produto. - Nunca tween um elemento
.clip(SS010, erro). O HyperFrames gerencia a visibilidade de um clip através dedata-startedata-duration; anime um wrapper dentro dele. - Repetições finitas (SS008, aviso).
repeat: -1só é permitido sob uma raizdata-durationfinita; calcule uma contagem comMath.max(0, Math.floor(span / period) - 1). - Defina todo estado inicial explicitamente no tempo 0. Um helper que faz
gsap.set(sel, vars)também deve fazertl.set(sel, vars, 0), para que buscar de volta para 0 restaure o primeiro frame em vez de manter o último estado que um worker renderizou.
Reproduza um bug suspeito antes de renderizar
O lint encontra padrões; um snapshot prova pixels. Para uma tween suspeita começando em t0:
npx --yes hyperframes@<pinned> snapshot . --at <t0 + 0.3> --no-end --describe false -o a
npx --yes hyperframes@<pinned> snapshot . --at <t0>,<t0 + 0.3> --no-end --describe false -o b
O frame em t0 + 0.3 deve ser idêntico em a e b. Se diferir, buscar através do início da tween mudou o estado. Para reproduzir exatamente um worker, tire snapshots dos frames 0, 3, 6, ... nessa ordem até logo após a tween. Faça bisseção dividindo o intervalo de tempo pela metade até que reste uma tween. Após renderizar, scan_render.py (render-qa) reporta o mesmo bug como uma execução WORKER PATTERN: frames discrepantes que compartilham um índice de frame mod 3.
Referências
references/patterns.md: código antes e depois para cada regra, os helpers que mantêm um template seguro (lineIn,init, digitação, rolagens, cliques de cursor) e o que o lint pode e não pode ver. Leia ao escrever um novo helper ou corrigir um achado do lint.