# MidnightSteel

## Status
Addon-Version: 13.0.0
MidnightSteel-Version: v0.2
Interface-Ziel: 120005
Stand: SteelUI vollstaendig, Keybinds, Cooldowns, Hints, DispelAlerts + StackTracker Integration abgeschlossen
Integration: MidnightHUD-Modul
Standalone: spaeter geplant
Hardware-Ziel: SteelSeries Apex Pro Gen 3 / Apex Pro TKL Gen 3 / Aerox-Serie

Wichtige Versionsregel:
- `## Interface` richtet sich immer nach der aktuell laufenden WoW-Client-Version. Fuer WoW 12.0.5 ist das `120005`.
- `## Version` ist die MidnightHUD-Addon-Version. Diese steht aktuell auf `13.0.0`.
- Diese beiden Werte duerfen nicht verwechselt werden. Eine Addon-Version 13.0.0 bedeutet NICHT automatisch `## Interface: 130000`.

---

## Kurzbeschreibung

MidnightSteel ist die geplante SteelSeries-Integration fuer MidnightHUD.
Das Modul verbindet eine grafische Tastatur-/Mausanzeige im Spiel mit spaeterer SteelSeries GameSense-Unterstuetzung ueber eine externe Bridge.

Wichtig: Das WoW-Addon steuert keine Hardware direkt. World of Warcraft Addons laufen in einer Sandbox und koennen keine lokale Hardware oder SteelSeries GG direkt abfragen. Deshalb wird spaeter eine externe Windows-Bridge benoetigt.

---

## Namensentscheidung

| Alter Name | Neuer Name |
|---|---|
| KeyUI | SteelUI |
| MidnightSense | MidnightSteel |

SteelUI ist die grafische Ingame-Darstellung innerhalb von MidnightSteel.
MidnightSteel ist das vollstaendige MidnightHUD-Modul.

---

## Ziel

MidnightSteel soll keine Automatisierung und keinen Bot bauen.
Das Ziel ist reine Anzeige und Rueckmeldung:

Erlaubt:
- Taste im Overlay hervorheben
- Taste auf SteelSeries RGB hervorheben
- Cooldowns auf Tasten anzeigen
- Dispel-/Interrupt-/Defensive-Hinweise anzeigen
- Bossmechanik grafisch sichtbar machen
- OLED/Statusanzeige ueber externe Bridge

Nicht erlaubt:
- automatische Casts
- automatische Rotation
- Eingabesimulation
- Bot-Funktionen

---

## Grundarchitektur

```text
MidnightHUD / MidnightSteel
  -> SteelUI Ingame-Fenster
  -> Keybinds, Cooldowns, Hinweise
  -> optionale Statusdaten fuer Bridge

MidnightSteel Bridge spaeter
  -> erkennt SteelSeries GG
  -> erkennt SteelSeries-Geraete
  -> registriert GameSense-App
  -> sendet RGB/OLED-Events
```

Ohne Bridge funktioniert MidnightSteel als normales Ingame-Overlay.

---

## Hardware-Erkennung

Das Addon selbst kann nicht sicher erkennen, ob eine SteelSeries-Tastatur angeschlossen ist.
Die Erkennung wird spaeter von der Bridge uebernommen.

Aktueller Status im Grundgeruest:

```lua
hardware = {
  bridgeInstalled = false,
  bridgeConnected = false,
  steelseriesEngine = false,
  keyboardDetected = false,
  mouseDetected = false,
  deviceName = "None",
  mode = "IngameOnly",
}
```

Wenn keine SteelSeries vorhanden ist:
- keine Fehler
- kein Chat-Spam
- kein RGB-Versuch
- SteelUI bleibt nutzbar

---

## Aktuell angelegte Dateien

```text
Modules/MidnightSteel/
  README.md
  Core.lua
  SteelUI.lua
  Keyboard.lua
  Mouse.lua
  Bindings.lua
  Cooldowns.lua
  Hints.lua
  Bridge.lua
  DeviceStatus.lua
  Profiles.lua
  Export.lua
  Utils.lua
  Layouts/ApexProGen3_DE.lua
  Layouts/G915_DE.lua

Options/MidnightSteel.lua
```

