Kiskujab/page-swarm-rebuild

Was macht page-swarm-rebuild?

Version 1.3.0 (Modul, Add-on, Stylesheet und diese Datei; siehe CHANGELOG.md im Repository; SwarmRebuild.version).

Reiner Präsentations-Intro-Effekt. Das echte DOM der Seite wird nie modifiziert: Ebenen werden mit einem kaskadenartigen Stylesheet im <head> versteckt und wieder eingeblendet, die gesamte Animation findet in einem Overlay statt, das an <html> angehängt wird, und beide werden am Ende entfernt. Keine Abhängigkeiten, keine Netzwerkanfragen (DSGVO-freundlich), kein Layout-Shift, kein Ton, und die Seite wird nie halb versteckt zurückgelassen (siehe Schutz).

Spezifikation des ursprünglichen Effekts (Zeitachse, visuelle Elemente, HUD, Scrollkurve): references/effekt-leiras.md (Ungarisch). Wo diese Datei und jene abweichen, hat diese Datei Vorrang (Produktentscheidungen wurden nach dem Schreiben der Beschreibung getroffen).

Dateien

Datei	Zweck
assets/swarm-rebuild.js	Das Modul, lesbarer Quellcode (klassisches Skript, setzt window.SwarmRebuild; auch aus einem Bundler importierbar).
assets/swarm-rebuild.min.js, swarm-rebuild-debug.min.js, swarm-rebuild.min.css	Minifizierte Builds für reine HTML-Seiten (scripts/build-min.cjs; der Installer verwendet sie; Bundler minifizieren die Quellen selbst).
assets/swarm-rebuild.css	Overlay-Styles, alle unter #swarm-rebuild-root begrenzt.
assets/swarm-rebuild-debug.js	Debug-Add-on: Steuerleiste, Auto-Scroll-Tour, Test-Hooks. Wird nie für Besucher geladen; nur mit ?rebuild-debug=1 / debug: true abgerufen. Installieren Sie es trotzdem neben dem Modul (so testen Sie auf der Live-Seite).
assets/react/SwarmRebuild.jsx	React / Next.js Client-Wrapper + <SwarmRebuildHead /> (Pre-Paint-Snippet); das Debug-Add-on ist ein separater Lazy-Chunk.
assets/demo/	Fiktionales dunkles Portfolio-Demo (assets/demo/index.html, 214 Ebenen (Desktop), 6.6 Viewport-Höhen, sticky Header).
tests/index.html	Links zu jeder Testseite in jedem Modus (auch die GitHub Pages Startseite).
tests/pages/dental/	Fiktionale Zahnarztpraxis: helles Thema, Telefonlinks, fixierte "Rufen Sie uns an"- + Buchungsleiste (mobil), fixierter Hinweis (Desktop).
tests/pages/lang-*/	Fiktionale Seiten auf Ungarisch, Arabisch (rechts nach links), Japanisch und eine emoji-reiche (Tippen in jeder Sprache).
tests/pages/law/, accounting/, bootstrap/, spa/	Fiktionale reale Muster: Webschriften, sticky Header, Consent-Banner, Iframe, faule Bilder, Dark Mode, lange Seite, Scroll-Reveal, Bootstrap (npm), Single-Page-App, Videos.
tests/pages/nextjs/	Fiktionale Next.js 15 App Router App: React-Zähler (Hydration-Check), fixierter Hilfe-Button.
scripts/verify.cjs	Playwright-Überprüfung einer Seite (siehe Schritt 4).
scripts/run-tests.cjs	Führt verify.cjs auf den drei Testseiten aus, Desktop und Mobil; gibt eine Zusammenfassungstabelle aus.
scripts/bench-fps.cjs	Bildrate einer älteren Modulversion gegen die aktuelle, gleiche Maschine, verschränkte Läufe.
scripts/build-site.cjs	Baut die drei Testseiten als eine statische Seite (GitHub Pages) oder stellt sie im lokalen Netzwerk bereit.
scripts/next-app.cjs	Hilfsprogramm: Bereitet / baut die Next.js Test-App in einem temporären Ordner.
scripts/build-min.cjs	Baut die .min-Dateien und prüft das Größenbudget (benötigt terser und csso von npm).
scripts/perf.cjs	Lighthouse-Metriken (LCP, CLS, TBT, Speed Index, Zugänglichkeit, SEO) mit und ohne Effekt.
scripts/sync-snippet.cjs	Kopiert das Head-Snippet des Moduls in den React-Wrapper, die SKILL.md und die Testseiten.
scripts/record-video.cjs	Nimmt den Effekt als .mp4 / .webm für ein Portfolio auf (die Debug-Tour, Steuerleiste ausgeblendet).
scripts/project.cjs	Installiert den Effekt in ein Projekt mit einem Backup in legacy/, entfernt ihn wieder, stellt die Originale wieder her.
scripts/test-project.cjs	Testet den Installer: Backup, Wiederherstellung nach einem defekten Projekt (hash-identisch), Deinstallation.

