Kiskujab/page-swarm-rebuild

Que fait page-swarm-rebuild ?

Version 1.3.0 (module, add-on, feuille de style et ce fichier ; voir CHANGELOG.md dans le dépôt ; SwarmRebuild.version).

Effet d'introduction, uniquement visuel. Le DOM réel de la page n'est jamais modifié : les couches sont cachées et révélées à l'aide d'une feuille de style en cascade dans <head>, toute l'animation se déroule dans une superposition ajoutée à <html>, et les deux sont supprimées à la fin. Aucune dépendance, aucune requête réseau (respectueux du RGPD), aucun changement de mise en page, aucun son, et la page n'est jamais laissée à moitié cachée (voir Protection).

Spécification de l'effet original (chronologie, visuels, HUD, courbe de défilement) : references/effekt-leiras.md (hongrois). En cas de désaccord entre ce fichier et cette spécification, ce fichier prévaut (des décisions produit ont été prises après la rédaction de la description).

Fichiers

Fichier	Objectif
assets/swarm-rebuild.js	Le module, source lisible (script classique, définit window.SwarmRebuild ; également importable depuis un bundler).
assets/swarm-rebuild.min.js, swarm-rebuild-debug.min.js, swarm-rebuild.min.css	Builds minifiés pour les sites HTML simples (scripts/build-min.cjs ; l'installateur les utilise ; les bundlers minifient eux-mêmes les sources).
assets/swarm-rebuild.css	Styles de la superposition, tous limités à #swarm-rebuild-root.
assets/swarm-rebuild-debug.js	Add-on de débogage : barre de contrôle, visite automatique, hooks de test. Jamais chargé pour les visiteurs ; chargé uniquement avec ?rebuild-debug=1 / debug: true. Installez-le à côté du module quand même (c'est ainsi que vous testez sur le site en direct).
assets/react/SwarmRebuild.jsx	Wrapper client React / Next.js + <SwarmRebuildHead /> (extrait pré-rendu) ; l'add-on de débogage est un morceau paresseux séparé.
assets/demo/	Démo fictive de portfolio sombre (assets/demo/index.html, 214 couches (desktop), 6,6 hauteurs de viewport, en-tête sticky).
tests/index.html	Liens vers chaque page de test dans chaque mode (également page de démarrage GitHub Pages).
tests/pages/dental/	Cabinet dentaire fictif : thème clair, liens téléphoniques, barre fixe "Appelez-nous" + réservation (mobile), avis fixe (desktop).
tests/pages/lang-*/	Pages fictives en hongrois, arabe (de droite à gauche), japonais et une page riche en emojis (saisie dans n'importe quelle langue).
tests/pages/law/, accounting/, bootstrap/, spa/	Schémas réels fictifs : polices web, en-tête sticky, bannières de consentement, iframe, images paresseuses, mode sombre, page longue, défilement-révélation, Bootstrap (npm), application monopage, vidéos.
tests/pages/nextjs/	Application Next.js 15 App Router fictive : compteur React (vérification d'hydratation), bouton d'aide fixe.
scripts/verify.cjs	Vérification Playwright d'une page (voir étape 4).
scripts/run-tests.cjs	Exécute verify.cjs sur les trois pages de test, desktop et mobile ; affiche un tableau récapitulatif.
scripts/bench-fps.cjs	Fréquence d'images d'une version plus ancienne du module par rapport à la version actuelle, même machine, exécutions entrelacées.
scripts/build-site.cjs	Construit les trois pages de test en un seul site statique (GitHub Pages) ou le sert sur le réseau local.
scripts/next-app.cjs	Assistant : prépare / construit l'application de test Next.js dans un dossier temporaire.
scripts/build-min.cjs	Construit les fichiers .min et vérifie le budget de taille (nécessite terser et csso depuis npm).
scripts/perf.cjs	Métriques Lighthouse (LCP, CLS, TBT, Speed Index, accessibilité, SEO) avec et sans l'effet.
scripts/sync-snippet.cjs	Copie l'extrait de tête du module dans le wrapper React, SKILL.md et les pages de test.
scripts/record-video.cjs	Enregistre l'effet en .mp4 / .webm pour un portfolio (la visite de débogage, barre de contrôle cachée).
scripts/project.cjs	Installe l'effet dans un projet avec une sauvegarde dans legacy/, le supprime, restaure les originaux.
scripts/test-project.cjs	Teste l'installateur : sauvegarde, restauration après un projet cassé (hash identique), désinstallation.

Décisions produit (elles prévalent sur la vidéo de référence)

• Le mode principal est scroll (par défaut) : la construction suit le défilement du visiteur, et seul ce qui est visible est jamais construit : un élément commence lorsque au moins 60 % de sa hauteur est à l'écran (buildVisible), rien n'est construit en dessous ou au-dessus du viewport, et aucun agent en activité ne quitte jamais l'écran.
• Les visiteurs ne voient jamais de barre de contrôle et n'obtiennent jamais de défilement automatique. La barre et la visite se trouvent dans l'add-on de débogage, chargé uniquement avec ?rebuild-debug=1 ou debug: true. mode: 'tour' sans l'add-on revient à scroll.
• Toujours une issue sans contrôles visibles : Échap, Tab, Entrée, toute autre touche (à l'exception de Maj/Ctrl/Alt/Meta seuls) et tout clic ou tap affichent la page finie immédiatement, sans animation et sans changement de mise en page. prefers-reduced-motion signifie aucun effet (WCAG 2.2.2).
• Les touches de défilement défilent : Espace, les flèches, Page précédente / suivante et Début / Fin (avec le focus sur la page elle-même, sans Ctrl / Alt / Meta) pilotent la construction exactement comme la molette de la souris. Sur un lien, un bouton ou un champ ciblé, ou avec un modificateur, elles mettent fin à l'effet comme toute autre touche. Tab, Entrée et Échap y mettent toujours fin, donc les utilisateurs du clavier atteignent le contenu réel (et son ordre de tabulation) dès leur première tabulation.
• Le clic qui met fin à l'effet ne fait jamais quelque chose que le visiteur n'a pas vu : s'il atterrit sur un contenu qui n'était pas encore fini (caché, ou encore en cours de construction), il est avalé (preventDefault + stopPropagation, sur la souris déjà au pointerdown, donc pas de focus, pas de lien, pas d'action sur le bouton). S'il atterrit sur un contenu fini (visible, rien à l'intérieur ou le révélant encore en cours — par exemple un lien téléphonique, qui est affiché dès le début, ou un bouton construit), il passe comme un clic normal et l'effet se termine en même temps. Raison : avaler chaque clic ferait échouer un lien "Appelez-nous" visible au premier tap ; laisser passer chaque clic suivrait des liens que le visiteur n'a jamais vus. Le défilement tactile et la barre de défilement ne mettent jamais fin à l'effet (le défilement est ainsi que la construction est pilotée).
• Pas de son. Le module n'a aucun code audio.

Modes

mode	vitesse	comportement
scroll (par défaut)	3x	Pas de défilement automatique. Les agents construisent uniquement ce qui est visible : un élément commence lorsque au moins buildVisible (60 %) de sa hauteur est à l'écran ; un élément plus grand que l'écran lorsqu'il remplit 60 % de l'écran, il est donc construit de haut en bas au fur et à mesure de son entrée. Rien n'est construit en dehors du viewport et un agent en activité ne le quitte jamais (un cadre plus grand que l'écran est tiré depuis le bord de l'écran). Après un défilement rapide (molette, touches, Début / Fin), la partie visible est remplie en ~1-2 s : ces couches commencent en premier, plus d'agents se joignent (jusqu'à 8 au-dessus du plan) et les tâches s'exécutent plus rapidement. Ce qui quitte le viewport est final immédiatement (voir Protection).
fast	6x	Identique à scroll, deux fois plus rapide.
tour (débogage uniquement)	1x	Défilement automatique comme dans la vidéo de référence : ~couches/7 secondes, la caméra suit le front de travail, se termine en bas avec l'anneau de curseurs. Pour les enregistrements et les vérifications côte à côte. ?rebuild-speed=6 donne l'ancienne "rapide" (un défilement automatique 6x, ~9 s sur la démo). Le défilement manuel cède la main au visiteur ; le bouton Tour de la barre reprend.

Après la construction, les essaims se rassemblent autour de l'élément de focus et la superposition disparaît après autoExit secondes (3 s ; avec l'add-on de débogage 6 s, jamais en mode tour).

Mouvement

Tout est subtil par défaut et défini avec motion (voir Configurer) ; ?rebuild-motion=arc:0,... désactive certaines parties pour les tests A/B (add-on de débogage).

• Élément de focus (focus) : l'ouverture et le final essaiment autour de lui. Demandez au développeur (étape 1). Dans chaque phase, le premier de ces éléments qui est au moins à moitié visible est utilisé : le(s) élément(s) configuré(s), [data-swarm-focus], h1, un bouton principal (a.btn, .button, .cta, button[type=submit] ...), le logo ; ensuite la plus grande image visible ; puis un point dans le viewport. Ainsi, un focus loin dans la page (par exemple un appel à l'action de clôture) sert le final, et l'ouverture utilise le titre principal.
• Essaims : les agents libres volent en 2 à 4 essaims de tailles nettement différentes (téléphones : 2). Chaque agent est attiré par un ressort amorti vers sa place dans son essaim ; les centres des essaims se déplacent sur une ellipse autour de l'élément de focus dont le rayon respire et dont le rythme change, de sorte que les agents accélèrent et ralentissent par eux-mêmes et ne tournent jamais sur un cercle parfait. L'ouverture commence déjà en essaims (elle dure bien moins d'une seconde pour les visiteurs).
• Agents au repos (pendant la construction, un agent sans travail) : il quitte son essaim pour son propre point dans le viewport, à au moins 72 px de tout autre agent au repos (jamais un amas de curseurs qui se chevauchent), dérive lentement et disparaît après 1,4 s ; il réapparaît là où il se repose lorsqu'il reçoit sa prochaine tâche. Au final, tous reviennent et se rassemblent en essaims autour du focus. Mesuré : au plus 2 curseurs au repos qui se chevauchent dans 99,6 à 100 % des images (1,2 : une médiane de 6 et jusqu'à 20 sur la démo).
• Final : un ressort raide et sous-amorti (amortissement 0,63, motion.spring) attire chaque agent vers le focus : le plus rapide au début, environ 5 à 20 % au-delà de sa place, puis en arrière ; après ~1 s, le ressort s'adoucit et les essaims tournent lentement.
• Souris (ouverture et final, desktop uniquement ; jamais au toucher, jamais avec mouvement réduit) : un agent près du pointeur s'écarte de son chemin (plus fortement lorsque le pointeur arrive vite) ; jusqu'à 3 agents curieux le suivent alors sur un petit cercle, 1,3 à 2 s lorsqu'il reste, plus court plus il s'éloigne vite (l'intérêt diminue à (1 + vitesse / 220 px/s) fois le taux de base). Jamais plus près que 36 px (une limite stricte, donc les icônes ne se chevauchent jamais) ; la superposition ignore les événements de pointeur, donc les clics ne sont jamais perturbés.
• Gravité : un agent porte l'élément sur lequel il travaille, donc son chemin là-bas (et une copie clonée transportée) se plie vers le bas : affaissement = 0,2 x distance horizontale x poids x horizontalité², poids = sqrt(zone) / 320 px limité à 0,2..1, au maximum 56 px et un cinquième de la distance horizontale. Un déplacement vertical ne se plie guère. Le chemin vers une tâche commence également avec la vitesse actuelle de l'agent (courbe cubique d'Hermite), donc il n'y a pas d'arrêts ou de virages brusques.
• Difficulté : le travail de chaque tâche (pas le chemin là-bas) est mis à l'échelle par une difficulté provenant de la zone de l'élément (pour la saisie : la boîte dans laquelle on tape) : près de la moyenne de la page 2x la zone ~ 1,6-1,8x le temps, écrasé (tanh) donc la tâche la plus difficile prend au maximum ~4x la plus facile. Il est normalisé (pondéré par la longueur de la tâche et la difficulté, car les tâches parallèles font que les longues donnent le rythme) donc toute la construction prend le même temps qu'avant ; seule la répartition entre les petites et les grandes change.
• Lite (motion.lite: 'auto') : sur les téléphones 2 essaims et aucun jeu de souris ; lorsque la fréquence d'images reste inférieure à 38 ips pendant deux secondes pendant la construction, également un fantôme de traînée au lieu de trois.

Langues et directions d'écriture

Le module ne suppose aucune langue. La saisie se fait par caractères perçus par l'utilisateur (grappes de graphèmes, Intl.Segmenter, avec un repli qui joint les marques de combinaison, les séquences ZWJ, les tons de peau, les sélecteurs de variation et les paires de drapeaux) : une lettre accentuée, une famille d'emojis, un drapeau ou une lettre avec des marques arabes / hébraïques n'est jamais divisé. Le texte non tapé reste en place comme texte caché, et les navigateurs le façonnent à travers cette frontière, donc les lettres arabes conservent leurs formes liées et rien ne se reflow. Éléments de droite à gauche (direction: rtl, par exemple <html dir="rtl">) : les cadres grandissent depuis le bord droit, les lignes sont tracées de droite à gauche, l'agent tape sur le côté gauche et le curseur se trouve à gauche de la dernière lettre tapée ; une séquence de gauche à droite à l'intérieur d'un texte de droite à gauche (un nombre, une adresse e-mail, un nom latin) est tapée dans son ensemble, comme un mot collé. Les textes CJK (sans espaces) et les mots longs s'enroulent exactement comme sur la page. La superposition elle-même est toujours disposée de gauche à droite (direction: ltr sur sa racine) donc une page de droite à gauche ne la reflète jamais. Les nombres dans n'importe quel script (\p{Nd}) comptent comme des nombres. Pages de test : tests/pages/lang-hu (ő / ű, mots très longs), lang-ar (droite à gauche, chiffres arabo-indiens, une citation hébraïque), lang-ja (japonais), lang-emoji. Limite connue : les modes d'écriture verticaux (writing-mode: vertical-rl) sont tapés mais les cadres grandissent toujours de gauche à droite.

Performances, moteurs de recherche, accessibilité

• Taille (ce qu'un visiteur télécharge ; l'add-on de débogage jamais) : module 70 Ko minifié / 27,5 Ko gzip, feuille de style 6 Ko / 1,6 Ko ; budget 30 Ko + 2 Ko gzip (node scripts/build-min.cjs --check). Reconstruisez les fichiers .min après chaque modification du module (--modules <dossier avec terser et csso>).

• Lighthouse (scripts/perf.cjs, médiane de 3, préréglages mobile / desktop, la machine de test sans GPU) :

  page	LCP ms désactivé -> activé	CLS désactivé -> activé	TBT ms désactivé -> activé	Speed Index ms désactivé -> activé	score perf
  demo, mobile	2106 -> 2207	0 -> 0	12 -> 10	968 -> 1669	99 -> 99
  demo, desktop	483 -> 573	0 -> 0	0 -> 0	266 -> 681	100 -> 100
  dental, mobile	1956 -> 2035	0 -> 0	0 -> 0	754 -> 1763	99 -> 99
  dental, desktop	442 -> 490	0 -> 0	0 -> 0	201 -> 767	100 -> 100
  law (polices web), mobile	2094 -> 2222	0,030 -> 0	0 -> 0	1895 -> 2386	98 -> 97
  accounting (page longue), mobile	1707 -> 1973	0 -> 0	0 -> 0	1652 -> 1697	99 -> 98

  Aucun temps de blocage et aucun changement de mise en page (le changement de police de la page law est même masqué). LCP augmente de 50 à 270 ms et Speed Index jusqu'à ~1 s : la première vue est construite devant le visiteur, donc elle est visuellement complète plus tard - c'est l'effet lui-même. Seuls les visiteurs pour la première fois (une fois par session) le paient ; les visiteurs de retour et les robots d'indexation obtiennent la page immédiatement. Les scores d'accessibilité / SEO bougent d'un point dans un sens ou dans l'autre uniquement parce que Lighthouse voit moins de la page pendant qu'elle est cachée.

• Moteurs de recherche et prévisualisations de liens : les robots d'indexation (user agent avec bot / crawl / spider, Googlebot, Bingbot, facebookexternalhit, prévisualisations de liens ...) n'obtiennent jamais l'effet, ni dans l'extrait de tête ni dans le module : ils voient la page finie avec le DOM identique (vérification a11y). Sans JavaScript, la page n'est jamais cachée, et l'effet ne supprime jamais de contenu (il utilise uniquement visibility).

• **Access

…

[Fin de la traduction partielle – le document original est tronqué]