---

## Fortschritt v0.1-dev

Korrektur nach Analyse:
- `## Interface` wurde von `130000` auf `120005` zurueckgesetzt.
- Grund: Interface ist die WoW-Client-Kompatibilitaet, nicht die MidnightHUD-Projektversion.
- `## Version` bleibt `13.0.0`.

Stand 13.0.0 Paket:
- TOC-Version auf 13.0.0 gesetzt
- Interface-Ziel korrekt auf 120005 gesetzt, da dies zur aktuell verwendeten WoW-Version 12.0.5 gehoert
- README um spaetere Konversationsanker und Architekturentscheidungen erweitert


## v0.2 - Abgeschlossen (2026-05-11)

Erledigt:
- Modulordner + Grundgeruest (Phase 1)
- MidnightHUD TOC erweitert, Config-Tab, Default-Profil, Modul API
- SteelUI Fenster vollstaendig (Drag, Lock, Theme, Scale)
- Apex Pro Gen 3 DE Tastaturlayout vollstaendig
- G915 DE Uebergangslayout
- Keybind-Auswertung (Bindings.lua) mit Modifier-Parsing
- Hint-System (Hints.lua): SetKey/ClearKey/ClearAll, Farben per Reason
- Cooldowns auf Tasten (text-basiert, 0.2s Throttle, amber/rot-Logik)
- Mouse-Panel (5 Tasten: LMB, RMB, MID, S1, S2)
- DispelAlerts -> NotifyDispelAlert (configurable key, duration)
- StackTracker -> NotifyProcAlert (permanent hint, kein Timeout)
- Options-Tab: vollstaendig inkl. beschreibender Tooltips fuer Key-Eingabe
- DeviceStatus/Bridge als saubere Platzhalter ohne Fehler

Entschieden / nicht integriert:
- BossBrief: kein standalone Addon, Integration entfaellt dauerhaft
- Skyriding-Profil: wird im Interface-Layout-Schritt gemacht
- Keine Spell-Icons auf Tasten (bewusst: MidnightSteel ist Alert-Overlay, kein Key-Viewer)

Noch offen (Phase 4):
- echte MidnightSteel Bridge (Windows-App)
- SteelSeries GG / GameSense Integration
- RGB-Events
- OLED-Ausgabe
- Geraetestatus-Rueckmeldung ans Addon

---

## Entwicklungsphasen

### Phase 1 - Grundgeruest
Status: abgeschlossen

### Phase 2 - SteelUI Ausbau + MidnightHUD Integration
Status: abgeschlossen

### Phase 3 - Interface Layout (naechster Schritt nach MidnightSteel)
Ziel:
- ZperlMini Unit Frames vollenden
- MidnightSkyriding Layout vollenden
- Skyriding-Profil fuer MidnightSteel

### Phase 4 - MidnightSteel Bridge
Ziel:
- Windows-App (separates Projekt)
- SteelSeries GG erkennen
- GameSense registrieren
- RGB/OLED Events senden
- Geraetestatus zurueckmelden

### Phase 5 - Standalone
Ziel:
- abgespeckte Standalone-Version ohne MidnightHUD-Abhaengigkeit

---

## Designvorgabe

Midnight Theme:
- dunkles Metall
- blau/violette Energie
- klare Kontraste
- lesbare Tasten

Light Theme:
- hellere Variante
- Gold/Blau
- kristallartig


---

## Wichtige Daten fuer spaetere Konversationen

Diese Punkte sind verbindlich fuer die weitere Entwicklung und sollen in spaeteren Chats nicht neu entschieden werden muessen.

### Aktueller Paketstand

- Paketname: `MidnightHUD_13.0.0_MidnightSteel_v0.2`
- Addon-Version im TOC: `13.0.0`
- Interface-Ziel im TOC: `120005`
- MidnightSteel ist aktuell ein integriertes MidnightHUD-Modul, kein separates Addon.
- Das Modul ist standardmaessig deaktiviert und darf ohne SteelSeries-Hardware keine Fehler erzeugen.

### Finale Namensentscheidungen