Produktentscheidungen (sie überschreiben das Referenzvideo)

• Hauptmodus ist scroll (der Standard): Der Aufbau folgt dem Scrollen des Besuchers, und es wird nur das gebaut, was im Viewport ist: ein Element beginnt, wenn mindestens 60 % davon auf dem Bildschirm sind (buildVisible), nichts wird unterhalb oder oberhalb des Viewports gebaut, und kein arbeitender Agent verlässt jemals den Bildschirm.
• Besucher sehen niemals eine Steuerleiste und erhalten kein automatisches Scrollen. Die Leiste und die Tour leben im Debug-Add-on, das nur mit ?rebuild-debug=1 oder debug: true geladen wird. mode: 'tour' ohne das Add-on fällt auf scroll zurück.
• Immer ein Ausweg ohne sichtbare Steuerelemente: Esc, Tab, Enter, jede andere Taste (alleinige Shift/Ctrl/Alt/Meta ausgenommen) und jeder Klick oder Tipp zeigen die fertige Seite sofort an, ohne Animation und ohne Layout-Shift. prefers-reduced-motion bedeutet überhaupt keinen Effekt (WCAG 2.2.2).
• Scrolltasten scrollen: Leertaste, Pfeiltasten, Bild auf/ab und Pos1/Ende (mit dem Fokus auf der Seite selbst, ohne Ctrl / Alt / Meta) treiben den Aufbau genau wie das Mausrad. Auf einem fokussierten Link, Button oder Feld, oder mit einem Modifikator, beenden sie den Effekt wie jede andere Taste. Tab, Enter und Esc beenden ihn immer, sodass Tastaturbenutzer den echten Inhalt (und seine Fokus-Reihenfolge) beim ersten Tab erreichen.
• Der Klick, der den Effekt beendet, tut nie etwas, was der Besucher nicht gesehen hat: wenn er auf Inhalt landet, der noch nicht fertig war (versteckt oder noch im Bau), wird er geschluckt (preventDefault + stopPropagation, bei der Maus bereits bei pointerdown, also kein Fokus, kein Link, kein Button-Aktion). Wenn er auf fertigem Inhalt landet (sichtbar, nichts darin oder Enthüllendes noch in Bearbeitung – z.B. ein Telefonlink, der von Anfang an angezeigt wird, oder ein gebauter Button), wird er als normaler Klick durchgelassen und der Effekt endet gleichzeitig. Grund: das Schlucken jedes Klicks würde einen sichtbaren "Rufen Sie uns an"-Link beim ersten Tippen fehlschlagen lassen; das Durchlassen jedes Klicks würde Links folgen, die der Besucher nie gesehen hat. Touch-Scrollen und die Scrollleiste beenden den Effekt nie (Scrollen ist, wie der Aufbau angetrieben wird).
• Kein Ton. Das Modul enthält keinen Audio-Code.

Modi

Modus	Geschwindigkeit	Verhalten
scroll (Standard)	3x	Kein Auto-Scroll. Agenten bauen nur das, was im Viewport ist: ein Element beginnt, wenn mindestens buildVisible (60 %) seiner Höhe auf dem Bildschirm ist; ein Element höher als der Bildschirm, wenn es 60 % des Bildschirms ausfüllt, sodass es von oben nach unten eingebaut wird, während es hereinkommt. Nichts wird außerhalb des Viewports gebaut und ein arbeitender Agent verlässt ihn nie (ein Rahmen höher als der Bildschirm wird vom Bildschirmrand gezogen). Nach einem schnellen Scrollen (Rad, Tasten, Pos1/Ende) wird der sichtbare Teil in ~1-2 s gefüllt: diese Ebenen beginnen zuerst, mehr Agenten kommen hinzu (bis zu 8 über Plan) und Aufgaben laufen schneller. Was den Viewport verlässt, ist sofort endgültig (siehe Schutz).
fast	6x	Wie scroll, doppelt so schnell.
tour (nur Debug)	1x	Auto-Scroll wie im Referenzvideo: ~Ebenen/7 Sekunden, die Kamera folgt der Arbeitsfront, endet am unteren Ende mit dem Ring aus Cursorn. Für Aufnahmen und Side-by-Side-Vergleiche. ?rebuild-speed=6 ergibt das alte "schnell" (ein 6x Auto-Scroll, ~9 s im Demo). Manuelles Scrollen übergibt an den Besucher; der Tour-Button der Leiste setzt fort.

Nach dem Aufbau sammeln sich die Schwärme um das Fokuselement und das Overlay verschwindet nach autoExit Sekunden (3 s; mit dem Debug-Add-on 6 s, nie im Tour-Modus).

