# <butterfly-field>

Ein Partikel-Schmetterling als Hintergrund — **reines WebGL, keine Abhängigkeiten,
kein Build-Schritt.** Ein Web Component (Custom Element), das in jedem Framework
und in purem HTML läuft: React, Vue, Svelte, Angular, Astro, Next, plain HTML.

Herkunft: extrahiert aus der TEISENDA-Website. Silhouette über die
Schmetterlings-Kurve (Temple Fay), Flügelschlag als Wanderwelle im Shader,
Zusammenbau-Effekt beim Laden. Rund 9 KB, eine Datei. Frei verwendbar (MIT).

## Schnellstart

```html
<script src="butterfly-field.js"></script>

<!-- füllt seinen eigenen Kasten -->
<div style="position:relative; min-height:100vh">
  <butterfly-field style="position:absolute; inset:0"></butterfly-field>
  <h1 style="position:relative">Dein Inhalt</h1>
</div>
```

Das Element **füllt seinen nächsten Kasten** (wie ein `<img>` mit
`width:100%;height:100%`). Du bestimmst über CSS, wo und wie groß: ein Hero,
eine Karte, die ganze Seite (`position:fixed;inset:0;z-index:-1`).

Der Schmetterling zeichnet die Partikel **additiv über den vorhandenen
Hintergrund** — standardmäßig transparent, sodass dein CSS-Hintergrund
durchscheint. Für einen mitgelieferten Verlauf siehe `gradient` unten.

## Attribute

Alle optional.

| Attribut | Vorgabe | Wirkung |
|---|---|---|
| `count` | 20000 (Desktop) / 7000 (schmal) | Zahl der Partikel |
| `color-deep` | `#3a2c63` | Körperfarbe (dunkel) |
| `color-primary` | `#8250e6` | Flügelfarbe |
| `color-lavender` | `#d8cbf2` | Spitzenfarbe (hell) |
| `intensity` | `0.7` | Leuchtkraft der Partikel |
| `glow` | `0.25` | Aufleuchten beim Flügelschlag |
| `size` | `13` | Punktgröße |
| `materialize` | `1.8` | Zusammenbau-Dauer in Sekunden beim Laden (`0` = aus) |
| `fps` | `30` | Bildrate |
| `parallax` | an | `parallax="off"` schaltet die Maus-Reaktion ab |
| `height` | `0` | vertikale Lage (Welteinheiten; positiv = höher) |
| `gradient` | — | `"#topHex,#midHex,#botHex"` zeichnet einen eigenen Verlauf hinter den Partikeln (deckend) statt transparent |
| `force` | — | erzwingt die Anzeige auch dort, wo sie sonst unterdrückt wird (s. u.) |
| `debug` | — | schreibt Fehler in die Konsole (sonst scheitert die Deko lautlos) |

Beispiele:

```html
<!-- Voller Hero mit eigenem Verlauf -->
<butterfly-field gradient="#3a2c63,#241546,#0e0a1e"></butterfly-field>

<!-- Andere Farben, ohne Zusammenbau, ruhiger -->
<butterfly-field color-primary="#e6a850" color-lavender="#ffe9c2"
                 materialize="0" intensity="0.6"></butterfly-field>
```

## Rücksicht (eingebaut)

Der Schmetterling ist Dekoration und verhält sich entsprechend:

- startet **erst nach dem Laden** (über `requestIdleCallback`), verzögert also
  nichts;
- **pausiert im Hintergrund-Tab** (spart Akku);
- **schaltet sich selbst ab** bei `prefers-reduced-motion`, im Datensparmodus /
  bei langsamer Verbindung und auf schwachen Geräten (< 4 GB RAM oder < 4 Kernen).
  Mit `force` lässt sich das überschreiben;
- **räumt sich auf**, wenn das Element aus dem DOM entfernt wird
  (`disconnectedCallback` stoppt die Schleife und gibt den WebGL-Kontext frei) —
  wichtig für Single-Page-Apps.

## Framework-Beispiele

**React / Next** — Custom Elements funktionieren direkt. Datei einmal laden
(z. B. in `app/layout.tsx` per `<script src>` oder `import 'butterfly-field.js'`):

```jsx
export default function Hero() {
  return (
    <section style={{ position: 'relative', minHeight: '100vh' }}>
      <butterfly-field style={{ position: 'absolute', inset: 0 }}
                       gradient="#3a2c63,#241546,#0e0a1e" />
      <h1 style={{ position: 'relative' }}>Titel</h1>
    </section>
  );
}
```

TypeScript-Hinweis: einmal deklarieren

```ts
declare namespace JSX {
  interface IntrinsicElements {
    'butterfly-field': any;
  }
}
```

**Vue** — als natives Element behandeln (Vite: `isCustomElement`):

```js
// vite.config.js
export default {
  plugins: [vue({ template: { compilerOptions: {
    isCustomElement: (tag) => tag === 'butterfly-field',
  } } })],
};
```
```html
<butterfly-field gradient="#3a2c63,#241546,#0e0a1e" />
```

**Svelte / Astro / plain HTML** — einfach das Tag verwenden, nichts weiter.

## Dateien

- `butterfly-field.js` — die Komponente (das Einzige, was du brauchst).
- `demo.html` — zwei Beispiele (voller Hero mit Verlauf, Karte mit eigenen Farben).

## Grenzen / gut zu wissen

- Es ist ein **Hintergrund** hinter Inhalt. Halte `intensity` niedrig genug,
  dass Text lesbar bleibt; leg Inhalt mit `position:relative; z-index` darüber.
- Braucht **WebGL** (praktisch überall vorhanden). Fehlt es, verschwindet der
  Effekt lautlos und dein CSS-Hintergrund bleibt.
- Farben werden in lineares Licht umgerechnet und **additiv** gemischt — das ist
  bewusst so und macht das weiche Leuchten. Sehr helle Grundfarben können
  überstrahlen; dann `intensity` senken.
- Ein Element = ein Schmetterling. Mehrere Instanzen auf einer Seite sind
  möglich (jede hat ihren eigenen Kontext), kosten aber je Rechenzeit.