ATLAS und Home Assistant

ATLAS besitzt mit @atlas/homeassistant ein eigenes Paket für die Home-Assistant-nahe Integration. Der aktuelle Schwerpunkt liegt auf einem Editor- und Export-Workflow für Home-Assistant-Karten, Live-Entitäten und spätere HACS-Nutzung.

Die ausführliche Bedien- und Funktionsdoku zum Editor liegt jetzt in der Plugin-Rubrik: Home Assistant Card Editor.

Plugin-Links in der Home-Assistant-Seitenleiste

Ab ATLAS App/Add-on 0.1.236 erzeugt der Sidebar-Dialog eine stabile Start-URL über Port 4176, zum Beispiel:

http://<ATLAS_HOST>:4176/launch/atlas.plugin.file-studio

Wenn ein Plugin bereits in der Home-Assistant-Seitenleiste eingetragen ist, öffne den Sidebar-Dialog in ATLAS erneut, kopiere die dort angebotene URL und ersetze damit den bisherigen url-Wert im zugehörigen panel_iframe- Eintrag. Alternativ kannst du den gesamten YAML-Block erneut kopieren und ersetzen. Starte Home Assistant anschließend neu, damit die Sidebar- Konfiguration neu geladen wird. Die Home-Assistant-Seitenadresse wie /atlas-studio/0 bleibt gleich; geändert wird die url des eingebetteten Panels. Port 4176 muss für den Browser erreichbar sein.

Aktueller Umfang

• ATLAS Status Preview mit Theme- und Renderer-Anbindung
• lokale und live geladene Home-Assistant-Entitäten
• Verbindung über Home-Assistant-WebSocket
• Token-Verwaltung in der Atlas Administration mit Übergabe und optionalem Auto-connect an die aktive Editor-Sitzung
• Laden der Entitäten über get_states
• Laden der Lovelace-Ressourcen über lovelace/resources
• gemeinsamer Entity-Katalog für Typfilter und Suche
• Card-Ziele für eingebaute Home-Assistant-Cards, Mushroom Template und Bubble Card
• Expert-Editor mit 12-Spalten-Raster, Drag-and-drop, Größenänderung und Container-Cards
• Container-Cards für vertical-stack, horizontal-stack und custom:tabbed-card-v2
• Card-Import per JSON/YAML, Datei, Zwischenablage und HACS-Bundle
• Erkennung von card_mod- und uix-Styles beim Import
• Layouts single, horizontal-stack, vertical-stack, grid, conditional und tabbed-card-v2
• JSON- und YAML-Export für Home-Assistant-Karten
• Atlas Card Packages und HACS-nahe Bundles für Editor-Roundtrips
• Import-Summary für importierte Karten

Arbeits-Kurzbefehle

Für die laufende ATLAS-Editor-Arbeit werden kurze Chat-Befehle verwendet, um wiederkehrende Schritte schnell auszulösen:

Kürzel	Bedeutung
??	nur antworten, nichts umsetzen
>>	den beschriebenen Schritt komplett umsetzen
>>!	ausführen und eine kurze Zusammenfassung ausgeben
<<	die letzte Änderung rückgängig machen
!!B / !!b	Backup vom aktuellen Stand erstellen
!!D / !!d	Open-Source-Dokumentation aktualisieren

Die Kurzbefehle können kombiniert werden. !!D !!B bedeutet zum Beispiel, dass der aktuelle Stand gesichert und die öffentliche Dokumentation passend aktualisiert wird.

Unterstützte Card-Ziele

Auswahl	Home-Assistant-Typ	Abhängigkeit
Entities	entities	in Home Assistant enthalten
Mushroom Template	custom:mushroom-template-card	Mushroom
Bubble Button	custom:bubble-card	Bubble Card
Tabbed Card V2	custom:tabbed-card-v2	ATLAS Tabbed Card V2

Entity Picker und Suche

ATLAS besitzt jetzt einen wiederverwendbaren Entity-Katalog im Paket @atlas/homeassistant. Dieser Katalog führt lokale Beispiel-Entitäten, gespeicherte Gruppen und live geladene Home-Assistant-Entitäten zusammen.

Der Katalog liefert:

• eindeutige und sortierte Entity IDs
• Domain-Erkennung wie sensor, binary_sensor, switch oder light
• bevorzugte Shortcut-Reihenfolge für häufige Domains
• Labels aus Live-Entitäten, zum Beispiel Friendly Names
• Suche nach Entity ID oder Label, auch mit Teilbegriffen wie Hyper

Damit bleibt der Entity Picker nicht nur Demo-Code, sondern wird zu einer gemeinsamen Grundlage für die spätere Home-Assistant-Frontend-Integration.

HACS- und Ressourcenhinweise

ATLAS legt die erwarteten Ressourcenpfade direkt in den Export-Metadaten ab. Die Demo kann dadurch anzeigen, ob eine Custom Card bereits in Home Assistant registriert ist oder welcher Pfad noch fehlt.