Bewegung

Alles ist standardmäßig dezent und wird mit motion eingestellt (siehe Konfigurieren); ?rebuild-motion=arc:0,... schaltet Teile für A/B-Tests aus (Debug-Add-on).

• Fokuselement (focus): der Eröffnungs- und der Finale-Schwarm darum. Fragen Sie den Entwickler (Schritt 1). In jeder Phase wird das erste dieser Elemente verwendet, das mindestens zur Hälfte im Viewport ist: das konfigurierte Element(e), [data-swarm-focus], h1, ein Haupt-Button (a.btn, .button, .cta, button[type=submit] ...), das Logo; dann das größte Bild im Viewport; dann ein Punkt im Viewport. Ein Fokus weit unten auf der Seite (z.B. ein abschließender Call-to-Action) dient dem Finale, und die Eröffnung verwendet die Hauptüberschrift.
• Schwärme: freie Agenten fliegen in 2-4 Schwärmen mit deutlich unterschiedlichen Größen (Telefone: 2). Jeder Agent wird von einer gedämpften Feder zu seinem Platz in seinem Schwarm gezogen; die Schwarmzentren bewegen sich auf einer Ellipse um das Fokuselement, deren Radius atmet und deren Tempo sich ändert, sodass Agenten von selbst beschleunigen und verlangsamen und nie auf einem perfekten Kreis laufen. Die Eröffnung beginnt bereits in Schwärmen (sie dauert für Besucher deutlich unter einer Sekunde).
• Ruhende Agenten (während des Aufbaus, ein Agent ohne Arbeit): er verlässt seinen Schwarm für seinen eigenen Platz im Viewport, mindestens 72 px von jedem anderen ruhenden Agenten entfernt (niemals ein Cluster überlappender Cursor), driftet langsam und blendet nach 1,4 s aus; er blendet an seinem Ruheplatz wieder ein, wenn er seinen nächsten Auftrag erhält. Beim Finale kommen alle zurück und sammeln sich in Schwärmen um den Fokus. Gemessen: höchstens 2 überlappende ruhende Cursor in 99,6-100 % der Frames (1,2: ein Median von 6 und bis zu 20 im Demo).
• Finale: eine steife, unterdämpfte Feder (Dämpfung 0,63, motion.spring) zieht jeden Agenten zum Fokus: am schnellsten am Anfang, etwa 5-20 % über seinen Platz hinaus, dann zurück; nach ~1 s wird die Feder weicher und die Schwärme kreisen langsam.
• Maus (Eröffnung und Finale, nur Desktop; nie bei Touch, nie mit reduzierter Bewegung): Ein Agent in der Nähe des Zeigers weicht aus (stärker, wenn der Zeiger schnell kommt); bis zu 3 neugierige Agenten folgen ihm dann auf einem kleinen Kreis, 1,3-2 s wenn er ruht, kürzer je schneller er sich entfernt (Interesse schwindet mit (1 + Geschwindigkeit / 220 px/s) mal der Basisrate). Niemals näher als 36 px (eine harte Grenze, damit sich die Symbole nie überlappen); das Overlay ignoriert Zeigerereignisse, sodass Klicks nie gestört werden.
• Schwerkraft: Ein Agent trägt das Element, an dem er arbeitet, sodass sein Weg dorthin (und eine getragene Klonkopie) nach unten gebogen wird: Durchhang = 0,2 x horizontale Distanz x Gewicht x Horizontalität², Gewicht = sqrt(Fläche) / 320 px, begrenzt auf 0,2..1, maximal 56 px und ein Fünftel der horizontalen Distanz. Eine vertikale Bewegung biegt kaum. Der Weg zu einer Aufgabe beginnt auch mit der aktuellen Geschwindigkeit des Agenten (kubische Hermite-Kurve), sodass es keine plötzlichen Stopps oder Wendungen gibt.
• Schwierigkeit: Die Arbeit jeder Aufgabe (nicht der Weg dorthin) wird durch eine Schwierigkeit aus der Fläche des Elements skaliert (beim Tippen: das Feld, in das getippt wird): nahe am Seitendurchschnitt 2x die Fläche ~ 1,6-1,8x die Zeit, abgeflacht (tanh), sodass die schwierigste Aufgabe höchstens ~4x die einfachste dauert. Es wird normalisiert (gewichtet nach Aufgabenlänge und Schwierigkeit, da parallele Aufgaben die langen zum Tempo machen), sodass der gesamte Aufbau genauso lange dauert wie zuvor; nur die Aufteilung zwischen kleinen und großen ändert sich.
• Lite (motion.lite: 'auto'): auf Telefonen 2 Schwärme und kein Mausspiel; wenn die Bildrate während des Aufbaus für zwei Sekunden unter 38 fps bleibt, auch ein Trail-Geist statt drei.

