RustAst/docs/Roadmap.md

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.