~/discoveries/work 2026-11-21

A revelação de tema que pulava no final

Uma revelação circular de tema terminava e a página então pulava para o visual final. A causa era estado do React mudando dentro de startViewTransition sem flushSync, e virou um lint.

O sintoma

Um console web tinha um tema claro e uma troca desenhada como uma íris: um círculo se abrindo a partir do clique. A revelação rodava, terminava e a página mudava mais uma vez. O dono descreveu como um soluço e disse que acontece com frequência. Foi registrado como uma issue nos registros do projeto em 2026-11-21.

A causa

`document.startViewTransition(callback)` tira um snapshot da página antiga, executa o callback, tira um snapshot da página nova e anima entre os dois. O navegador assume que o DOM é final quando o callback retorna.

No React, uma atualização de estado dentro desse callback não está commitada quando o callback retorna. Ela está agendada. O navegador tira snapshot de uma página que ainda não mudou, toca a animação até ela e o React então commita a mudança real depois. O usuário vê a transição terminar e depois a página se mover.

Antes e depois, como registrado na entrada do catálogo do lintts
// before: the new snapshot is taken before React commits
document.startViewTransition(() => draw(next));

// after
document.startViewTransition(() => flushSync(() => draw(next)));

`flushSync` força o commit dentro do callback, de modo que o snapshot é da página finalizada. A correção é um wrapper. O código parece correto, e por isso essa classe é fácil de escrever de novo.

Da correção ao lint

O learning loop do time diz que uma classe recorrente de erro vira um guard, depois que o dono confirma. Esta era uma classe com nome: estado do React alterado dentro de um callback de view transition sem flushSync. O guard mais barato que serve é uma regra do Semgrep no repositório de regras compartilhadas, que todo projeto já executa.

  • Ele reporta `startViewTransition` em qualquer receptor, e a forma `{ update }`, em um módulo que importa React.
  • Só quando o callback é uma função inline sem `flushSync(`, sem `new Promise` e sem `await`.
  • Um callback passado por nome não é reportado, porque um padrão não enxerga dentro dele.
  • Um módulo sem React não é reportado. A forma preferida é uma troca só com CSS, e a mensagem diz isso.

Os testes da regra têm cinco casos que devem ser reportados e nove que não, dois deles em um módulo sem React. Sem o escopo de React, esses dois são reportados, e é assim que sei que o escopo importa. Rodada sobre os checkouts locais da organização, os únicos outros callbacks inline eram dois helpers de transição de página que devolvem uma promise resolvida depois que a rota renderiza; a exceção de Promise e await existe por causa deles.

Em que pé está

A entrada do catálogo diz que a regra está em revisão no repositório de regras compartilhadas, para ser lançada como a tag `v0.2.0`, e que nenhum projeto a fixa ainda. Um projeto a ativa movendo um pin no seu comando de check.

Uma ressalva honesta. A entrada diz que o dono pediu o lint no mesmo dia, quando a correção em si ainda não tinha sido confirmada. O learning loop quer uma confirmação antes de um guard. Aqui o lint foi pedido explicitamente, então leio isso como aquele sim, mas o registro mantém a distinção.

Uma segunda regra do mesmo padrão, a de que a revelação deve terminar além da tela com uma curva in-out, não tem lint. É um teste unitário na função de raio do projeto, porque um padrão não conseguiria seguir o helper sem ruído. Escolher qual guard serve faz parte do trabalho: uma regra barulhenta demais é desligada.