Sprachen und Schreibrichtungen

Das Modul setzt keine Sprache voraus. Das Tippen erfolgt nach benutzerwahrgenommenen Zeichen (Graphem-Cluster, Intl.Segmenter, mit einem Fallback, das kombinierende Markierungen, ZWJ-Sequenzen, Hauttöne, Variationsselektoren und Flaggenpaare verbindet): ein akzentuierter Buchstabe, eine Emoji-Familie, eine Flagge oder ein Buchstabe mit arabischen / hebräischen Markierungen wird nie getrennt. Nicht getippter Text bleibt als verborgener Text an Ort und Stelle, und Browser formen über diese Grenze hinweg, sodass arabische Buchstaben ihre verbundenen Formen behalten und nichts umfließt. Rechts-nach-links-Elemente (direction: rtl, z.B. <html dir="rtl">): Rahmen wachsen von der rechten Kante, Linien werden von rechts nach links gezeichnet, der Agent tippt auf der linken Seite und der Cursor sitzt links des zuletzt getippten Buchstabens; ein links-nach-rechts-Lauf innerhalb von rechts-nach-links-Text (eine Zahl, eine E-Mail-Adresse, ein lateinischer Name) wird als Ganzes getippt, wie ein eingefügtes Wort. CJK-Text (keine Leerzeichen) und lange Wörter umbrechen genau wie auf der Seite. Das Overlay selbst wird immer links nach rechts angeordnet (direction: ltr auf seinem Root), sodass eine rechts-nach-links-Seite es nie spiegelt. Zahlen in jeder Schrift (\p{Nd}) gelten als Zahlen. Testseiten: tests/pages/lang-hu (ő / ű, sehr lange Wörter), lang-ar (rechts nach links, arabisch-indische Ziffern, ein hebräisches Zitat), lang-ja (Japanisch), lang-emoji. Bekannte Einschränkung: vertikale Schreibmodi (writing-mode: vertical-rl) werden getippt, aber die Rahmen wachsen immer noch von links nach rechts.

Leistung, Suchmaschinen, Barrierefreiheit

• Größe (was ein Besucher herunterlädt; das Debug-Add-on nie): Modul 70 KB minifiziert / 27,5 KB gzip, Stylesheet 6 KB / 1,6 KB; Budget 30 KB + 2 KB gzip (node scripts/build-min.cjs --check). Bauen Sie die .min-Dateien nach jeder Änderung am Modul neu (--modules <Ordner mit terser und csso>).

• Lighthouse (scripts/perf.cjs, Median von 3, Mobil / Desktop-Voreinstellungen, die Testmaschine ohne GPU):

  Seite	LCP ms aus -> an	CLS aus -> an	TBT ms aus -> an	Speed Index ms aus -> an	Leistungspunktzahl
  Demo, mobil	2106 -> 2207	0 -> 0	12 -> 10	968 -> 1669	99 -> 99
  Demo, Desktop	483 -> 573	0 -> 0	0 -> 0	266 -> 681	100 -> 100
  Dental, mobil	1956 -> 2035	0 -> 0	0 -> 0	754 -> 1763	99 -> 99
  Dental, Desktop	442 -> 490	0 -> 0	0 -> 0	201 -> 767	100 -> 100
  Recht (Web-Schriften), mobil	2094 -> 2222	0,030 -> 0	0 -> 0	1895 -> 2386	98 -> 97
  Buchhaltung (lange Seite), mobil	1707 -> 1973	0 -> 0	0 -> 0	1652 -> 1697	99 -> 98

  Keine Blockierungszeit und kein Layout-Shift (der eigene Schriftartwechsel der Rechtsseite wird sogar versteckt). LCP wächst um 50-270 ms und Speed Index um bis zu ~1 s: Der erste Viewport wird vor dem Besucher aufgebaut, ist also später visuell vollständig - das ist der Effekt selbst. Nur Erstbesucher (einmal pro Sitzung) zahlen dafür; wiederkehrende Besucher und Crawler erhalten die Seite sofort. Barrierefreiheits-/SEO-Punktzahlen bewegen sich nur um einen Punkt in die eine oder andere Richtung, weil Lighthouse weniger von der Seite sieht, während sie versteckt ist.

• Suchmaschinen und Link-Vorschauen: Crawler (User-Agent mit bot / crawl / spider, Googlebot, Bingbot, facebookexternalhit, Link-Vorschauen ...) erhalten den Effekt nie, weder im Head-Snippet noch im Modul: sie sehen die fertige Seite mit dem identischen DOM (a11y-Prüfung). Ohne JavaScript wird die Seite nie versteckt, und der Effekt entfernt niemals Inhalt (er verwendet nur visibility).

• **Zugänglich