Card-Ziel	HACS-Hinweis	Erwarteter Ressourcenpfad
Entities	nicht erforderlich	in Home Assistant enthalten
Mushroom Template	HACS > Frontend > Mushroom	/hacsfiles/lovelace-mushroom/mushroom.js
Bubble Button	HACS > Frontend > Bubble Card	/hacsfiles/Bubble-Card/bubble-card.js

Alle erwarteten Home-Assistant- und HACS-Ressourcenpfade werden exakt mit Groß- und Kleinschreibung geprüft. Für Bubble Card ist der Pfad zum Beispiel absichtlich so hinterlegt:

/hacsfiles/Bubble-Card/bubble-card.js

Wichtig: Home Assistant läuft häufig auf Linux. Groß- und Kleinschreibung im Pfad sind dort für alle Ressourcen relevant.

ATLAS kann für Mushroom und Bubble Card außerdem einen kopierbaren Lovelace-Ressourcen-Snippet erzeugen. Der kombinierte Snippet enthält die ATLAS-Frontend-Resource und, wenn nötig, die gewählte Card-Abhängigkeit. Im YAML-Format sieht das zum Beispiel für ATLAS Server plus Bubble Card so aus:

- url: "/local/atlas/atlas-homeassistant-panel.js"
  type: "module"
- url: "/hacsfiles/Bubble-Card/bubble-card.js"
  type: "module"

Dieser Snippet ist für die Ressourcenregistrierung im Home-Assistant-Dashboard gedacht. Bei der eingebauten Entities Card wird nur die ATLAS-Frontend-Resource kopiert.

Export-Modell

ATLAS trennt den HA-Card-Export in drei Ebenen:

1. Card-Konfiguration: das eigentliche Home-Assistant-Card-Objekt.
2. Export-Manifest: Dateiname, Format, MIME-Type, Ziel, Layout und Abhängigkeit.
3. Export-Payload: Manifest plus serialisierter JSON- oder YAML-Inhalt.

Dadurch nutzen Kopieren und Download denselben geprüften Inhalt.

Atlas Card Packages