- Aus `KeyUI` wurde `SteelUI`.
- Aus `MidnightSense` wurde `MidnightSteel`.
- `SteelUI` bezeichnet nur das Ingame-Fenster fuer Tastatur/Maus.
- `MidnightSteel` bezeichnet das komplette System aus Addon-Modul, spaeterer Bridge und Hardware-Integration.

### Grundsatzentscheidung: KeyUI nur als Vorlage

KeyUI wird nicht 1:1 uebernommen.
Nur sinnvolle Konzepte werden uebernommen:

- Layout-Idee fuer Tastatur/Maus
- Keybind-Anzeige
- Cooldown-Anzeige
- optische Hervorhebung von Tasten

Nicht uebernehmen:

- ueberladene Optionsstruktur
- Controller-Systeme
- Tutorial-/Importsysteme
- unnoetige Libraries
- alte Standalone-Logik
- Minimap-Button
- fremde Optik

MidnightSteel soll langfristig fast komplett eigenstaendig geschrieben werden.

### 13.0.0 Architekturentscheidung

Fuer 13.0.0 soll MidnightSteel intern langfristig in klare Bereiche aufgeteilt werden:

```text
Modules/MidnightSteel/
  Core/
  UI/
  Providers/
  Hardware/
  Layouts/
  Media/
```

Der aktuelle v0.1-dev Stand nutzt noch flache Dateien, damit das Modul schnell laedt und testbar bleibt.
Beim naechsten groesseren Umbau soll die Struktur sauber aufgeteilt werden.

### Provider-Regel

Die UI darf langfristig nicht direkt alle WoW-APIs abfragen.
Stattdessen:

```text
Provider sammeln Daten -> SteelUI zeigt Daten -> Hardware/Export verarbeitet Daten
```

Geplante Provider:

- Bindings Provider
- Cooldowns Provider
- Combat Provider
- Boss Provider
- Dispel Provider
- StackTracker Provider
- Skyriding Provider
- Actionbar Provider

Ziel:

- weniger Taint
- weniger CPU-Verbrauch
- leichteres Debugging
- stabile 13.0.0-Kompatibilitaet

### Hardware- und Bridge-Regel

World of Warcraft Addons duerfen keine SteelSeries-Hardware direkt erkennen oder steuern.
Deshalb gilt:

```text
WoW Addon -> Ingame-Anzeige / Statusdaten
MidnightSteel Bridge -> SteelSeries GG / GameSense / RGB / OLED
```

Ohne Bridge:

- SteelUI bleibt nutzbar
- Keybinds und Hinweise bleiben nutzbar
- RGB/OLED bleibt aus
- kein Fehler
- kein Chat-Spam

Mit Bridge spaeter:

- SteelSeries GG erkennen
- Apex Pro Gen 3 erkennen
- Aerox Maus erkennen
- GameSense App registrieren
- RGB/OLED Events senden
- Status an Addon zurueckgeben

### Sicherheitsregel / Blizzard-Konformitaet

MidnightSteel darf nur anzeigen und rueckmelden.

Erlaubt:

- Taste hervorheben
- Taste blinken lassen
- Cooldown anzeigen
- Boss-/Dispel-/Interrupt-Hinweis anzeigen
- RGB/OLED ueber Bridge anzeigen

Nicht erlaubt:

- automatisches Casten
- automatische Rotation
- Eingaben simulieren
- Makros automatisch ausfuehren
- Bot-Funktionen

### Taint-Regel fuer 13.0.0

MidnightSteel darf keine protected Frames veraendern und keine secure Aktionen ausloesen.
Bekannte Risikobereiche aus MidnightHUD:

- Secret Values
- UnitExists / UnitAura / Tooltip-Daten in tainted Execution
- Actionbutton-Hooks
- protected UI in Combat

Deshalb:

- keine direkten permanenten ActionButton-Hooks
- keine protected Aktionen im Kampf
- Daten moeglichst ueber C_ APIs und Events sammeln
- Updates throttlen
- UI im Kampf nicht strukturell umbauen

### Performance-Regel

SteelUI darf nicht permanent pro Frame alles neu berechnen.

Verboten:

- grosses OnUpdate ohne Throttle
- permanente Vollscans aller Tasten
- SavedVariables-Spam
- Hardware-/Export-Spam

