### **Roadmap: Implementierung des Interaktiven Semantischen Editors**

**Leitprinzip:** Die Serialisierung ist kein nachträgliches Feature, sondern das Fundament. Das Datenformat wird zuerst vollständig definiert und implementiert. Die Visualisierungs- und Editierfunktionen bauen darauf auf.

---

#### **Phase 1: Das Fundament – Datenmodell & Persistenz**

**Ziel:** Eine robuste Serialisierungs-Engine zu schaffen, die den gesamten Zustand des Editors (AST, logische Metadaten, Instanz-Metadaten) verlustfrei speichern und laden kann, *bevor* eine einzige visuelle Komponente existiert.

1. **Definition der Kern-Datenstrukturen:**  
   * **TViewModelID**: Ein Int64-Typ als eindeutige, stabile ID für jede visuelle Knoteninstanz.  
   * **TVisualNodeViewModel**: Die Vermittlerklasse zwischen IAstNode und TAuraNode. Enthält eine Referenz auf den IAstNode und seine eigene TViewModelID.  
   * **TLogicalMetadata**: Record für Metadaten, die an einen IAstNode gebunden sind (z.B. semantische Farbcodierung).  
   * **TVisualInstanceMetadata**: Record für Metadaten, die an eine TViewModelID gebunden sind. **Hier wird die neue Anforderung verankert:**  
     * PositionOverride: TPointF  
     * IsCollapsed: Boolean  
     * VisualizationMode: (vmSyntactic, vmSemantic) // Definiert, wie DIESE Instanz ihre Kinder darstellt.  
2. **Festlegung des finalen JSON-Formats:**  
   * Das JSON-Format wird von Anfang an so entworfen, dass es alle zukünftigen Anforderungen abbilden kann. Es besteht aus drei Hauptteilen:  
     1. **ast**: Der reine IAstNode-Baum. Zur Persistenz wird jedem IAstNode beim Speichern eine temporäre, datei-interne Integer-ID zugewiesen.  
     2. **logicalMetadata**: Ein Dictionary, das die temporären IAstNode-IDs auf ihre TLogicalMetadata abbildet.  
     3. **instanceMetadata**: Ein Dictionary, das die stabilen TViewModelIDs auf ihre TVisualInstanceMetadata abbildet (inklusive des neuen VisualizationMode).  
3. **Implementierung des Serialisierungs- & Deserialisierungs-Backbones:**  
   * Entwicklung der Routinen, die einen IAstNode-Baum und die dazugehörigen Metadaten-Dictionaries entgegennehmen und eine JSON-Datei gemäß Schritt 1.2 erzeugen.  
   * Entwicklung der Gegenstücke, die eine solche JSON-Datei einlesen und die In-Memory-Strukturen (IAstNode-Baum, Dictionaries für Metadaten) vollständig und konsistent wiederherstellen.  
   * **Wichtig:** Diese Logik arbeitet komplett ohne UI-Komponenten.

**Ergebnis von Phase 1:** Eine voll funktionsfähige "headless" Lade- & Speicher-Bibliothek. Man kann einen Editor-Zustand programmatisch erzeugen, speichern, wieder laden und die Datenintegrität per Unit-Tests verifizieren. **Die Serialisierung ist damit vom ersten Tag an das stabilste Element der Architektur.**

---

#### **Phase 2: Die Flexible Visualisierungs-Engine**

**Ziel:** Die in Phase 1 definierten Datenstrukturen sichtbar machen und den Wechsel zwischen syntaktischer und semantischer Darstellung ermöglichen.

1. **Der "ViewModel-Builder"-Visitor:**  
   * Dieser Visitor nimmt einen IAstNode (HAST) sowie die Metadaten entgegen und erzeugt den TVisualNodeViewModel-Graphen.  
   * Er arbeitet modus-abhängig, basierend auf dem VisualizationMode des Eltern-ViewModels:  
     * **Im vmSyntactic-Modus:** Erzeugt für jeden Kind-IAstNode eine neue, einzigartige TVisualNodeViewModel-Instanz mit einer neuen TViewModelID. Das Ergebnis ist ein Baum.  
     * **Im vmSemantic-Modus:** Nutzt nach dem obligatorischen Binding-Schritt einen TDictionary\<TResolvedAddress, TVisualNodeViewModel\>, um für bereits visualisierte semantische Entitäten das existierende ViewModel wiederzuverwenden. Das Ergebnis ist ein DAG.  
2. **Die Layout- & Rendering-Engine (TAuraLayoutEngine):**  
   * Diese Engine nimmt den TVisualNodeViewModel-Graphen (der ein Baum oder DAG sein kann) und erzeugt die visuellen TAuraNode-Controls.  
   * Für jedes ViewModel liest sie die TVisualInstanceMetadata (über die TViewModelID) und wendet Position, Kollaps-Zustand etc. an.  
   * Sie muss in der Lage sein, die Verbindungen für eine DAG-Struktur korrekt zu zeichnen (d.h. Linien von mehreren Eltern zu einem Kind).  
3. **Implementierung des Modus-Wechsels:**  
   * Schaffung einer UI-Aktion (z.B. Kontextmenü auf einem TAuraNode), um den VisualizationMode in den Metadaten einer ViewModel-Instanz zu ändern.  
   * Diese Änderung löst eine Aktualisierung aus: Der ViewModel-Builder wird für den betroffenen Teilbaum neu ausgeführt, und die Layout-Engine zeichnet den Bereich neu.

**Ergebnis von Phase 2:** Ein interaktiver Viewer. Projekte können geladen, in beiden Modi (syntaktisch/semantisch) dargestellt und per Knoten umgeschaltet werden.

---

#### **Phase 3: Der Interaktive Editor**

**Ziel:** Dem Benutzer die sichere und strukturierte Bearbeitung des Graphen zu ermöglichen.

1. **Implementierung des Command Patterns:**  
   * Jede Änderung am AST (Knoten hinzufügen, löschen, Eigenschaft ändern) wird als IEditorCommand mit Execute und Unexecute implementiert, um Undo/Redo zu ermöglichen.  
   * Ein Command modifiziert **immer nur das HAST-Modell**, niemals direkt das ViewModel oder die View.  
2. **Entwicklung des Socket-basierten Controllers:**  
   * Implementierung der Logik, die Benutzerinteraktionen (Klick auf ein "Socket") in die Erzeugung und Ausführung des passenden Commands übersetzt.  
3. **Etablierung des Update-Zyklus:**  
   * Nachdem ein Command das HAST-Modell erfolgreich modifiziert hat, wird der Update-Prozess angestoßen:  
     1. Der "ViewModel-Builder" läuft über den geänderten Teil des HAST. Er versucht dabei, existierende ViewModels (anhand ihrer IAstNode-Referenz) wiederzuverwenden, um deren stabile IDs und damit die UI-Zustände zu erhalten. Nur für neue IAstNodes werden neue ViewModels erzeugt.  
     2. Die TAuraLayoutEngine rendert die neuen TAuraNode-Controls.

**Ergebnis von Phase 3:** Ein voll funktionsfähiger, interaktiver Editor mit robustem Zustandsmanagement, flexibler Visualisierung und Undo/Redo-Funktionalität.