HuanEnzie/agent-build-effect

AgentBuild: 30 agentes de IA constroem a página diante dos olhos do visitante

Efeito de entrada: cada bloco da página fica oculto atrás de um wireframe, enquanto cursores com nomes voam, selecionam a área e "constroem" aquele bloco. Usa apenas DOM e CSS transition (sem canvas, sem bibliotecas), com 30 cursores que consomem recursos quase zero.

Arquivos em assets/:

Arquivo	Quando usar
agent-build.js	Núcleo. Use com <script> (cria window.AgentBuild) ou import em bundler (CommonJS).
agent-build.css	Obrigatório, acompanha o núcleo. Altere cores com variáveis --ab-*.
agent-build.d.ts	Tipos TypeScript para o núcleo.
AgentBuild.tsx	Wrapper React/Next (client component).
demo.html	Página de demonstração que roda sozinha, abra diretamente no navegador.

Como integrar

HTML comum

1. Copie agent-build.js e agent-build.css para o projeto.
2. Inclua o CSS no <head>, o script no final do <body>, e chame start após o conteúdo estar no DOM:

<link rel="stylesheet" href="agent-build.css" />
<script src="agent-build.js"></script>
<script>
  AgentBuild.start({
    root: "main",                       // área a ser construída; cursores ficam dentro dela
    targets: "main h1, main p, .card",  // blocos, em ordem de prioridade
    seenKey: "home",                    // uma chave por página
    labels: { status: "{agents} agentes · {edits} edições", building: "Construindo página", done: "Construída", skip: "Pular" },
  });
</script>

React / Next.js (App Router)

1. Copie agent-build.js, agent-build.d.ts, AgentBuild.tsx para o mesmo diretório, ex.: src/components/agent-build/.
2. Importe agent-build.css uma vez no stylesheet comum (@import "../components/agent-build/agent-build.css";).
3. Coloque o componente como primeiro filho da área a ser construída. O componente usa o elemento pai como root:

<div className="landing">
  <AgentBuild targets=".landing h1, .landing p, .card" seenKey="landing" />
  ...
</div>

Páginas renderizadas no servidor funcionam porque o componente só roda no cliente, e oculta os blocos em useLayoutEffect (antes da primeira pintura), evitando piscadas de conteúdo.

Escolha targets corretamente

Esta parte define se o efeito fica bonito ou confuso.

• Escolha blocos com significado: título, parágrafo, botão, cartão, imagem. Não selecione div que envolve uma seção inteira, pois um wireframe gigante parece um erro.
• Liste em ordem de prioridade. Elementos dentro de um já selecionado serão ignorados automaticamente. Exemplo: se selecionou .card, o p dentro do cartão não será construído separadamente. Se quiser construir o cartão inteiro, coloque .card antes de p.
• Pule áreas com efeitos próprios (texto animado com scroll, canvas) com skipInside: ".tagline".
• Elementos com largura ou altura zero no início serão ignorados.
• Cerca de 30 a 140 blocos fica bom. maxTargets padrão é 140.
• Se o projeto já tem efeitos de "aparecer ao scroll", desligue-os durante a execução dos agentes, senão os efeitos se sobrepõem. Exemplo: [data-agent-build] .reveal { opacity: 1; transform: none; transition: none; } (o atributo data-agent-build é adicionado ao root durante a execução).

Opções

Opção	Padrão	Significado
root	document.body	Elemento ou seletor. Receberá position: relative durante a execução.
targets	h1, h2, h3, p, img, figure, li, button, .card	Lista de blocos.
count	30 (16 em telas menores que 640px)	Número de agentes.
once / seenKey	true / "agent-build"	Cada aba executa apenas uma vez.
forceParam	"agents"	Adicione ?agents à URL para forçar reexecução, útil para gravar vídeos.
respectReducedMotion	true	Não executa se o usuário ativar redução de movimento.
pill	true	Barra de status com botão Pular.
labels	inglês	status (com {agents}, {edits}), building, done, skip.
colors, roles	8 cores, 10 funções	Cores e nomes dos agentes (layout-07).

start() retorna { skip(), destroy(), started }. destroy() restaura a página ao estado original. Chame-a ao sair da página (SPA) ou ao desmontar o componente.

Altere a aparência com variáveis CSS: --ab-wire (cor do wireframe), --ab-pill-bg, --ab-pill-text, --ab-pill-muted, --ab-mono, --ab-ease.

Teste numericamente, sem precisar de capturas contínuas

Use Playwright para abrir a página com ?agents, então leia:

({
  cursors: document.querySelectorAll(".ab-cursor:not([data-hidden])").length, // ~30 no início
  waiting: document.querySelectorAll('[data-ab="wait"]').length,              // diminui ao scroll
  on: !!document.querySelector("[data-agent-build]"),                          // false quando terminar
})

Role com window.scrollTo em passos (não use mouse.wheel se a página tiver Lenis smooth scroll), espere alguns segundos. Resultado correto: waiting chega a 0 e on fica false. Teste o botão Pular: clique .ab-skip; depois disso, não deve haver [data-ab]. Capture apenas uma imagem quando precisar avaliar o visual.

Erros comuns

• Wireframe ou cursor desalinhado: root não engloba todos os blocos. Escolha um root que contenha todos os targets.
• Imagem fill (Next/Image) cobrindo a página: não é erro desta skill. O pai da imagem fill precisa ter position: relative.
• Efeito não executa novamente: já rodou uma vez na aba. Adicione ?agents à URL ou abra uma nova aba.
• React StrictMode (dev executa efeito duas vezes): o núcleo só marca "executou" após 1,2 segundos, então a segunda montagem roda normalmente.