Gewuenscht:

- eventbasiert
- 0.1 bis 0.2 Sekunden Throttle fuer sichtbare Anzeige
- nur sichtbare Elemente aktualisieren
- Export nur bei relevanten Statusaenderungen

### Geplante erste echte Funktionsstufe

Naechster sinnvoller Entwicklungsstand: `MidnightSteel v0.2`

Ziel:

1. SteelUI visuell komplett nutzbar machen
2. Apex Pro Gen 3 DE Layout vervollstaendigen
3. G915 als Uebergangslayout behalten
4. Keybinds lesbar auf Tasten anzeigen
5. Cooldown-Zahlen vorbereiten
6. Hint-System stabilisieren
7. DispelAlerts anbinden
8. BossBrief spaeter anbinden

### Aktueller bekannter Zustand

Aktuell vorhanden:

- Modul laedt ueber MidnightHUD TOC
- Optionsdatei vorhanden
- Defaults vorhanden
- Slash `/mhud steel` vorbereitet
- SteelUI-Fenster vorbereitet
- Basis-Tastaturdarstellung vorbereitet
- ApexProGen3_DE Layoutbasis vorhanden
- G915_DE Uebergangslayout vorhanden
- DeviceStatus/Bridge als Platzhalter vorhanden
- Export-Snapshot als Platzhalter vorhanden

Noch nicht vorhanden:

- echte Bridge
- echte SteelSeries-Erkennung
- echte GameSense Events
- vollstaendige Tastaturgrafik
- vollstaendige Mausgrafik
- OLED
- Actionbar-Cooldowns
- DispelAlerts-Integration
- BossBrief-Integration
- StackTracker-Integration
- Skyriding-Profil

### Entwicklungsprioritaet

Die Reihenfolge bleibt:

1. Stabile Ingame-Anzeige
2. Saubere Keybind-Erkennung
3. Hint-/Warnsystem
4. Cooldown-Anzeige
5. MidnightHUD-Modul-Anbindungen
6. Erst danach Bridge/RGB/OLED

RGB ist nicht die Grundlage. Die Grundlage ist eine gute SteelUI.

---

## Naechster sinnvoller Schritt

Als naechstes sollte SteelUI visuell ausgebaut werden:
1. vollstaendige Apex-Pro-Gen-3-DE-Tastatur
2. Keybind-Labels
3. Cooldown-Text
4. farbige Hint-Stati
5. Mauslayout

Danach erst Bridge/GameSense.

---

## Verlauf / Fix 2026-05-10 - WealthAudit Gold Secret-GUID

Fehlerbild:
- In `Düsterweg Tiefen`/Tiefen-Tooltippfaden meldete BugGrabber:
  `MidnightHUD/Core/WealthAudit.lua:206: attempt to compare local 'guid' (a secret string value, while execution tainted by 'MidnightHUD')`.

Ursache:
- `TooltipDataProcessor` kann in WoW 12.x/Midnight bei Unit-Tooltips `data.guid`, `unitGUID` oder `healthGUID` als Secret-Wert liefern.
- Schon Vergleiche wie `guid == ""`, `unitGUID ~= pendingGUID` oder die Nutzung als Tabellen-Key koennen in tainted Addon-Pfaden crashen.

Umgesetzte Regel:
- WealthAudit/Gold liest keine TooltipData-GUIDs mehr.
- WealthAudit/Gold vergleicht keine `INSPECT_ACHIEVEMENT_READY`-GUID mehr.
- Fuer Gold-Tooltips wird nur noch der sichere Literal-Unit-Token `mouseover` genutzt.
- Vor Anzeige wird der aktuelle `mouseover` erneut mit `UnitExists` und `UnitIsPlayer` in `pcall` geprueft.

Wichtig fuer spaetere Arbeiten:
- Bei WoW 12.x nie TooltipData-GUIDs aus tainted Pfaden vergleichen.
- Secret-Werte nicht in Bedingungen, Stringkonvertierung, Tabellen-Keys oder Log-Ausgaben verwenden.
- Wenn moeglich immer sichere Literal-Unit-Tokens verwenden: `player`, `target`, `mouseover`, `party1` usw.
