HuanEnzie/agent-build-effect

AgentBuild: 30 agentes AI construyen la página ante los ojos del espectador

Efecto de entrada: cada bloque de la página está oculto tras un marco de puntos, una bandada de cursores con nombre vuela hacia ellos, arrastra un marco de selección y 'construye' ese bloque. Solo usa DOM y transiciones CSS (sin canvas, sin librerías), 30 cursores apenas consumen recursos.

Archivos en assets/:

Archivo	Úsalo cuando
agent-build.js	Núcleo. Se usa con <script> (crea window.AgentBuild) o import en bundler (CommonJS).
agent-build.css	Obligatorio, viene con el núcleo. Cambia colores con variables --ab-*.
agent-build.d.ts	Tipos TypeScript para el núcleo.
AgentBuild.tsx	Envoltorio React/Next (componente cliente).
demo.html	Página de ejemplo autocontenida, ábrela directamente en el navegador.

Cómo integrarlo

Web HTML normal

1. Copia agent-build.js y agent-build.css en tu proyecto.
2. Pon el CSS en <head>, el script al final de <body>, y llama a start después de que el contenido esté en el DOM:

<link rel="stylesheet" href="agent-build.css" />
<script src="agent-build.js"></script>
<script>
  AgentBuild.start({
    root: "main",                       // zona a construir; la capa de cursores está dentro de esta zona
    targets: "main h1, main p, .card",  // los bloques, en orden de prioridad
    seenKey: "home",                    // una clave por página
    labels: { status: "{agents} agentes · {edits} ediciones", building: "Construyendo página", done: "Construcción completada", skip: "Omitir" },
  });
</script>

React / Next.js (App Router)

1. Copia agent-build.js, agent-build.d.ts, AgentBuild.tsx en el mismo directorio, por ejemplo src/components/agent-build/.
2. Importa agent-build.css una vez en tu hoja de estilos global (@import "../components/agent-build/agent-build.css";).
3. Coloca el componente como primer hijo de la zona a construir. El componente toma el elemento padre como raíz:

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

La página renderizada del lado del servidor sigue funcionando porque el componente solo se ejecuta en el cliente y oculta los bloques en useLayoutEffect (antes del primer pintado), por lo que no hay destello de contenido.

Selecciona targets correctamente

Esta es la parte que determina si el efecto se ve bien o es confuso.

• Elige bloques con significado: títulos, párrafos, botones, tarjetas, imágenes. No selecciones un div que envuelva toda una sección, porque un marco enorme parece un error.
• Enuméralos en orden de prioridad. Los elementos que están dentro de un elemento ya seleccionado se ignoran automáticamente. Por ejemplo, si ya seleccionaste .card, los p dentro de la tarjeta no se construirán por separado. Si quieres construir tanto la tarjeta como su contenido, pon .card antes que p.
• Omite zonas que ya tienen su propio efecto (texto que se mueve con scroll, canvas) con skipInside: ".tagline".
• Los elementos con ancho o alto igual a 0 al inicio se ignoran.
• Entre 30 y 140 bloques se ve bien. maxTargets por defecto es 140.
• Si el proyecto ya tiene un efecto de 'aparición al hacer scroll', desactívalo mientras los agentes estén activos, de lo contrario ambos efectos se solaparán. Por ejemplo: [data-agent-build] .reveal { opacity: 1; transform: none; transition: none; } (el atributo data-agent-build se añade a la raíz durante la ejecución).

Opciones

Opción	Valor por defecto	Significado
root	document.body	Elemento o selector. Se le asigna position: relative durante la ejecución.
targets	h1, h2, h3, p, img, figure, li, button, .card	Lista de bloques.
count	30 (16 en pantallas menores de 640px)	Número de agentes.
once / seenKey	true / "agent-build"	Solo se ejecuta una vez por pestaña.
forceParam	"agents"	Añade ?agents a la URL para forzar la ejecución de nuevo, útil para grabar videos.
respectReducedMotion	true	No se ejecuta si el usuario tiene activada la reducción de movimiento.
pill	true	Barra de estado con botón Omitir.
labels	Inglés	status (con {agents}, {edits}), building, done, skip.
colors, roles	8 colores, 10 roles	Colores y nombres de agentes (layout-07).

start() devuelve { skip(), destroy(), started }. destroy() restaura la página a su estado original. Llámalo al salir de la página (SPA) o al desmontar el componente.

Cambia la apariencia con variables CSS: --ab-wire (color del marco de puntos), --ab-pill-bg, --ab-pill-text, --ab-pill-muted, --ab-mono, --ab-ease.

Pruebas mediante números, sin necesidad de capturas continuas

Usa Playwright para abrir la página con ?agents y luego lee:

({
  cursors: document.querySelectorAll(".ab-cursor:not([data-hidden])").length, // ~30 al inicio
  waiting: document.querySelectorAll('[data-ab="wait"]').length,              // disminuye al hacer scroll
  on: !!document.querySelector("[data-agent-build]"),                          // false cuando termina
})

Haz scroll con window.scrollTo paso a paso (no uses mouse.wheel si la página tiene Lenis smooth scroll), espera unos segundos. Resultado correcto: waiting llega a 0 y on se vuelve false. Prueba el botón Omitir: haz clic en .ab-skip, después no debe haber ningún [data-ab]. Toma una captura solo cuando necesites evaluar la parte visual.

Errores conocidos

• Marco o cursor desalineados: la raíz no cubre todos los bloques. Elige una raíz que contenga todos los targets.
• Imagen fill (Next/Image) cubre toda la página: no es un error de este skill. El contenedor padre de la imagen fill necesita position: relative.
• El efecto no se vuelve a ejecutar: ya se ejecutó una vez en la pestaña. Añade ?agents a la URL o abre una nueva pestaña.
• React StrictMode (en desarrollo ejecuta el efecto dos veces): el núcleo solo registra 'ya se ejecutó' después de 1,2 segundos, por lo que el segundo montaje se ejecuta normalmente.