# CAVEATS — bevor du baust, bitte lesen

## Realität-Check

LaserOS (WickedLasers/LaserCube) hat **keine offizielle High-Level-API**:

- Kein offizieller MIDI-Input für "Pattern XY laden". LaserOS lernt aber MIDI-CC/Notes auf bereits konfigurierte UI-Aktionen (Stars/Favoriten/Hotkeys) — das nutzen unsere Plugins.
- Für volle Kontrolle über Punktdaten (eigene Pattern) gibt es das offene `libLaserdockCore` UDP-Protokoll (Ports 45456–45458). Das ist hier **nicht** drin, wäre der Weg für eine Variante 5 (siehe unten).
- BLE-Protokoll der Mobile-App ist proprietär – ignoriert.

Quellen: `LASEROS-API.md`, `SDK-NOTES.md`, `STATUS.md` (Subagent-Recherche).

## Was die 4 Varianten tun

Sie senden **MIDI** (Notes/CCs) und **OSC** auf einen virtuellen Port. Du musst in LaserOS einmalig:

1. MIDI-Input auf `LoupedeckLaserBridge` aktivieren.
2. Pro Pattern/Effekt/Encoder im LaserOS-UI „Assign MIDI" + Plugin-Button drücken (Learn).

Sobald gelernt: alles läuft.

## Was die Plugins NICHT können

- **Pattern-Vorschau auf dem Loupedeck-Touchscreen.** Dafür müsste LaserOS Pattern-Thumbnails über ein API liefern – tut es nicht.
- **Status-Feedback** (ist Pattern X gerade aktiv?). Einbahnstraße: Plugin → LaserOS.
- **Verbindungstest zum LaserCube.** Wir reden nur mit LaserOS.

## Optionaler Pfad: Variante 5 (UDP-Direct)

Wenn dir das nicht reicht und du LaserOS **umgehen** willst:

- Subagent hat in `LASEROS-API.md` das komplette `libLaserdockCore`-UDP-Protokoll dokumentiert (Discovery, Output-Toggle, Sample-Stream, Backpressure).
- Damit könnte ein zukünftiges Plugin direkt Punkte streamen + eigene Pattern rendern.
- Aufwand: deutlich höher (Pattern-Engine, Lasersicherheits-Watchdog, ILDA-Sample-Code), aber 100 % autark und ohne LaserOS-Lizenz.

## Sicherheits-Hinweise

- **PANIC-Button:** Jede Variante hat einen `PanicCommand` (rote Taste). Sendet auf alle 16 MIDI-Channels gleichzeitig CC7=0 + AllNotesOff + OSC-Blackout. Leg den auf einen physischen Loupedeck-Button mit haptik.
- **Watchdog beim Unload:** `LaserBridge.Shutdown()` schickt Panic beim Plugin-Unload (Loupedeck-App-Quit, Plugin-Reload).
- **Strobe-Auto-Cutoff:** In Variante 4 schaltet sich Strobe/Whiteout nach 2,5 s / 1,5 s zwangsweise ab (Epilepsie-Risiko).
- **Safety Lens** während Entwicklung tragen. Immer.

## Bekannte Limits in v1.0

- Kein UI in der Loupedeck-App, um MIDI-Channel / OSC-Host umzustellen (hartcodiert).
  → Workaround: `LaserBridge.ConfigureOsc("127.0.0.1", 5000)` im `Plugin.Load()` editieren.
- Keine Icons im Repository — Loupedeck zeigt Text-Labels.
  → Du kannst PNGs (60/80/256 px) in `package/metadata/` legen, dann zeigt Loupedeck Bilder.
- Build auf macOS getestet gegen Logi PluginService 6.x. Ältere Loupedeck-Software (< 6.0) braucht das alte SDK (siehe `SDK-NOTES.md`).