HuanEnzie/agent-build-effect

AgentBuild : 30 agents IA construisent la page sous les yeux du visiteur

Effet d'entrée : chaque bloc de la page est masqué derrière une maquette filaire ; une nuée de curseurs portant des noms vole jusqu'au bloc, trace une zone de sélection et le construit. Utilise uniquement le DOM et les transitions CSS (pas de canvas, pas de bibliothèque). Les 30 curseurs sont pratiquement sans ressource.

Fichiers dans assets/ :

Fichier	Quand l'utiliser
agent-build.js	Cœur. Utilisation via <script> (crée window.AgentBuild) ou import dans un bundler (CommonJS).
agent-build.css	Requis, fourni avec le cœur. Modifiez les couleurs via les variables --ab-*.
agent-build.d.ts	Types TypeScript pour le cœur.
AgentBuild.tsx	Composant React/Next (client component).
demo.html	Page de démonstration prête à l'emploi, à ouvrir directement dans un navigateur.

Comment intégrer

Web HTML standard

1. Copiez agent-build.js et agent-build.css dans votre projet.
2. Ajoutez le CSS dans <head>, le script à la fin du <body>, puis appelez start après que le contenu est présent dans le DOM :

<link rel="stylesheet" href="agent-build.css" />
<script src="agent-build.js"></script>
<script>
  AgentBuild.start({
    root: "main",                       // zone à construire ; les curseurs sont placés dans cette zone
    targets: "main h1, main p, .card",  // blocs, dans l'ordre de priorité
    seenKey: "home",                    // une clé par page
    labels: { status: "{agents} agents · {edits} modifications", building: "Construction en cours", done: "Construction terminée", skip: "Ignorer" },
  });
</script>

React / Next.js (App Router)

1. Copiez agent-build.js, agent-build.d.ts, AgentBuild.tsx dans un même dossier, par exemple src/components/agent-build/.
2. Importez agent-build.css une fois dans votre feuille de style globale (@import "../components/agent-build/agent-build.css";).
3. Placez le composant comme premier enfant de la zone à construire. Le composant utilise l'élément parent comme racine :

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

La page rendue côté serveur fonctionne toujours car le composant s'exécute uniquement côté client et masque les blocs dans useLayoutEffect (avant le premier rendu visuel), donc il n'y a pas de flash de contenu.

Choisissez targets correctement

C'est la partie qui détermine si l'effet est beau ou confus.

• Choisissez les blocs significatifs : titres, paragraphes, boutons, cartes, images. N'incluez pas une div qui enveloppe toute une section, car une grande maquette filaire ressemblerait à une erreur.
• Listez-les par ordre de priorité. Les éléments à l'intérieur d'un élément déjà sélectionné seront automatiquement ignorés. Par exemple, si vous sélectionnez .card, les p dans cette carte ne seront pas construits séparément. Pour construire toute la carte, placez .card avant p.
• Ignorez les zones qui ont déjà un effet spécial (texte animé au défilement, canvas) avec skipInside: ".tagline".
• Les éléments ayant une largeur ou hauteur de 0 au début seront ignorés.
• Entre 30 et 140 blocs donne un bel aspect. maxTargets par défaut est 140.
• Si votre projet a déjà un effet de révélation progressive au défilement, désactivez-le pendant l'exécution des agents, sinon les deux effets se superposent. Exemple : [data-agent-build] .reveal { opacity: 1; transform: none; transition: none; } (l'attribut data-agent-build est ajouté à la racine pendant l'exécution).

Options

Option	Valeur par défaut	Description
root	document.body	Élément ou sélecteur. Reçoit position: relative pendant l'exécution.
targets	h1, h2, h3, p, img, figure, li, button, .card	Liste des blocs.
count	30 (16 sur écran < 640px)	Nombre d'agents.
once / seenKey	true / "agent-build"	Exécution unique par onglet.
forceParam	"agents"	Ajoutez ?agents à l'URL pour forcer une réexécution (utile pour enregistrer une vidéo).
respectReducedMotion	true	Ne s'exécute pas si l'utilisateur a activé la réduction des mouvements.
pill	true	Barre d'état avec bouton Ignorer.
labels	Anglais	status (contient {agents}, {edits}), building, done, skip.
colors, roles	8 couleurs, 10 rôles	Couleurs et noms des agents (layout-07).

start() retourne { skip(), destroy(), started }. destroy() remet la page dans son état initial. Appelez-le en quittant la page (SPA) ou lors du démontage du composant.

Modifiez l'apparence avec les variables CSS : --ab-wire (couleur de la maquette filaire), --ab-pill-bg, --ab-pill-text, --ab-pill-muted, --ab-mono, --ab-ease.

Tests avec des nombres, sans captures d'écran répétées

Utilisez Playwright, ouvrez la page avec ?agents, puis lisez :

({
  cursors: document.querySelectorAll(".ab-cursor:not([data-hidden])").length, // ~30 au début
  waiting: document.querySelectorAll('[data-ab="wait"]').length,              // diminue au défilement
  on: !!document.querySelector("[data-agent-build]"),                          // false quand terminé
})

Défilez avec window.scrollTo par étapes (n'utilisez pas mouse.wheel si la page a un défilement fluide Lenis), attendez quelques secondes. Résultat correct : waiting passe à 0 et on à false. Testez le bouton Ignorer : cliquez sur .ab-skip, puis vérifiez qu'il n'y a plus de [data-ab]. Prenez une seule capture d'écran si nécessaire pour évaluer l'aspect visuel.

Problèmes rencontrés

• Maquettes ou curseurs décalés : la racine ne contient pas tous les blocs. Choisissez un élément racine qui englobe tous les targets.
• Image fill (Next/Image) qui couvre toute la page : ce n'est pas un problème de cette compétence. Le conteneur parent de l'image fill doit avoir position: relative.
• L'effet ne se relance pas : il a déjà été exécuté dans l'onglet. Ajoutez ?agents à l'URL ou ouvrez un nouvel onglet.
• React StrictMode (le développement exécute les effets deux fois) : le cœur enregistre « déjà exécuté » après 1,2 secondes, donc le deuxième montage s'exécute normalement.