Phase 3: Plugin-SDK-Dokumentation (docs/plugin-sdk/, 7 Dateien)

- README: Pluginarten, Verzeichnisstruktur, Quick Start (§14.1/§14.2)
- manifest-reference: komplette plugin.json-Feldreferenz mit
  Validator-Regeln und ZIP-Sicherheit (§27.2)
- shader-contract: Standard-Uniformsatz je Backend, cbuffer-Layout,
  16-Byte-Alignment, Multipass, AQ-Bindung, GLES-Einschraenkungen (§14.4)
- parameters-and-dmx: dmx_slots max 8 (§14.7), Kurven, 16-Bit-Werte,
  gemeinsamer Effektvertrag mix/blend/quality (§14.8)
- lifecycle: Zustandsmaschine, Quarantaene, Show-Lock (§14.5/§26.3)
- adaptive-quality: Varianten, Semantik-Erhalt, Kompilierung vor
  Aktivierung, Framegrenzen-Wechsel (§5.2)
- example-walkthrough: komplettes Filter-Plugin anhand vignette
- 1199 Zeilen, Deutsch, alle Beispiele aus echten Repo-Dateien

docs/plugin-sdk/lifecycle.md

@@ -0,0 +1,83 @@
+# Plugin-Lebenszyklus
+
+Dieses Dokument beschreibt den Lebenszyklus eines Plugins. Grundlage sind PLAN.md §14.5 (Plugin-Lebenszyklus), §14.6 (Sicherheitsgrenze), §26.3 (Show-Lock) und die Implementierung `packages/plugin_sdk/hms_plugin_sdk/lifecycle.py`.
+
+## Zustände
+
+Der Lebenszyklus kennt folgende Zustände:
+
+```text
+discovered → validated → installed → enabled → compiled → active
+                                      ↘ quarantined / incompatible
+```
+
+Zusätzlich existiert der Zustand `disabled` (deaktiviert, aber installiert). Die vollständige Zustandsmenge (`lifecycle.py`):
+
+- `discovered`
+- `validated`
+- `installed`
+- `enabled`
+- `compiled`
+- `active`
+- `quarantined`
+- `incompatible`
+- `disabled`
+
+## Übergänge
+
+Übergänge sind nur entlang definierter Kanten erlaubt; Sprünge sind Fehler (`InvalidTransitionError`). Die erlaubten Übergänge (`lifecycle.py`):
+
+| Von | Nach |
+| --- | --- |
+| `discovered` | `validated`, `incompatible`, `quarantined` |
+| `validated` | `installed`, `incompatible`, `quarantined` |
+| `installed` | `enabled`, `disabled`, `quarantined` |
+| `enabled` | `compiled`, `disabled`, `quarantined` |
+| `compiled` | `active`, `quarantined`, `disabled` |
+| `active` | `disabled`, `quarantined` |
+| `disabled` | `enabled`, `quarantined` |
+| `quarantined` | – (manuelle Entfernung/Neuinstallation) |
+| `incompatible` | – |
+
+## Discovery und Validierung
+
+`discover()` scannt ein Verzeichnis mit Plugin-Ordnern, lädt `plugin.json` und validiert es (inkl. Shader-Existenz). Jedes Plugin wird in `validated` oder `incompatible`/`quarantined` überführt (`lifecycle.py`).
+
+Die Validierung umfasst (PLAN.md §14.5):
+
+- Manifest-Schema;
+- eindeutige Plugin-ID und semantische Version;
+- API-Kompatibilität;
+- Pfad- und ZIP-Sicherheit;
+- erlaubte Dateitypen und Größenlimits;
+- Shader-Kompilierung;
+- Capability-Prüfung;
+- vollständige, vorab kompilierbare Adaptive-Quality-Varianten und unveränderte Parametersemantik;
+- Lizenzmetadaten;
+- Hash des Pakets.
+
+## Quarantäne (§3.5, §14.5)
+
+Ein fehlerhaftes Plugin wird **quarantiniert**, ohne ein Projekt unbrauchbar zu machen. Der Effekt wird überbrückt (`bypass_on_error`). Die Quarantäne speichert die Ursache (`last_error`). Aus `quarantined` gibt es keinen automatischen Übergang; das Plugin muss manuell entfernt oder neu installiert werden.
+
+## Show-Lock (§26.3)
+
+Der Show-Lock sperrt strukturelle Änderungen während einer laufenden Show:
+
+- **Installieren/Updaten ist gesperrt.** Übergänge, die Installation/Update bedeuten (`installed` von `discovered`/`validated`), sind im Show-Lock blockiert.
+- **Enable/Disable und Parameter bleiben erlaubt.** Aktivieren bereits installierter Plugins (`enabled`/`compiled`/`active`) bleibt möglich (PLAN.md §17.7 Live-Modus).
+- **Versionswechsel sind gesperrt.** Ein Update startet einen neuen Zyklus; im Show-Lock wird ein Versionswechsel abgelehnt.
+
+Der Show-Lock wird über `set_show_lock(enabled)` gesetzt (`lifecycle.py`).
+
+## Doppelte Plugin-IDs
+
+Doppelte Plugin-IDs sind Fehler, keine stillen Überschreibungen. Ein Versionskonflikt wird erkannt; ohne Show-Lock gewinnt der neue Stand, mit Show-Lock wird der Versionswechsel abgelehnt (`lifecycle.py`).
+
+## Sicherheitsgrenze (§14.6)
+
+- Shaderplugins erhalten keinen Dateisystem- oder Netzwerkzugriff.
+- Native DLL-Plugins sind vor Version 2 nicht vorgesehen.
+- Python-Control-/Automation-Plugins laufen später in einem separaten Prozess mit freigegebener Command-API.
+- Kein Plugin greift direkt auf SQLite oder interne Python-Objekte zu.
+- Pluginfehler werden einem konkreten Plugin zugeordnet und in der UI angezeigt.