~/discoveries/work 2026-11-21

A animação de 1 ms que nunca terminou

Um terminal digitado neste site deixou 148 de 430 glifos invisíveis, embora o navegador reportasse todas as animações como concluídas. A correção, a medição e uma segunda pegadinha com calc() e var().

  • css
  • animation
  • debugging
  • chromium

Sintoma

A página inicial tem um terminal que digita sozinho. Para obter uma revelação por caractere sem timers de JavaScript, cada glifo é um span com sua própria animação CSS, atrasada de acordo com o índice. Na minha máquina parecia certo e nas outras errado: alguns caracteres nunca apareciam.

Contei em vez de confiar nos meus olhos. Depois do carregamento, 148 de 430 glifos tinham opacidade calculada 0. O estranho é que element.getAnimations() reportava essas mesmas animações como concluídas.

O código que falhou

antescss
.type-glyph {
  opacity: 0;
  animation: type-glyph 1ms steps(1) var(--d) forwards;
}

@keyframes type-glyph {
  to { opacity: 1; }
}

O estilo base esconde o glifo. A animação deveria torná-lo visível depois do atraso e manter esse valor com forwards. Uma duração de um milissegundo com um único passo parecia a forma mais barata de dizer "ligue no tempo d".

Como medi

A checagem é um script curto executado na página depois do carregamento. Ele percorre cada glifo, lê a opacidade calculada e conta os que ainda estão em 0. Também compara isso com o estado da animação. Este é o formato, não um arquivo de teste do repositório.

js
const glyphs = [...document.querySelectorAll(".type-glyph")];
const hidden = glyphs.filter((g) => getComputedStyle(g).opacity === "0");
const finished = glyphs.filter((g) =>
  g.getAnimations().every((a) => a.playState === "finished"),
);
console.log({ total: glyphs.length, hidden: hidden.length, finished: finished.length });

Antes da correção isto imprimia 430 no total e 148 ocultos, com as animações reportadas como concluídas. Uma animação concluída com resultado oculto significa que o estado final da animação não foi aplicado ao estilo calculado.

A correção

depoiscss
.type-glyph {
  animation: type-glyph 40ms linear var(--d) both;
}

@keyframes type-glyph {
  from { opacity: 0; }
}
  • Sem opacidade base. O elemento é visível por padrão, então um glifo nunca fica preso oculto por falta de um efeito de animação.
  • O keyframe anima do valor oculto até o valor do próprio elemento, então o estado de repouso é o estilo normal, não um valor preenchido para a frente.
  • both também preenche para trás, o que mantém o glifo oculto durante o atraso.
  • 40 ms linear em vez de 1 ms steps(1). A revelação é um fade curto, não um interruptor.

Mesmo script, mesma página: 0 de 430 ocultos.

Causa, como hipóteses. Não verifiquei nada disso no código-fonte do Chromium. Uma: com duração de 1 ms e muitas animações começando nos mesmos frames, uma animação pode chegar ao fim entre atualizações de estilo, e um fill forwards do keyframe final pode não ser aplicado sobre a base opacity: 0. Duas: a base opacity: 0 e um fill forwards são duas declarações separadas que precisam vencer na cascata, e removi essa dependência em vez de provar qual lado perdia. A correção funciona; a explicação é um palpite.

Uma segunda pegadinha, no mesmo dia

A digitação linha a linha usava uma animação por linha, com a duração calculada a partir da contagem de caracteres.

css
.type-line {
  animation: type calc(var(--chars) * var(--type-step, 20ms)) steps(var(--chars), end) var(--delay, 0ms) both;
}

Uma linha de 10 caracteres tinha --type-step: 90ms definido inline no mesmo elemento, então esperei 0.9 s. A animation-duration calculada foi 0.2 s, que é 10 vezes o fallback de 20 ms. A custom property inline foi ignorada dentro daquele calc().

contornotsx
<span
  className="type-line"
  style={{ "--chars": text.length, animationDuration: `${text.length * 90}ms` }}
>

Definir animationDuration inline deu 0.9 s. Como antes, não sei a causa raiz. Minhas hipóteses são um problema de ordem entre a substituição de var() do shorthand e a propriedade inline, ou um valor com unidade chegando ao calc() como o fallback. Nenhuma foi verificada.

O que eu faria da próxima vez

  • Confiar no estilo calculado, não em getAnimations(). O primeiro disse que 148 glifos estavam ocultos; o segundo disse que estava tudo bem.
  • Fazer do estado padrão o visível, e deixar a animação tirar coisas, não acrescentar.
  • Evitar durações menores que um frame. A 60 Hz um frame tem cerca de 16.7 ms, então 1 ms pede um efeito que a página não consegue mostrar.
  • Quando um valor é calculado a partir de uma custom property e sai como o fallback, definir o valor final inline e seguir em frente.