Zusätzlich zum direkten YAML/JSON-Export kann ATLAS ein portables JSON-Paket erzeugen. Dieses Paket ist für spätere Editor- und HACS-nahe Workflows gedacht. Wird ein Paket aus dem Expert-Modus exportiert, enthält es zusätzlich den Editorplan. Beim späteren Import kann ATLAS dadurch die platzierten Felder wiederherstellen und automatisch in den Expert-Modus wechseln. Das Demo-UI bietet dafür ein eigenes Feld für den HACS-Script-Dateinamen. Namen wie Energy Kitchen werden zu energy-kitchen.js normalisiert, im eingebetteten Editorplan gespeichert und beim erneuten Import eines Atlas Card Package wieder in das Feld übernommen. Zusätzlich kann der Paketplan nun eine Custom-Card-JavaScript-Quelle erzeugen. Dieses Script enthält den normalisierten Dateinamen, den passenden custom:<name>-Kartentyp, den /hacsfiles/atlas/...-Resource-Pfad, eine getStubConfig()-Vorgabe mit sicheren Demo-Entitäten und den Hinweis, diese Entitäten in Home Assistant durch eigene Werte zu ersetzen. In der Demo kann diese .js-Quelle auch direkt über den Card-Script-Export heruntergeladen werden, damit das Artefakt vor einem vollständigen HACS-Bundle separat geprüft werden kann. Der nächste Paketierungsschritt erzeugt ein abhängigkeitsfreies .hacs.zip. Das Archiv enthält die Dateien für ein späteres Frontend-Repository: hacs.json, die generierte JavaScript-Card, eine README, eine Beispiel-Lovelace-Card und das ursprüngliche Atlas Card Package für spätere Bearbeitung. Die Demo kann solche .hacs.zip-Dateien beim HA-Card-Import wieder erkennen. Sie liest die ZIP-Struktur, meldet fehlende Bundle-Dateien und importiert das eingebettete atlas/*.atlas-card.json wieder in den Expert-Editor. Damit ist ein erster HACS-Bundle-Roundtrip möglich.

{
  "version": 1,
  "kind": "atlas.homeassistant.card",
  "manifest": {
    "name": "Office Light",
    "filename": "office-light-bubble-single.yaml",
    "format": "yaml",
    "mimeType": "text/yaml",
    "target": "bubble",
    "layout": "single"
  },
  "content": "type: \"custom:bubble-card\"\n..."
}

In der Demo enden diese Dateien auf:

.atlas-card.json

Der gleiche Import kann rohe Home-Assistant-Karten als JSON/YAML und Atlas Card Packages einlesen.

Vor dem eigentlichen Import kann ATLAS Artefakte prüfen und einordnen:

• ATLAS Card Package
• rohe Home-Assistant-Card als JSON oder YAML
• möglicher externer Card-Builder-Export
• unbekannter Inhalt

Externe Card-Builder-ähnliche Dateien werden dabei nicht automatisch importiert. Sie benötigen zuerst ein bewusstes Kompatibilitäts-Mapping und eine Lizenzprüfung.

Aus dieser Prüfung entsteht eine Import-Entscheidung für die Oberfläche:

• Import: unterstützte ATLAS- oder Home-Assistant-Artefakte.
• Review: externe Card-Builder-ähnliche Artefakte.
• Reject: unbekannte oder nicht sicher einordenbare Inhalte.

Für den Review-Fall liefert ATLAS bereits strukturierte Prüfpunkte: Lizenzgrenze, erkannte visuelle Blöcke, erkannte Entity-Slots und den nächsten Schritt zur Schema-Zuordnung. Eine Oberfläche kann daraus später einen Dialog bauen, bevor ein externes Artefakt in ATLAS-Felder umgewandelt wird.

Zusätzlich kann ATLAS eine Mapping-Vorschau erzeugen. Häufige externe Blocktypen werden dabei ATLAS-Templates zugeordnet: State-ähnliche Blöcke zu State Buttons, Switch-ähnliche Blöcke zu Switch Buttons und horizontale oder vertikale Layout-Blöcke zu passenden Stack-Templates. Nicht erkannte Blöcke bleiben sichtbar und müssen manuell bewertet werden.

Aus einer Mapping-Vorschau kann ATLAS außerdem eine geprüfte Field-Preview für die Expert-Fläche erzeugen. Die Felder werden im Raster platziert, enthalten aber zunächst leere Entitäten und bleiben review-pflichtig. So kann die Oberfläche eine Umwandlung zeigen, ohne sie still zu importieren.

Die Card-Editor-Demo nutzt diese Prüfung inzwischen direkt vor dem HA-Card-Import. Unterstützte ATLAS-Packages und rohe Home-Assistant-Cards werden importiert, externe Card-Builder-ähnliche Dateien zeigen eine Review-Ausgabe, und unbekannte Artefakte werden vor dem Parsen abgelehnt. Die ATLAS Status Preview bleibt als Renderer-, Theme- und Entitäts-Smoke-Test erhalten, liegt aber jetzt im einklappbaren Diagnostics-Bereich und steht nicht mehr im Hauptfluss des Card-Editors. Ob Diagnostics geöffnet ist, wird mit der lokalen Demo-Konfiguration gespeichert.

Außerdem enthält die Demo inzwischen den visuellen Expert-Editor. Er verwendet die gemeinsame Template-Palette, erlaubt die Auswahl einer Card-Familie, platziert Felder per Klick oder Drag-and-drop im begrenzten 12-Spalten-Raster und rendert daraus verschachtelten Home-Assistant-Card-Code. Felder können ausgewählt, verschoben, gelöscht und im Bearbeiten-Modus in der Größe geändert werden. Beim Ablegen sucht ATLAS eine freie Rasterposition, damit neue oder verschobene Felder nicht auf bereits belegten Kacheln landen.

Der Importpfad akzeptiert jetzt auch verschachtelte Home-Assistant-Karten. Eine reale vertical-stack-Karte kann also horizontal-stack-Zeilen, grid-Container, conditional-Karten und einzelne Karten enthalten; ATLAS behält die unterstützte Struktur und extrahiert die enthaltenen Entitäten. Bubble-Header oder Separatoren ohne Entity werden ebenfalls akzeptiert. Handgebaute Bubble-Switch-Spalten und empty-column-Karten werden ebenfalls erkannt. Erweiterte Bubble-Card-Details wie modules, styles, grid_options, Slider und Sub-Buttons sind als spätere Erhaltungsschicht geplant. Handgeschriebene custom:tabbed-card-v2-Cards mit tabs[].card und verschachtelten Stack-Bereichen werden ebenfalls erkannt und im Expert-Modus als Tabbed-Container geöffnet.

Card-Layout-Editor

ATLAS entwickelt sich in Richtung eines visuellen Editors, mit dem Nutzer eine Home-Assistant-Card per Drag-and-drop aufbauen können. Dabei bleiben Cardname und JavaScript-Dateiname getrennt: Ein Nutzer kann also zum Beispiel eine Card Energy Kitchen nennen und daraus später eine installierbare Datei energy-kitchen.js erzeugen, statt auf einen festen Namen wie atlas-card.js beschränkt zu sein.

Für den späteren HACS-Card-Paket-Export ist außerdem vorgesehen, Demo-Entitäten wie binary_sensor.atlas_status und sensor.atlas_temperature als sichere Vorgabe mitzugeben. Die Oberfläche soll dabei klar darauf hinweisen, dass diese Beispiel-Entitäten durch eigene Home-Assistant-Entitäten ersetzt werden müssen.

Der Editor startet direkt im Expert-Workflow. Der frühere sichtbare Simple-Modus und der Simple/Expert-Umschalter wurden entfernt, damit die Bedienung kompakter bleibt und die freie Editor-Fläche im Mittelpunkt steht. Pro Feld ist der Card-Typ wählbar, zum Beispiel Entities, Bubble Card, Mushroom Template, vertical-stack, horizontal-stack oder Tabbed Card V2.

Aus dem Editor-Plan leitet ATLAS die tatsächlich genutzten Card-Ziele ab. Bei einem gemischten Expert-Layout erkennt ATLAS dadurch gemeinsam, ob zum Beispiel Mushroom und Bubble Card als HACS-Ressourcen benötigt werden, während reine Entities-Felder keine zusätzliche Custom-Card-Resource brauchen.

Zusätzlich kann ein Editor-Plan in eine Home-Assistant-Card-Konfiguration übersetzt werden. Der Expert-Workflow sortiert belegte Felder nach Zeile und Spalte. Mehrere Felder in derselben Zeile werden zu einem horizontal-stack; mehrere Zeilen werden mit einem vertical-stack zusammengefasst. Ein einzelnes Feld kann außerdem selbst als horizontal-stack oder vertical-stack markiert werden und mehrere Card-Einträge enthalten. custom:tabbed-card-v2 wird als eigener Container unterstützt: Tabs werden im Popup eingerichtet, ausgewählt und anschließend mit Cards befüllt. Container starten absichtlich ohne Entity und ohne automatisch erzeugte erste Card. Beim Anlegen erhalten sie technische, fortlaufende Titel wie Tabbed 1, Vertical 1 oder Horizontal 1; Cards im Container behalten eigene Titel. Die HACS-Card unterstützt zusätzlich eigene Style-Variablen für aktive und inaktive Tab-Hintergründe; die vollständige Liste steht in der Card-Editor-Dokumentation. Wenn ein Expert-Plan noch keine belegten Felder enthält, nutzt ATLAS die Demo-Entitäten als sicheren Fallback.

In der Demo sind der einfache Card-Layout-Wähler und der normale HA-Card-Code ausgeblendet. Export, Package-Export, Kopieren und Ressourcen-Kopieren verwenden den Expert-HA-Card-Code aus der Editor-Fläche. Ressourcen-Kopieren nimmt alle platzierten Mushroom- und Bubble-Abhängigkeiten gemeinsam mit der ATLAS-Frontend-Resource auf. Auch Panel group, Group name, Card target, Card layout sowie die Gruppen-Aktionsbuttons werden ausgeblendet, weil die Editor-Fläche die zu exportierende Card-Struktur direkt bestimmt. Der Editor nutzt dafür ein eigenes Feld Expert card name für Kopieren, Export und Paket-Dateinamen.

Für die Bedienung ist eine seitliche Template-Palette vorgesehen. Dort können visuelle Bausteine wie Entity List, State Button, Switch Button, vertical-stack und horizontal-stack angeboten werden. In der Demo ist daraus bereits eine linke Palette ohne Modus-Umschaltung geworden: Der Nutzer kann einen Baustein anklicken oder per Drag-and-drop in die Editor-Fläche ziehen. Hinzugefügte Felder erscheinen als verschiebbare Kacheln auf der Rasterfläche. Die Fläche nutzt ein sichtbares 12-Spalten-Raster, das näher an Home Assistant erinnert. Beim Verschieben vorhandener Felder nutzt ATLAS das echte innere Raster und erhält den Punkt, an dem die Kachel gegriffen wurde; dadurch lassen sich Felder nach oben ziehen, ohne seitlich zu springen. Das sichtbare Raster liegt auf derselben inneren Fläche wie die Kacheln, mit kleinerem Kachelabstand für dichteres Stapeln. Fokussierte Kacheln lassen sich zusätzlich per Pfeiltasten um je eine Rasterzelle verschieben; im Bearbeiten-Modus ändert Shift plus Pfeiltaste die Größe des ausgewählten Feldes in 1er-Schritten. Jeder Baustein in der linken Palette kann eigene Spalten von 1 bis 12 oder full sowie Zeilen auto oder 1 bis 8 vorgeben. Entity List, State Button, Switch Button, horizontal-stack und vertical-stack starten mit derselben Standardfläche; Horizontal-Stacks können bei mehreren ausgewählten Entitäten entsprechend breiter werden. Die Palette kann geladene Lovelace-Ressourcen nutzen, um Custom-Card-Familien als installiert, fehlend oder ungeprüft zu markieren. Beim Platzieren auf der Expert-Fläche klemmt ATLAS Spalte, Zeile und Größe an die erlaubten Rastergrenzen, damit Elemente nicht außerhalb der gültigen Fläche landen. Platzierte Felder können ausgewählt und über einen Bearbeiten-Modus angepasst werden. Erst im Bearbeiten-Modus erscheint der rechte untere Anfasser, mit dem die Feldgröße innerhalb des 12-Spalten-Rasters verändert wird. Die Titel platzierter Felder sind editierbar. Neue Felder bekommen zunächst einen automatisch gezählten Titel nach Typ, zum Beispiel Entity 1, Bubble 1, Mushroom 1, Tabbed 1, Vertical 1 oder Horizontal 1. Dieser Titel wird im Export als Entities-Title, Bubble-Button-Name oder Mushroom-Primary-Text verwendet. Ein Apply-Button übernimmt den manuell editierten Titel in das ausgewählte Feld. Der bestehende Übernahme-Button kann zusätzlich den aktuell gewählten Home-Assistant-Entitätsnamen direkt als Titel einsetzen. Im Expert-Modus weist eine Entitätsauswahl aus Picker oder Entitätsliste die Entität dem aktuell ausgewählten Editor-Feld zu und füllt den Titel mit dem Entitätsnamen vor. Für Bubble-Felder zeigt ATLAS zusätzlich einen Bubble-Button-Type-Dropdown. Aktuell unterstützt sind state, switch, slider und name; der Wert wird als button_type in den generierten Bubble-Card-Code geschrieben. Die linke Expert-Palette trennt Core- und Community-Cards. Einzelne Cards können per Häkchen als Favoriten markiert und über Save favorites gespeichert werden. Sobald Favoriten gespeichert sind, blendet ATLAS alle anderen Cards aus. Show all cards öffnet die vollständige Liste erneut, ohne die gespeicherten Favoriten zu löschen. Zusätzlich können nicht benötigte Einträge über eine rote Versteckt-Checkbox aus der normalen Palette ausgeblendet und in der vollständigen Liste wieder eingeblendet werden. Eine weitere opt-in Option kann unbekannte registrierte Ressourcen automatisch aus dem Dateinamen einem custom:* Card-Typ zuordnen; sie steht unter den Import-Werkzeugen und ist mit einem roten Sicherheitshinweis markiert. Dadurch können mehrere Favoriten bequem nachträglich ausgewählt und danach gemeinsam gespeichert werden. Scan HA cards liest die aktuell registrierten Lovelace-Ressourcen aus Home Assistant und ergänzt erkannte Community-Cards wie Mushroom und Bubble Card in der Palette. Home Assistant liefert darüber keine vollständige Options-Registry für jede beliebige Custom-Card, aber installierte Ressourcen lassen sich so als Ausgangspunkt erkennen. Andere registrierte Lovelace-Ressourcen werden als Scan-only-Einträge sichtbar, bis ATLAS dafür ein fest eingebautes Card-Mapping kennt. Der Nutzer kann solche Einträge lokal einem passenden custom:* Card-Typ zuordnen. Danach sind sie als gemappte Custom Cards ziehbar, werden im Expert-YAML mit diesem Card-Typ exportiert und ihr Resource-Pfad wird beim Ressourcen-Snippet mitgeführt. Bereits gemappte Ressourcen werden dedupliziert, damit sie nicht noch einmal als Scan-only-Kopie erscheinen. Die Core-Liste enthält jetzt Entität, Entitäten, Übersicht/Glance, Button, Raster, Sensor, Stapel, Querstapel, Thermostat, Verknüpfung und Webseite. Die Webseite wird im Export als Home-Assistant-iframe-Card geschrieben. Die Übersicht/Glance-Vorlage startet ohne Demo-Entität, erhält automatisch Namen wie Glance 1 oder Glance 2 und wird über ein eigenes Entitäten-Popup befüllt. Beim Verbinden mit Home Assistant fordert ATLAS diese Ressourcenliste automatisch an. Gespeicherte Favoriten blenden alle nicht ausgewählten Cards aus, inklusive gescannter /hacsfiles/-Einträge. Versteckte Cards bleiben in der normalen Ansicht ausgeblendet, bis Show all cards genutzt und die Versteckt-Markierung wieder entfernt wird. Gemappte Scan-only-HACS- und HA-Ressourcen können ebenfalls als Favoriten markiert werden. Hilfsressourcen wie Card-Tools, Dashboards, Strategien, Navigationshelfer, Icon-Pakete und bekannte Nicht-Card-Ressourcen werden beim Palette-Scan ausgeblendet. Der temporäre Ressourcencheck besitzt einen zuschaltbaren Debugbereich. Über Ressourcen-Debug anzeigen kann der Verlauf der WebSocket- und Admin-Proxy-Abfragen eingeblendet werden, um zu sehen, ob der Browser-WebSocket, der Admin-WebSocket-Proxy oder ein Fallback hängt. Die Home-Assistant-Entitätenliste wird lokal im Browser gecacht. Beim Öffnen steht der zuletzt bekannte Katalog sofort für Filter und Picker bereit; bei einer Verbindung mit Home Assistant synchronisiert ATLAS die Live-Liste und zeigt unter dem Verbindungsstatus an, ob der Katalog aus dem Cache kommt, noch synchronisiert, fertig geladen ist oder ein Fehler aufgetreten ist. Die Meldung nennt auch neue und entfernte Entitäten. Ein Reset-Button zeigt wieder die vollständige Liste. Die Palette selbst ist scrollbar und nutzt kompakte zweispaltige Template-Zeilen: Card-Name und Favoritenstatus stehen links, Layout-Details und Größensteuerung rechts. Spalten- und Zeilenvorgaben der Templates werden mit der lokalen Demo-Konfiguration gespeichert und können über Reset sizes wieder auf die Standardwerte zurückgesetzt werden. Ausgewählte Editorfelder können mit der Maus oder über Breite und Höhe in 1er-Schritten verändert werden, bis zu fünf Rasterzellen über die Template-Standardgröße hinaus. Die Editorfläche selbst hat unten rechts einen sichtbaren Anfasser und kann in beide Richtungen um bis zu fünf Rasterschritte vergrößert werden; die aktuelle Größe bleibt der Standard. Ein Reset-Button setzt die Editorfläche wieder auf die Standardgröße zurück. Platzierte Expert-Felder, das ausgewählte Feld und die vergrößerte Editorfläche werden lokal im Browser gespeichert und nach einem Neuladen wiederhergestellt. Die Demo-Oberfläche ist jetzt zweisprachig: Über den Sprachumschalter im Kopf kann zwischen Deutsch und Englisch gewechselt werden. Die Auswahl wird ebenfalls lokal gespeichert und beim nächsten Öffnen wiederhergestellt. Neben statischen Labels werden auch Entity-Picker-Rückmeldungen, Stack-Zusammenfassungen, Dependency-Hinweise sowie wichtige Import-/Export-Statusmeldungen über die gemeinsame Übersetzungstabelle ausgegeben. Die Expert-Zusammenfassung nennt Felder, befüllte Felder, leere Platzhalter, belegte Reihen, aktuelle Surface-Ausdehnung, Überschneidungen, Card-Ziele und Layouttypen, bevor der generierte HA-Card-Code kopiert oder exportiert wird. Überlappende Editorfelder werden direkt auf der Fläche markiert. Auto arrange packt Felder in Zeilen- und Spaltenreihenfolge auf die ersten freien Rasterplätze und reduziert Überschneidungen, ohne den Card-Inhalt zu verändern. Beim normalen Drop und beim Verschieben sucht ATLAS ebenfalls nach einem freien Zielplatz, wenn die gewünschte Rasterposition bereits belegt ist. Die Liste der ausgewählten Entitäten unterhalb des Editors ist einklappbar und standardmäßig zugeklappt, kann aber bei Bedarf geöffnet werden.

YAML-Import und Styles

Der Editor kann rohe Home-Assistant-Card-Konfigurationen als YAML oder JSON einlesen. YAML kann über ein Eingabefenster eingefügt, aus der Zwischenablage übernommen oder als Datei mit Endungen wie .yaml, .yml oder .txt geladen werden. Der importierte YAML-Code bleibt für den HA-Card-Code weitgehend im Original erhalten; Atlas ergänzt oder ändert ihn nur dort, wo der Nutzer im Editor tatsächlich etwas anpasst.

Beim Import erkennt ATLAS card_mod- und uix-Styles. Entity-nahe Styles werden den importierten Entities in der Vorschau zugeordnet und dort über ein kompaktes Style-Popup angezeigt. In der Übersicht/Glance-Entitätenbearbeitung stehen erkannte Entity-Styles zusätzlich direkt unter der jeweiligen Entität als einklappbarer Style-Code. Globale Card-Styles bleiben getrennt sichtbar. Beim Expert-Export bleiben die zugeordneten Entity-Styles an den passenden Entity-Blöcken erhalten. Beim HA-Card-Export kann der Nutzer wählen, ob Styles als card_mod erhalten oder als uix ausgegeben werden sollen.

Externe Referenz: Home Assistant Card Builder

Das Projekt studiobts/home-assistant-card-builder ist eine wichtige externe Referenz für visuelle Home-Assistant-Card-Editoren. Es bietet bereits einen Drag-and-drop-Builder, ein Blocksystem, ein eigenes Home-Assistant-Panel und einen Renderer.

ATLAS übernimmt daraus aktuell keinen Quellcode. Das Projekt steht unter AGPL-3.0, daher würde ein echter Fork oder eine abgeleitete Nutzung klare Lizenz- und Attribution-Pflichten auslösen. Für ATLAS ist der geplante Weg: eigenständige Verträge und UI-Modelle bauen, das Original klar nennen und später optional Import-/Export-Kompatibilität oder einen bewusst gekennzeichneten Fork prüfen.

Der Interop-Plan trennt drei Pfade:

• Inspiration: öffentliche Produktideen und dokumentiertes Verhalten fließen in eigenständige ATLAS-Verträge ein.
• Import/Export-Kompatibilität: später kann ATLAS dokumentierte Artefakte prüfen und eigene Mappings anbieten, ohne Quellcode zu kopieren.
• Fork/Derivative: nur als bewusste Entscheidung mit AGPL-3.0-Erfüllung, sichtbarer Attribution und vollständiger Lizenzprüfung.

Import-Summary

Beim Import normalisiert ATLAS die Karte in eine Zusammenfassung:

• Titel
• Entitäten
• Format
• Ziel
• Layout
• Abhängigkeit
• Information, ob die Quelle ein Atlas Card Package war

Damit bleibt die eigentliche Editor-Logik im Paket @atlas/homeassistant und nicht verstreut in der Oberfläche.

Lovelace-Ressourcenprüfung

Wenn ATLAS mit Home Assistant verbunden ist, kann die Demo Lovelace-Ressourcen abrufen und prüfen, ob Mushroom oder Bubble Card registriert sind.

Mögliche Zustände:

• not-required: Entities Card benötigt keine Custom-Card-Ressource
• unchecked: noch nicht geprüft
• installed: erwartete Ressource gefunden
• missing: erwartete Ressource fehlt

ATLAS als Home-Assistant-Frontend

ATLAS unterscheidet jetzt auch die Resource, die ATLAS selbst in Home Assistant verfügbar macht. Das ist getrennt von der gewählten Card-Abhängigkeit.

Nutzungsart	Zweck	Erwarteter Ressourcenpfad
ATLAS Server	selbst gehosteter ATLAS-Editor oder Panel	/local/atlas/atlas-homeassistant-panel.js
ATLAS HACS	geplante HACS-Frontend-Integration	/hacsfiles/atlas/atlas-homeassistant-panel.js

Die neue Integrationsplanung kann dadurch gemeinsam prüfen:

• ist die ATLAS-Frontend-Resource registriert?
• ist die gewählte Card-Resource installiert?
• fehlen bei Mushroom oder Bubble Card zusätzliche HACS-Pfade?
• ist der gesamte Export bereit für Home Assistant?
• welche JSON- oder YAML-Resources sollen in Home Assistant registriert werden?

Damit ist der nächste Schritt in Richtung “ATLAS direkt in Home Assistant nutzen oder als HACS-nahe Integration installieren” vorbereitet.

Aktuelle Demo

Im ATLAS-Repo lässt sich die Demo nach dem Build starten:

pnpm build
node examples/status-demo/server.mjs

Standardadresse:

http://127.0.0.1:4174/

Auf breiten Bildschirmen nutzt die Demo kompakte Zwei- und Drei-Spalten-Raster für Verbindung, Card-Konfiguration und Entity-Picker, damit zusammengehörige Eingaben nebeneinander statt über die gesamte Seitenbreite laufen.

Roadmap

Die Home-Assistant-Integration zielt auf zwei Nutzungsarten:

• ATLAS als eigenständiger Server oder Editor
• ATLAS als Home-Assistant-Frontend-Integration, später auch HACS-nah

Die aktuellen Card Packages sind ein Zwischenschritt auf dem Weg zu einem installierbaren und wieder importierbaren HA-Card-Editor.

Beim Export von Card Packages und HACS-Bundles fragt der Card Editor die gewünschten Card-Sprachen separat ab. Das betrifft nur die exportierte Card, nicht die Atlas-Oberfläche selbst. en ist immer als Pflicht-Fallback enthalten, weitere europäische Sprachen können per Checkbox ausgewählt werden, inklusive ru für russischsprachige Nutzer. Solange keine automatische Übersetzung aktiv ist, erzeugt ATLAS für zusätzliche Sprachen englische Fallback-Dateien mit einem Hinweis, dass die entsprechenden locales/*.json Dateien vor einer Veröffentlichung übersetzt und geprüft werden müssen.

Die Atlas Administration verwaltet die geplante Auswahl des Übersetzungsmoduls. Vorgesehen sind zunächst none, chatgpt, gemini, deepl-free, deepl-pro und custom-ai. Die Auswahl soll als klare Radio-Liste mit API-Key-Feldern für die jeweiligen Provider erfolgen. Im Card Editor kann beim Export eine Checkbox für automatische Übersetzung aktiviert werden. Die Oberfläche zeigt dabei einen Fortschritt an. Bis echte Provider-Adapter und API-Schlüssel angebunden sind, bleibt das Ergebnis bewusst als Fallback markiert, damit keine unübersetzten Dateien versehentlich als maschinell übersetzt gelten. Eine spätere echte automatische Übersetzung muss klar darauf hinweisen, dass dafür eine Internetverbindung erforderlich ist. Fuer DeepL ist https://www.deepl.com/de/pro#api als Referenz fuer die Free/Pro-API-Optionen vorgemerkt. Der vorbereitete DeepL-Translate-Endpunkt ist https://api.deepl.com/v2/translate; die Request-Details werden ueber https://developers.deepl.com/api-reference/translate/request-translation nachgehalten. Dieser Endpunkt ist interne Konfiguration und soll nicht als normales Eingabefeld in der Atlas Administration erscheinen. Fuer Gemini ist https://ai.google.dev/gemini-api/docs/api-key als Referenz für API-Key- und Sicherheitshinweise vorgemerkt. Provider-API-Keys gehören in die Atlas Administration oder spätere Backend-Adapter; der Card Editor soll nur Provider, Endpunkt und Key-konfiguriert-Status erhalten. ChatGPT/OpenAI ist der erste angebundene Adapterpfad. Der Card Editor ruft dafür die Atlas Administration über /api/card-translation auf, und der Admin-Server nutzt den dort gehaltenen OpenAI-Key für die OpenAI Responses API. Erfolgreich erzeugte Locale-Dateien werden als machine markiert und müssen vor einer Veröffentlichung weiterhin geprüft werden. Der verwendete OpenAI-Modellname kann serverseitig über ATLAS_OPENAI_TRANSLATION_MODEL überschrieben werden. Nach einem Reload der Atlas Administration stellt die Admin-Seite den Home-Assistant-Token und Provider-API-Keys aus einem verschlüsselten Langzeit-Admin-Cookie wieder her. Der browserseitige Entschlüsselungsschlüssel bleibt in der lokalen Admin-Speicherung, damit der Cookie selbst keine rohen Provider-Keys und keinen rohen Token enthält. Zusätzlich kann die Admin-Seite Secrets vom laufenden lokalen Admin-Server über GET /api/admin-connection?includeSecrets=1 auffrischen. Die rohen Keys und der rohe Token werden weiterhin nicht in den gemeinsamen Handoff-Cookie oder in Card-Editor-Handoff-Payloads geschrieben. Für Sicherungen kann die Administration atlas-admin-settings.json exportieren: normale Einstellungen bleiben lesbar, Token und Provider-API-Keys liegen darin als AES-GCM- verschlüsselter encryptedSecrets-Block. Diese verschlüsselten Secrets sind zusätzlich an die lokale Atlas-Administration-Installation gebunden. Der Admin-Server erzeugt dafür eine Installationskennung in lokalen Benutzerdaten außerhalb des Repos oder nutzt ATLAS_INSTANCE_ID, wenn eine Docker- oder Serverinstallation bewusst eine stabile Identität bekommen soll. Wird nur der Serverordner oder eine Exportdatei auf eine fremde Umgebung kopiert, gelten die Secrets als ungültig. Normale Einstellungen können später weiterhin migrierbar bleiben; für Secrets braucht ein bewusster Umzug eine eigene Transfer- oder Passphrase-Funktion.

Als späteres Folgeprojekt ist die Lovelace UV Card vorgesehen. Für diese Card ist filipnet/haos-uv-index als Inspirationsquelle vorgemerkt. Wichtig sind dabei nicht Code-Übernahme, sondern Produktideen: UV-Index-Sensor, farbcodierte Risikoanzeige, WHO-nahe Schutzempfehlungen, Mushroom-kompatible Darstellung und optionale Benachrichtigungs-Automationen.

Der Home-Assistant-Card-Editor wird dabei als erstes offizielles ATLAS-Referenz-Plugin betrachtet. Er soll später zeigen, wie ein Plugin Entitätenauswahl, Card-Targets, Import/Export, HACS-nahe Pakete und Administration in einem echten Workflow verbindet.

Im Atlas-Paket wird dieser Schritt bereits durch createHomeAssistantCardEditorPlugin() vorbereitet. Damit kann der Editor über die Runtime-Plugin-Schnittstelle aktiviert und über den Plugin-Katalog gefunden werden. createHomeAssistantCardEditorPluginInstallPackage() erzeugt zusätzlich ein erstes Installpaket mit Manifest, README und Beispielkonfiguration.

Dieser Plugin-Schritt ist bereits sichtbar: Die minimale Atlas Administration läuft als eigene Oberfläche auf Port 4175, getrennt vom Card Editor auf Port 4174. Sie zeigt den Card Editor als installiertes Referenz-Plugin und exportiert das Plugin-Paket als .atlas-plugin.json. Die Admin-Fläche markiert zugleich die spätere Sicherheitsgrenze: Tokens und Verbindungseinstellungen liegen zentral in Atlas. Der Editor erhält den Token nur als Sitzungsübergabe aus der Administration, während Plugins nur freigegebene Pfade, URLs und Fähigkeiten erhalten.