Desktop app for designing parametric 3D models in CadQuery together with the coding agent of your choice
TypeScript 3d-modeling3d-printing3d-printing-toolsagentagentic-aiai-cadcadcadqueryclaude-codecodexelectronfemllmmacdmakeropencodeparametric-designpythonsteptext-to-cad
App: Tutorial für neue Nutzer (E94)
Kai-Jungsthoefelacd917f72da0
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex bb43d08..86205ed 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -10,6 +10,7 @@ the version is bumped.- The packages include `THIRD_PARTY_NOTICES.md` and the license texts of all bundled npm packages.- `SECURITY.md` explains how to report vulnerabilities privately, and issue templates ask for the system info from Settings > About.+- Tutorial for new users: the start page shows "New to SOMA?" with "Start tutorial" and "Got it". The tutorial opens an example model and walks through the window in ten steps (agent, code, selecting, measuring, mark up, parameters, history, saving and export, help), with the right button highlighted. Help can start it again at any time.### Changeddiff --git a/CLAUDE.md b/CLAUDE.mdindex 0e6d8ef..bce836a 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -21,7 +21,7 @@ Details in `app/README.md`.**`app/`** Electron app- `src/main/` main process. Projects: `projects.ts` (save, open, history, export), `git.ts`, `zip.ts`, `workspace.ts`, `files.ts`, `watcher.ts`. Building and display: `build.ts` (prewarmed Python process), `previews.ts`, `measure.ts`, `dxf.ts` (E80), `render.ts` + `bridge.ts` (`soma render`), `animations.ts`. Agent and skills: `terminals.ts`, `agents.ts`, `skills.ts`, `skilllibrary.ts` (own skills, E78). Environment: `packages.ts` (project environment, E67), `params.ts` (parameter panel, E74). App: `settings.ts`, `storage.ts`, `about.ts` (E81), `help.ts` (E83), `dialogs.ts`.- `src/preload/` the only bridge to the renderer.-- `src/renderer/` interface, wired up in `main.ts`. Viewer: `viewer.ts`, `viewcube.ts`, `tree.ts` (structure tree, E82), tools `sectiontool.ts`, `explodetool.ts`, `measuretool.ts`, `markup.ts`. Panels: `code.ts`, `pdfview.ts`, `dxfview.ts`, `markdown.ts`, `filetree.ts`, `versions.ts`, `terminals.ts`, `params.ts`, `skills.ts`, `help.ts`, `settings.ts` + `settingspages.ts`. Animation and analysis: `animtool.ts`, `animpanel.ts`, `animdata.ts`, `overlay.ts`, `resulttool.ts`, `resultview.ts`, `analysispanel.ts`, `videoview.ts`. Render window: `render.ts`/`render.html`. General: `ui.ts`, `icons.ts`, `busy.ts`, `shortcuts.ts`, `style.css`.+- `src/renderer/` interface, wired up in `main.ts`. Viewer: `viewer.ts`, `viewcube.ts`, `tree.ts` (structure tree, E82), tools `sectiontool.ts`, `explodetool.ts`, `measuretool.ts`, `markup.ts`. Panels: `code.ts`, `pdfview.ts`, `dxfview.ts`, `markdown.ts`, `filetree.ts`, `versions.ts`, `terminals.ts`, `params.ts`, `skills.ts`, `help.ts`, `settings.ts` + `settingspages.ts`, `tutorial.ts` (guided tour, E94). Animation and analysis: `animtool.ts`, `animpanel.ts`, `animdata.ts`, `overlay.ts`, `resulttool.ts`, `resultview.ts`, `analysispanel.ts`, `videoview.ts`. Render window: `render.ts`/`render.html`. General: `ui.ts`, `icons.ts`, `busy.ts`, `shortcuts.ts`, `style.css`.- `src/shared/` `types.ts` (IPC contract), `settings.ts` (defaults, validation, mouse bindings, E81), `editable.ts`, `help.ts`, `skillname.ts`, `version.ts`.- `resources/` `template/` (template for user projects incl. `AGENTS.md`), `skills/` (bundled skills, among them `soma-app.md` as the user guide for help and agent, E83), `help/` (images of the guide), `icon.*` (generated with `scripts/make-icon.py`).- `test/` test suites, CDP client, screenshots. `SOMA_TEST_EXE` runs them against a packaged app.diff --git a/app/README.md b/app/README.mdindex 02663dc..3850d99 100644--- a/app/README.md+++ b/app/README.md@@ -29,10 +29,11 @@ npm run test:drawing # Technische Zeichnungen (E76): Codeblock des Skills ohnenpm run test:dxf # DXF-Ansicht (E80): soma dxfview mit Einheit, Größe, Layern, Kurven, Linientyp als Striche, Nicht-Zeichenbares, gleiche Ausgabe, kaputte Datei; in der App Öffnen per Klick im Dateibaum, Layer aus und ein (auch im Menü, ausgeschaltete aus der Datei), Zoom, Neuladen mit Ausschnitt, Mark up view mit Bereich, kaputte und gelöschte Datei (23 Prüfungen)npm run test:animation # Animation, Analyse, soma render und Video: Bauen über den Watcher, Ablauf als Text, Kollisionsprüfung, Fehler mit Ort, Abspielen im Viewer (Lage, Hervorhebung, Kamera), Ausschluss mit Explosion und Messen, Verbindung mit Schlüssel, Bild, Übersicht, MP4 mit WebVTT, Video abspielen und Standbild markieren, Überhang, Wandstärke, Abstand mit Anzeige und Neu berechnen, Beispiel des Skills, ohne App Grenzwert mit Netzgenauigkeit, Teil vor Gruppe, Problemstellen, bessere Druckrichtung, kurze Schritte als eine Zeile, Modell nur einmal ausgeführt soma render mit Richtung, Ausblenden, Einpassen und Zoom (65 Prüfungen)npm run test:settings # Einstellungen (E81): Reiter, Mausbelegungen (SOMA, SolidWorks, Fusion, Onshape) mit Ziehen und Klick, Zoomrichtung, orthografisch (Bildgröße, Auswählen, verdeckte Kanten beim Messen), Nachkommastellen in der offenen Messung, Darstellung beim Öffnen, Speicherplatz und Vorschau-Cache leeren, About mit Versionen, Komponenten und Kopieren, Neustart, kaputte settings.json mit Sicherung (45 Prüfungen)+npm run test:tutorial # Tutorial (E94): Karte auf der Startseite, „Got it“ über einen Neustart, kaputte settings.json, Modell „Tutorial“, Next, Back, Skip, Escape, Ziel jedes Schritts vorhanden und Karte im Fenster, Haken beim Ausprobieren, fehlendes Ziel, Neustart aus der Hilfe mit Rückfrage, unverändertes Tutorial-Modell verschwindet (31 Prüfungen)npm run test:packages # Projektumgebung: klein, pip im Terminal installiert dorthin, Basispakete vorhanden und in der Version festgelegt, requirements.txt aus den Importen des Builds, nicht in Git und ZIP, alter Stand mit eigener Liste, anderer Rechner installiert vor dem Build, Paket ohne Quelle als Hinweis (26 Prüfungen, ohne Netz mit lokalen Wheels)npm run test:params # Parameter (E74): Panel aus der Leiste, Werte in parameters.json statt im Code, Zurücksetzen einzeln und alle, Komma, Bereich (rot, trotzdem gebaut), Schieber, Sprung in den Code, An Agent geben, Typen (Stepper, Schalter, Auswahl, Text), Gruppen, unpassende Werte und Werte ohne Parameter, gescheiterter Build mit „Back to“, Syntaxfehler vor den Parametern, kaputte Datei, Snapshot und ZIP, leerer Zustand, Bereich des Agenten in der Zeile, Auswertungen mit den Werten des Nutzers und veraltet nach einer Änderung (46 Prüfungen)node test/run-all.mjs fem # FEM: Kragbalken gegen die Formel, verschmolzene Teile mit Druck und Eigengewicht, Fehler (Lagerung, Bauteil, Selektor, kein fix, Code), Karte mit Lastfall und Überhöhung, Wert in Ausgangslage, soma render --result, veraltet nach Änderung der Studie, Neu berechnen, Beispiel des Skills (24 Prüfungen)-npm test # alle siebzehn, vier gleichzeitig (test/run-all.mjs)+npm test # alle achtzehn, vier gleichzeitig (test/run-all.mjs)node test/run-all.mjs smoke editor # nur diese, nach npm run buildnpm run help:shots # Bilder der Anleitung neu aufnehmen (resources/help/), nach Änderungen an der Oberfläche```@@ -71,7 +72,7 @@ SOMA_TEST_EXE="$LOCALAPPDATA/soma-dev/release/win-unpacked/SOMA.exe" node test/s|---|---|| `src/main/` | Hauptprozess: `projects.ts` (offenes Projekt, Speichern, Öffnen, Verlauf, Wiederherstellen), `git.ts` (mitgeliefertes Git über dugite), `zip.ts` (Modelldatei .soma oder ZIP schreiben und sicher entpacken), `workspace.ts` (UUID-Arbeitsordner, Projektzustand doppelt, Projekt-Check nur melden), `build.ts` (Build als Einmal-Prozess mit Entprellung, Warteschlange, Zeitlimit, ein vorgewärmter Python-Prozess für alle Aufträge der App, gilt der letzte Build noch), `previews.ts` (Build als Vorschau eines Commits ablegen), `measure.ts` (langlebiger Python-Messdienst, `soma serve`), `skills.ts` (Bibliothek aus mitgelieferten und eigenen Skills, Stufen der Skills: Kopie nach `.soma/skills/`, bei Bedarf mit Hinweis, zwei Listen in `AGENTS.md`, Sicherung abweichender Kopien, Prüfung eines Skill-Texts), `help.ts` (Text und Bilder der Anleitung, Bilder nach `.soma/help/` im Projekt, E83), `skilllibrary.ts` (eigene Skills in den App-Daten für die Einstellungen: anlegen, speichern, zurücksetzen, löschen, importieren, mit Sicherung, E78), `settings.ts` (Einstellungen der App in `settings.json`, Kaputtes gemeldet und vor dem Ersetzen gesichert, E81), `storage.ts` (Größe der App-Daten je Bereich, Vorschau-Cache leeren, E81), `about.ts` (Versionen, Komponenten mit Lizenz, Python-Pakete aus den Metadaten, Text für Fehlermeldungen, E81), `params.ts` (Werte des Nutzers in `parameters.json` lesen, prüfen und schreiben, E74), `dialogs.ts` (native Dialoge, im Test beantwortbar), `watcher.ts`, `terminals.ts` (node-pty, Projektumgebung, `soma` und `git` im PATH, `PIP_PYTHON`), `packages.ts` (Projektumgebung `.soma/env` anlegen lassen, fehlende Pakete aus `requirements.txt` installieren, E67), `files.ts` (Pfadschutz, Dateien nach `inputs/`, Markierungen nach `.soma/feedback/`, Schreiben aus dem Editor mit Konfliktprüfung und Sicherung), `dxf.ts` (DXF für die Ansicht über `soma dxfview`, nur bei geänderter Datei, E80), `agents.ts`, dazu für E58 `bridge.ts` (Verbindung für `soma render`: HTTP auf 127.0.0.1 mit Schlüssel), `render.ts` (unsichtbares Render-Fenster, Aufträge nacheinander), `animations.ts` (Liste der Animationen und Ergebnisse, Bauen im Hintergrund) || `src/preload/` | Schmale, feste Schnittstelle zum Renderer (kein Node-Zugriff dort), `render-preload.ts` für das Render-Fenster |-| `src/renderer/` | Oberfläche: `main.ts` (Verdrahtung: Kopfzeile mit Spalten-Schaltern, Seitenleiste und Code-Spalte, Reiter Analysis und Animation mit Punkt für Neues, Werkzeuge neben dem Strukturbaum, Menüs, Auswahl, Export, Übergabe an den Agenten auch per Ziehen ins Terminal, Startseite), `viewer.ts` (three.js, Klick auf Code, Ansichten, Drehpunkt, Mausbelegungen und orthografische Kamera (E81), Schnittebene mit gefüllter Schnittfläche und Kontur, verschobene Bauteile der Explosion mit Wegen, Strahltest der Demontage-Analyse mit BVH aus `three-mesh-bvh`, Vorschaubild, Bild für die Markierung), `viewcube.ts` (Ansichtswürfel in 3D), `sectiontool.ts` (Schnitt: Karte, Ebene, Text für den Agenten), `explodetool.ts` (Explosion: Demontage-Analyse mit Baugruppen und schrägen Richtungen, Elternteile, Lage, Abspielen Schritt für Schritt, Karte, Texte für den Agenten), `busy.ts` (Ladeanzeige über dem Viewer mit Fortschritt und Abbrechen, für die Analyse der Explosion), `skills.ts` (Skills in der Seitenleiste: Zeilen mit Stufen-Schalter, Karte daneben mit Einstellungen), `help.ts` (Hilfe über der App: Abschnitte der Anleitung, E83), `settings.ts` (Einstellungen über der App mit Reitern, Reiter „Skills“ mit Liste, Markdown-Editor, Vorschau und Prüfung beim Tippen, E78), `settingspages.ts` (Reiter Viewer, Shortcuts, Storage und About, E81), `params.ts` (Parameter in der Seitenleiste: Felder nach Art, Gruppen, Zurücksetzen auf den Wert aus dem Code, E74), `markup.ts` (Zeichenfläche der Markierung, Formen als bearbeitbare Objekte), `measuretool.ts` (Messen: Ablauf, Karte, Text für den Agenten), `tree.ts` (Strukturbaum oben links im Viewer, E82: ohne Hintergrund, Baumstriche, Gruppen, Auge und Transparenz vor dem Namen, Referenzen als Gruppe am Ende, Suche, F3, Mehrfachauswahl, Ziehen über die Augen), `shortcuts.ts` (Liste aller Tasten für den Reiter Shortcuts der Einstellungen), `code.ts` (Code-Spalte mit Editor: CodeMirror 6, Speichern auf Wunsch, Abgleich mit Änderungen des Agenten, Konflikte, Umschalter für Markdown), `dxfview.ts` (DXF-Ansicht im Code-Panel: Pfade auf einer Canvas, Zoom, Layer, Mark up view, E80), `markdown.ts` (Markdown als Dokument: Tokens von `marked` direkt als DOM, ohne `innerHTML`), `filetree.ts` (Dateibaum in der Seitenleiste, offene Datei hervorgehoben), `versions.ts` (Verlaufsleiste), `terminals.ts` (xterm.js, Tabs, Einklappen, Einfügen), `ui.ts` (Menüs, Meldungen, Helfer), `icons.ts` (Symbole), `style.css` (Farben mit fester Bedeutung, siehe Kopf der Datei) |+| `src/renderer/` | Oberfläche: `main.ts` (Verdrahtung: Kopfzeile mit Spalten-Schaltern, Seitenleiste und Code-Spalte, Reiter Analysis und Animation mit Punkt für Neues, Werkzeuge neben dem Strukturbaum, Menüs, Auswahl, Export, Übergabe an den Agenten auch per Ziehen ins Terminal, Startseite), `viewer.ts` (three.js, Klick auf Code, Ansichten, Drehpunkt, Mausbelegungen und orthografische Kamera (E81), Schnittebene mit gefüllter Schnittfläche und Kontur, verschobene Bauteile der Explosion mit Wegen, Strahltest der Demontage-Analyse mit BVH aus `three-mesh-bvh`, Vorschaubild, Bild für die Markierung), `viewcube.ts` (Ansichtswürfel in 3D), `sectiontool.ts` (Schnitt: Karte, Ebene, Text für den Agenten), `explodetool.ts` (Explosion: Demontage-Analyse mit Baugruppen und schrägen Richtungen, Elternteile, Lage, Abspielen Schritt für Schritt, Karte, Texte für den Agenten), `busy.ts` (Ladeanzeige über dem Viewer mit Fortschritt und Abbrechen, für die Analyse der Explosion), `skills.ts` (Skills in der Seitenleiste: Zeilen mit Stufen-Schalter, Karte daneben mit Einstellungen), `help.ts` (Hilfe über der App: Abschnitte der Anleitung, E83), `tutorial.ts` (geführte Tour, E94: Karte mit Schritt, Titel und Text, oranger Rahmen um das Element, Abdunklung aus vier Flächen, Klicks gehen durch, ohne Element Karte in der Mitte; die zehn Schritte am Modell „Tutorial“), `settings.ts` (Einstellungen über der App mit Reitern, Reiter „Skills“ mit Liste, Markdown-Editor, Vorschau und Prüfung beim Tippen, E78), `settingspages.ts` (Reiter Viewer, Shortcuts, Storage und About, E81), `params.ts` (Parameter in der Seitenleiste: Felder nach Art, Gruppen, Zurücksetzen auf den Wert aus dem Code, E74), `markup.ts` (Zeichenfläche der Markierung, Formen als bearbeitbare Objekte), `measuretool.ts` (Messen: Ablauf, Karte, Text für den Agenten), `tree.ts` (Strukturbaum oben links im Viewer, E82: ohne Hintergrund, Baumstriche, Gruppen, Auge und Transparenz vor dem Namen, Referenzen als Gruppe am Ende, Suche, F3, Mehrfachauswahl, Ziehen über die Augen), `shortcuts.ts` (Liste aller Tasten für den Reiter Shortcuts der Einstellungen), `code.ts` (Code-Spalte mit Editor: CodeMirror 6, Speichern auf Wunsch, Abgleich mit Änderungen des Agenten, Konflikte, Umschalter für Markdown), `dxfview.ts` (DXF-Ansicht im Code-Panel: Pfade auf einer Canvas, Zoom, Layer, Mark up view, E80), `markdown.ts` (Markdown als Dokument: Tokens von `marked` direkt als DOM, ohne `innerHTML`), `filetree.ts` (Dateibaum in der Seitenleiste, offene Datei hervorgehoben), `versions.ts` (Verlaufsleiste), `terminals.ts` (xterm.js, Tabs, Einklappen, Einfügen), `ui.ts` (Menüs, Meldungen, Helfer), `icons.ts` (Symbole), `style.css` (Farben mit fester Bedeutung, siehe Kopf der Datei) || `src/renderer/` (E58) | `animdata.ts` (Animation aus der glTF-Datei auswerten), `animtool.ts` (Abspielleiste unten im Bild), `animpanel.ts` (Reiter Animation: Liste mit Videos, Schritte, E82), `overlay.ts` (Untertitel, Beschriftungen, Legende auf einer 2D-Fläche, im Viewer wie im Video), `resultview.ts` und `resulttool.ts` (Ergebnisse farbig, Legende, Leiste und Beschriftungen im Bild), `analysispanel.ts` (Reiter Analysis: Liste und Bericht, E82), `videoview.ts` (Video-Player mit Standbild markieren), `render.html` und `render.ts` (unsichtbares Render-Fenster: Bild, Übersicht, MP4 mit WebCodecs und mediabunny) || `src/shared/` | `help.ts` Anleitung in Abschnitte zerlegen (E83), `types.ts` Typen des IPC-Vertrags, `editable.ts` welche Dateien der Editor nur zeigt (gilt in Renderer und Hauptprozess), `skillname.ts` Kennung eines eigenen Skills aus seinem Namen || `resources/template/` | Vorlage für neue Projekte: `model.py`, `AGENTS.md`, `CLAUDE.md`, `NOTES.md`, `.gitignore` |@@ -79,7 +80,7 @@ SOMA_TEST_EXE="$LOCALAPPDATA/soma-dev/release/win-unpacked/SOMA.exe" node test/s| `resources/help/` | Bilder der Anleitung (E83) mit nummerierten Markierungen, erzeugt mit `npm run help:shots` (`test/helpshots.mjs`, Ausschnitte und Nummern in `test/helpshots-spec.mjs`). Der Text ist der Skill `resources/skills/soma-app.md`, die Liste unter jedem Bild nennt dieselben Bezeichnungen wie die Markierungen (`npm run test:unit` prüft das) || `resources/icon.*` | App-Icon (E44) für Fenster und Taskleiste: `icon.svg` als Vorlage, `icon.ico` (16 bis 256 px) und `icon.png`. Neu erzeugen mit `python scripts/make-icon.py` (braucht Edge und Pillow, kleine Größen bekommen einen dickeren Strich) || `../python/soma/` | Hilfsbibliothek und Kommandozeile (`soma build`, `soma export`, `soma glb` für Vorschauen, `soma serve` Messdienst, `soma warm` vorgewärmter Prozess der App, `soma env` und `env.py` Projektumgebung und `requirements.txt` (E67), `measure.py` exakte Werte mit OCC, `fasteners.py` Normteile mit Tabellen aus bd_warehouse in `data/fasteners/`, `anim.py` und `animrun.py` Animationen mit `soma anim`, `analysis.py` Auswertungen mit `soma analyze`, `fem.py` Festigkeit mit `soma analyze fem` (gmsh, Kontakt, Schrauben mit Vorspannung, eigener Solver mit pyamg als Rückfall), `ccx.py` CalculiX als Rechenwerk (E84), `render.py` Auftrag an die App für `soma render`, `drawing.py` und `drawrun.py` technische Zeichnungen mit `soma drawing` (E76: HLR aus OCP, DXF mit ezdxf, PDF und PNG über matplotlib, Prüfung), `dxfview.py` DXF für die Ansicht der App mit `soma dxfview` (E80, Zeichenmodul von ezdxf), `gltf.py` GLB-Schreiber, `progress.py` Fortschritt langer Befehle) |-| `test/` | `smoke.mjs`, `versions.mjs`, `editor.mjs`, `measure.mjs`, `groups.mjs`, `section.mjs`, `explode.mjs`, `skills.mjs`, `params.mjs`, `fasteners.mjs`, `drawing.mjs`, `dxf.mjs`, `animation.mjs` (Ende-zu-Ende), `unit.mjs` (ohne Electron), `harness.mjs` (App starten und steuern), `cdp.mjs` (kleiner DevTools-Client, puppeteer scheitert an Electron 44) |+| `test/` | `smoke.mjs`, `versions.mjs`, `editor.mjs`, `measure.mjs`, `groups.mjs`, `section.mjs`, `explode.mjs`, `skills.mjs`, `params.mjs`, `tutorial.mjs`, `fasteners.mjs`, `drawing.mjs`, `dxf.mjs`, `animation.mjs` (Ende-zu-Ende), `unit.mjs` (ohne Electron), `harness.mjs` (App starten und steuern), `cdp.mjs` (kleiner DevTools-Client, puppeteer scheitert an Electron 44) |## Noch nicht enthaltendiff --git a/app/package.json b/app/package.jsonindex fddbb02..cb890ab 100644--- a/app/package.json+++ b/app/package.json@@ -26,6 +26,7 @@"test:animation": "npm run build && node test/animation.mjs","test:packages": "npm run build && node test/packages.mjs","test:settings": "npm run build && node test/settings.mjs",+ "test:tutorial": "npm run build && node test/tutorial.mjs","test:unit": "node test/unit.mjs","help:shots": "npm run build && node test/helpshots.mjs","dist": "npm run build && electron-builder --config electron-builder.config.cjs --publish never",diff --git a/app/resources/help/start.png b/app/resources/help/start.pngindex 04b2028..96e8539 100644Binary files a/app/resources/help/start.png and b/app/resources/help/start.png differdiff --git a/app/resources/skills/soma-app.md b/app/resources/skills/soma-app.mdindex 4686e3c..9281f1a 100644--- a/app/resources/skills/soma-app.md+++ b/app/resources/skills/soma-app.md@@ -6,7 +6,7 @@ order: 9category: Way of workingdefault: on-demandwhen: the user asks how to do something in the SOMA app, cannot find a button or panel, or asks what a part of the window does-topics: The window; Start page; The agent; Viewer; Tools; Mark up; Sidebar; Files and code; Saving and history; Export; Settings; When something goes wrong+topics: The window; Start page; Tutorial; The agent; Viewer; Tools; Mark up; Sidebar; Files and code; Saving and history; Export; Settings; When something goes wrong---# Using SOMA@@ -44,13 +44,20 @@ The logo at the top left opens the start page.-1. **New model**: starts from a small example (a box with a lid) and opens a terminal in the model folder (Ctrl N).-2. **Open**: opens a .soma or ZIP file (Ctrl O).-3. **Recent**: models you worked on. The bin on a card removes the model from this computer, a saved .soma file stays.-4. **Agents on this computer**: the agents SOMA found. You install them yourself, SOMA does not bring one.-5. **Help**: this guide (F1).-6. **Settings**: viewer, shortcuts, skills, storage and version.-7. **Back to the model**: returns to the open model.+1. **Tutorial**: a short guided tour of the app with an example model. No agent needed. "Got it" hides the card.+2. **New model**: starts from a small example (a box with a lid) and opens a terminal in the model folder (Ctrl N).+3. **Open**: opens a .soma or ZIP file (Ctrl O).+4. **Recent**: models you worked on. The bin on a card removes the model from this computer, a saved .soma file stays.+5. **Agents on this computer**: the agents SOMA found. You install them yourself, SOMA does not bring one.+6. **Help**: this guide (F1).+7. **Settings**: viewer, shortcuts, skills, storage and version.+8. **Back to the model**: returns to the open model.++**Start tutorial** opens a new example model called "Tutorial" and walks you through the window in ten steps: starting+the agent, the code, clicking a part, measuring, marking up, parameters, history, saving and export, and help. An orange+frame shows where to look, and you can try everything right away. Back, Skip and Next move through the steps, Esc ends+the tour. To see it again, click **Start tutorial** at the top of Help. If you leave the example model unchanged, it+disappears like any new model you did not change.## The agentdiff --git a/app/src/main/main.ts b/app/src/main/main.tsindex d4110bd..4d4a055 100644--- a/app/src/main/main.ts+++ b/app/src/main/main.ts@@ -45,7 +45,8 @@ function registerIpc(ctl: ProjectController): void {const dir = () => ctl.need().dir;ipcMain.handle('project:current', () => ctl.info());- ipcMain.handle('project:create', () => ctl.create());+ // Nur der feste Name fürs Tutorial (E94), kein freier Text aus dem Renderer+ ipcMain.handle('project:create', (_e, kind?: unknown) => ctl.create(kind === 'tutorial' ? 'Tutorial' : undefined));ipcMain.handle('project:list', async () => (await import('./workspace')).listProjects());ipcMain.handle('project:open', (_e, id: string) => ctl.open(id));ipcMain.handle('project:saveState', () => ctl.saveState());diff --git a/app/src/main/projects.ts b/app/src/main/projects.tsindex 47d05f5..1a0efaa 100644--- a/app/src/main/projects.ts+++ b/app/src/main/projects.ts@@ -146,8 +146,8 @@ export class ProjectController {return info;}- async create(): Promise<ProjectInfo> {- const { id } = await createProject();+ async create(name?: string): Promise<ProjectInfo> {+ const { id } = await createProject(name);return this.open(id);}diff --git a/app/src/preload/preload.ts b/app/src/preload/preload.tsindex 6a41ad4..90a4101 100644--- a/app/src/preload/preload.ts+++ b/app/src/preload/preload.ts@@ -7,7 +7,7 @@ const api: SomaApi = {startsHome: process.env.SOMA_TEST !== '1' || process.env.SOMA_TEST_START === 'home',project: {current: () => ipcRenderer.invoke('project:current'),- create: () => ipcRenderer.invoke('project:create'),+ create: (kind) => ipcRenderer.invoke('project:create', kind),list: () => ipcRenderer.invoke('project:list'),open: (id) => ipcRenderer.invoke('project:open', id),onChanged: (cb) => { ipcRenderer.on('project:changed', (_e, p) => cb(p)); },diff --git a/app/src/renderer/index.html b/app/src/renderer/index.htmlindex a708774..0817b5d 100644--- a/app/src/renderer/index.html+++ b/app/src/renderer/index.html@@ -497,6 +497,15 @@<div><h1>Models</h1><p class="c2 lead">A model is a .soma file with code, result and history. You can move it and share it freely.</p>+ <!-- Tutorial (E94): bis „Got it“ (gespeichert in settings.json). Die Tour führt durch ein Beispielmodell, ohne Agent -->+ <section id="start-tour" class="tour-intro" aria-label="Tutorial" hidden>+ <span class="ico"><i data-icon="route" data-size="22" data-stroke="1.8"></i></span>+ <div class="ti-text"><b>New to SOMA?</b><span class="c2">Learn the basics in a few minutes with an example model. No agent needed.</span></div>+ <div class="ti-acts">+ <button id="btn-tour-start" class="btn primary">Start tutorial</button>+ <button id="btn-tour-dismiss" class="btn" title="Hide this card. Help can start the tutorial at any time.">Got it</button>+ </div>+ </section><div class="bigcards"><button id="start-new" class="bigcard"><span class="ico acc"><i data-icon="plus" data-size="22" data-stroke="2.2"></i></span><b>New model</b><span class="c2">Template with an example part, plus a terminal in the model folder</span><span class="c3 small">Ctrl N</span></button><button id="start-open" class="bigcard"><span class="ico"><i data-icon="folder" data-size="22"></i></span><b>Open …</b><span class="c2">.soma or ZIP file from this or another computer</span><span class="c3 small">Ctrl O</span></button>@@ -559,6 +568,7 @@<div id="help" class="st-scrim" hidden><div class="st-dlg" role="dialog" aria-modal="true" aria-labelledby="help-title"><header class="st-hd"><i data-icon="help" data-size="18" data-stroke="1.7"></i><b id="help-title">Help</b><span class="c3 small">How SOMA works. The agent knows this guide too: just ask it.</span><span class="grow"></span>+ <button id="btn-help-tour" class="btn sm acc" title="A short guided tour with an example model"><i data-icon="route" data-size="14" data-stroke="1.9"></i>Start tutorial</button><button id="btn-help-close" class="ibtn" aria-label="Close help" title="Close (Escape)"><i data-icon="x" data-size="16" data-stroke="2"></i></button></header><div class="st-body"><nav id="help-nav" class="st-nav help-nav" aria-label="Help"></nav>diff --git a/app/src/renderer/main.ts b/app/src/renderer/main.tsindex 866cef7..0d5fdd6 100644--- a/app/src/renderer/main.ts+++ b/app/src/renderer/main.ts@@ -20,6 +20,7 @@ import { AboutPage, ShortcutsPage, StoragePage, ViewerPage } from './settingspagimport { SkillsPanel } from './skills';import { ParamsPanel } from './params';import { StructureTree } from './tree';+import { Tour, tourSteps, type TourContext } from './tutorial';import { ResultTool } from './resulttool';import { ResultLayer } from './resultview';import { TerminalTabs } from './terminals';@@ -1013,6 +1014,8 @@ const versions = new VersionsBar({async function onProject(p: ProjectInfo): Promise<void> {project = p;+ // Ein anderes Modell geöffnet (Menü, Startseite): Die Tour gehört zum Tutorial-Modell und endet+ if (tour.active && p.id !== tourProject) tour.stop(false, false);loadSeq++; // laufende Ladevorgänge des vorherigen Projekts verwerfenmap = null;lastOkAt = null;@@ -1487,6 +1490,7 @@ async function showStart(on: boolean): Promise<void> {menus.close();$('btn-start-close').hidden = !project;$('start-note').hidden = store.get('soma.noteSeen') === '1';+ renderTourCard();let list: ProjectListEntry[] = [];try { list = await api.project.list(); } catch { /* ohne Liste */ }list.sort((a, b) => b.modified - a.modified);@@ -1557,7 +1561,80 @@ api.project.onSaveState((st) => renderSaveState(st));// Das Projekt kommt ausschließlich über das Ereignis (Startseite, Menü, im Testmodus öffnet es der Hauptprozess beim Start). Ein zweiter Weg würde alles doppelt aufbauen.// Einstellungen der App (E81): Ein Modell, das schon offen ist, bekommt auch die Darstellung beim Öffnen-void api.settings.get().then((st) => { appSettings = st; applySettings(); applyDisplayDefaults(); }).catch(() => { /* es gelten die Vorgaben */ });+void api.settings.get().then((st) => { appSettings = st; applySettings(); applyDisplayDefaults(); renderTourCard(); }).catch(() => { /* es gelten die Vorgaben */ });++// ---- Tutorial (E94) ---------------------------------------------------------------------------------------------+// Erst hier angelegt: Seine Escape-Taste kommt nach Menüs, Messen und Markierung, die Escape zuerst für sich nutzen++const tourCtx: TourContext = {+ showPanel: (p) => showPanel(p),+ showCode: (on) => showCode(on),+ openCode: (f) => void openCode(f),+ expandAgent: () => setAgentCollapsed(false),+ // Die Liste nennt alle bekannten Agenten mit „found“. Leer heißt: Suche läuft noch+ agentsFound: () => (agents.length ? agents.filter((a) => a.found).map((a) => a.label) : null),+ selected: () => !!selection,+ measuring: () => measureTool.isActive,+ stopMeasure: () => { if (measureTool.isActive) measureTool.setActive(false); },+ marking: () => markup.active,+ closeEmptyMarkup: () => { if (markup.active && !markup.drawn) markup.close(); },+ // Läuft in jedem Frame: nur nachsehen, ob eine Zeile als geändert markiert ist (state() misst den ganzen Text)+ paramsChanged: () => !!document.querySelector('#params-list .prm.chg'),+};+/** Modell, zu dem die laufende Tour gehört. */+let tourProject: string | null = null;+const tour = new Tour({+ covered: () => !$('start').hidden || help.isOpen || settings.isOpen,+ // Durchlaufen blendet die Karte der Startseite aus (wie „Got it“), Überspringen nicht: Wer abbricht, findet sie dort wieder+ ended: (finished) => {+ if (finished) void hideTourCard();+ toast(finished ? 'That’s the basics. Help (F1) has the whole guide and can start the tutorial again.' : 'Tutorial ended. Help (F1) can start it again.', 'info');+ },+});++function renderTourCard(): void {+ $('start-tour').hidden = !appSettings.settings.start.tutorialCard;+}++/** Karte „New to SOMA?“ dauerhaft ausblenden (settings.json). Klappt das Schreiben nicht, bleibt sie für diese Sitzung weg. */+async function hideTourCard(): Promise<void> {+ $('start-tour').hidden = true;+ if (!appSettings.settings.start.tutorialCard) return;+ try {+ const r = await changeSettings({ start: { tutorialCard: false } });+ if (!r.ok) toast(r.error ?? 'The setting could not be saved.', 'error');+ } catch (e) { toast(`The setting could not be saved: ${e instanceof Error ? e.message : String(e)}`, 'error'); }+ $('start-tour').hidden = true;+}++/**+ * Tutorial starten: Es legt wie „New model“ ein neues Modell aus der Vorlage an, nur mit dem Namen „Tutorial“, und führt+ * daran durch die Oberfläche. Ein offenes Modell bleibt, wie es ist (unter Recent), nach einer Rückfrage, weil seine+ * Terminals dabei schließen. Bleibt das Tutorial-Modell unverändert, verschwindet es beim Wechsel wie jedes neue (E69).+ */+async function startTutorial(): Promise<void> {+ if (project) {+ const c = await api.dialog.choose({+ title: 'Tutorial', message: 'Start the tutorial with a new example model?',+ detail: `Your model “${project.name}” stays on the start page under Recent. Its terminals close.`, buttons: ['Start tutorial', 'Cancel'],+ });+ if (c !== 0) return;+ }+ if (!(await leaveEditor('Start tutorial'))) return;+ help.close();+ tour.stop(false, false);+ void showStart(false);+ let info: ProjectInfo;+ try { info = await api.project.create('tutorial'); } catch (e) {+ toast(`The example model could not be created: ${e instanceof Error ? e.message : String(e)}`, 'error');+ return;+ }+ tourProject = info.id;+ tour.start(tourSteps(tourCtx));+}+$('btn-tour-start').addEventListener('click', () => void startTutorial());+$('btn-tour-dismiss').addEventListener('click', () => void hideTourCard());+$('btn-help-tour').addEventListener('click', () => void startTutorial());if (store.get('soma.agentCollapsed') === '1') setAgentCollapsed(true);// Seitenleiste wie beim letzten Mal, beim ersten Start zu: Die Bauteile stehen im Baum im Viewer (E82)@@ -1649,6 +1726,8 @@ if (api.testMode) {/** „Everything as ZIP“ im Export-Menü (E79). */exportZip: () => doExportZip(),showStart: (on: boolean) => showStart(on),+ tour: () => tour.state(),+ tourGo: (n: number) => tour.goTo(n),setAgentCollapsed,fileRows: () => [...document.querySelectorAll('#tab-files .frow .fn')].map((x) => x.textContent),codeText: () => code.text(),diff --git a/app/src/renderer/style.css b/app/src/renderer/style.cssindex 5841614..1f91995 100644--- a/app/src/renderer/style.css+++ b/app/src/renderer/style.css@@ -1108,3 +1108,28 @@ code { font-family:var(--mono); font-size:.95em; }.fatal h1 { font-size:18px; font-weight:600; color:var(--err); margin:0 0 12px; }.fatal p { color:var(--tx2); margin:0 0 16px; }.fatal pre { font-family:var(--mono); font-size:12px; color:var(--tx3); white-space:pre-wrap; background:var(--s2); border:1px solid var(--line); border-radius:6px; padding:10px 12px; margin:0; }++/* ---- Tutorial (E94, tutorial.ts) ------------------------------------------------------------------------------------+ Startseite: Karte „New to SOMA?“ über New model und Open. In der Tour ein oranger Rahmen um das Element des Schritts,+ der Rest leicht abgedunkelt (vier Flächen um das Element). Beides lässt Klicks durch, nur die Karte fängt sie. Unter den Menüs+ (z-index 40), damit ein geöffnetes Menü hell bleibt, über Startseite und Viewer. */+.tour-intro { display:flex; align-items:center; gap:16px; margin:0 0 14px; padding:16px 18px; border:1px solid var(--acc-line); border-radius:12px; background:linear-gradient(90deg, var(--acc-tint), var(--s2) 60%); }+.tour-intro .ico { width:40px; height:40px; flex-shrink:0; border-radius:10px; display:flex; align-items:center; justify-content:center; background:var(--s3); color:var(--acc); }+.tour-intro .ti-text { flex:1; min-width:0; display:flex; flex-direction:column; gap:2px; }+.tour-intro .ti-text b { font-size:15px; }+.tour-intro .ti-acts { display:flex; gap:8px; flex-shrink:0; }+.tour { position:fixed; inset:0; z-index:38; pointer-events:none; }+.tour.covered { display:none; }+.tour.free { background:rgba(8,9,11,.35); }+.tour-dim { position:fixed; background:rgba(8,9,11,.4); }+.tour-spot { position:fixed; border:2px solid var(--acc); border-radius:6px; box-shadow:0 0 0 5px rgba(242,154,56,.18); }+.tour-card { position:fixed; width:330px; pointer-events:auto; display:flex; flex-direction:column; gap:6px; padding:14px 16px 12px; background:var(--s2); border:1px solid var(--acc-line); border-radius:12px; box-shadow:0 18px 50px rgba(0,0,0,.55); }+.tour-hd { display:flex; align-items:center; gap:8px; min-height:18px; }+.tour-n { font-size:11px; letter-spacing:.06em; text-transform:uppercase; color:var(--acc-tx); font-weight:500; }+.tour-ok { display:flex; align-items:center; gap:4px; margin-left:auto; font-size:12px; color:var(--ok); }+.tour-t { font-size:15px; font-weight:600; }+.tour-x { margin:0 0 6px; color:var(--tx2); font-size:12.5px; line-height:1.5; }+.tour-acts { display:flex; align-items:center; gap:6px; }+.tour-acts .btn.ghost { padding:0 4px; color:var(--tx3); }+.tour-acts .btn.ghost:hover { color:var(--tx); background:none; }+.tour-acts .btn:disabled { visibility:hidden; }diff --git a/app/src/renderer/tutorial.ts b/app/src/renderer/tutorial.tsnew file mode 100644index 0000000..155c288--- /dev/null+++ b/app/src/renderer/tutorial.ts@@ -0,0 +1,304 @@+import { icon } from './icons';+import { el } from './ui';++/** Ein Schritt der Tour. Texte sind fest (englisch, E73), nichts aus dem Projekt. */+export interface TourStep {+ title: string;+ /** Text der Karte, als Funktion, wenn er vom Zustand abhängt (etwa gefundene Agenten). */+ text: string | (() => string);+ /** Hervorgehobenes Element (mehrere: gemeinsamer Rahmen). Fehlt es oder ist unsichtbar, steht die Karte in der Mitte. */+ target?: () => (HTMLElement | null)[];+ /** Beim Betreten: nötiges Panel oder Werkzeug öffnen. */+ enter?: () => void | Promise<void>;+ /** Beim Verlassen: aufräumen, was den nächsten Schritt stören würde. */+ leave?: () => void;+ /** Hat der Nutzer getan, wozu der Schritt einlädt? Zeigt nur einen Haken, „Next“ geht immer. */+ done?: () => boolean;+}++interface Deps {+ /** Liegt gerade etwas über dem Modellfenster (Startseite, Hilfe, Einstellungen)? Dann wartet die Tour unsichtbar. */+ covered(): boolean;+ /** Tour zu Ende, `finished`: bis zum letzten Schritt durchlaufen (sonst übersprungen). */+ ended(finished: boolean): void;+}++const GAP = 14;+const MARGIN = 12;++/**+ * Geführte Tour (E94): eine Karte mit „Step n of m“, Titel, Text und Back, Skip, Next, dazu ein oranger Rahmen um das+ * Element des Schritts, der Rest leicht abgedunkelt. Rahmen und Abdunklung lassen Klicks durch (pointer-events: none), der+ * Nutzer probiert also direkt an der echten Oberfläche aus. Die Lage folgt dem Element in jedem Frame: Panels gehen auf,+ * das Fenster ändert seine Größe. Fehlt ein Element, steht die Karte ohne Rahmen in der Mitte, statt zu scheitern.+ */+export class Tour {+ private layer: HTMLElement;+ private spot: HTMLElement;+ /** Abdunklung um das Element: vier Flächen oben, unten, links, rechts (ein riesiger Schatten wird bei großen Elementen nicht gezeichnet). */+ private dims: HTMLElement[];+ private card: HTMLElement;+ private count: HTMLElement;+ private check: HTMLElement;+ private title: HTMLElement;+ private text: HTMLElement;+ private back: HTMLButtonElement;+ private next: HTMLButtonElement;+ private i = -1;+ private raf = 0;+ private timer: ReturnType<typeof setInterval> | undefined;+ private last = '';+ private steps: TourStep[] = [];++ constructor(private deps: Deps) {+ this.spot = el('div', { className: 'tour-spot' });+ this.dims = [0, 1, 2, 3].map(() => el('div', { className: 'tour-dim' }));+ this.count = el('span', { className: 'tour-n' });+ this.check = el('span', { className: 'tour-ok', title: 'Done' }, icon('check', 14, 2.4), 'Done');+ this.title = el('b', { className: 'tour-t' });+ this.text = el('p', { className: 'tour-x' });+ this.back = el('button', { className: 'btn sm', id: 'btn-tour-back', textContent: 'Back' });+ this.next = el('button', { className: 'btn sm primary', id: 'btn-tour-next', textContent: 'Next' });+ const skip = el('button', { className: 'btn sm ghost', id: 'btn-tour-skip', textContent: 'Skip', title: 'End the tutorial (Escape). Help can start it again.' });+ this.card = el('div', { className: 'tour-card', id: 'tour-card' },+ el('div', { className: 'tour-hd' }, this.count, this.check),+ this.title, this.text,+ el('div', { className: 'tour-acts' }, skip, el('span', { className: 'grow' }), this.back, this.next));+ this.card.setAttribute('role', 'dialog');+ this.card.setAttribute('aria-label', 'Tutorial');+ this.card.setAttribute('aria-live', 'polite');+ this.layer = el('div', { className: 'tour', id: 'tour', hidden: true }, ...this.dims, this.spot, this.card);+ document.body.append(this.layer);+ this.back.addEventListener('click', () => void this.go(this.i - 1));+ this.next.addEventListener('click', () => { if (this.i >= this.steps.length - 1) this.stop(true); else void this.go(this.i + 1); });+ skip.addEventListener('click', () => this.stop(false));+ // Escape beendet die Tour, aber erst nach Menüs und Werkzeugen (die rufen preventDefault) und nie im Terminal oder+ // Editor: Dort gehört Escape dem Agenten (Claude Code unterbricht damit) und dem Editor+ window.addEventListener('keydown', (e) => {+ if (!this.active || e.key !== 'Escape' || e.defaultPrevented || this.deps.covered()) return;+ if ((e.target as HTMLElement | null)?.closest?.('#terminals, #code-view, input, textarea, select')) return;+ e.preventDefault();+ this.stop(false);+ });+ }++ get active(): boolean { return this.i >= 0; }++ start(steps: TourStep[]): void {+ if (this.active) this.stop(false, false);+ this.steps = steps;+ this.layer.hidden = false;+ void this.go(0);+ const tick = () => { this.place(); this.raf = requestAnimationFrame(tick); };+ cancelAnimationFrame(this.raf);+ this.raf = requestAnimationFrame(tick);+ // Ein verdecktes oder unsichtbares Fenster bekommt keine Frames: dann wenigstens alle 250 ms nachziehen+ clearInterval(this.timer);+ this.timer = setInterval(() => this.place(), 250);+ }++ /** Beenden, `finished`: mit „Done“ im letzten Schritt. `notify`: dem Aufrufer Bescheid geben. */+ stop(finished: boolean, notify = true): void {+ if (!this.active) return;+ try { this.steps[this.i]?.leave?.(); } catch { /* Aufräumen ist verzichtbar */ }+ this.i = -1;+ cancelAnimationFrame(this.raf);+ clearInterval(this.timer);+ this.layer.hidden = true;+ this.last = '';+ if (notify) this.deps.ended(finished);+ }++ private async go(i: number): Promise<void> {+ if (i < 0 || i >= this.steps.length) return;+ if (this.i >= 0 && this.i !== i) { try { this.steps[this.i].leave?.(); } catch { /* weiter */ } }+ this.i = i;+ const s = this.steps[i];+ this.count.textContent = `Step ${i + 1} of ${this.steps.length}`;+ this.title.textContent = s.title;+ this.text.textContent = typeof s.text === 'function' ? s.text() : s.text;+ this.back.disabled = i === 0;+ this.next.textContent = i === this.steps.length - 1 ? 'Done' : 'Next';+ this.last = '';+ try { await s.enter?.(); } catch { /* Ohne Panel geht der Schritt trotzdem, die Karte steht dann in der Mitte */ }+ if (this.i !== i) return;+ // Der Text kann vom Zustand nach dem Betreten abhängen+ this.text.textContent = typeof s.text === 'function' ? s.text() : s.text;+ this.place();+ this.next.focus({ preventScroll: true });+ }++ /** Gemeinsamer Rahmen der sichtbaren Zielelemente, null ohne. */+ private targetRect(): DOMRect | null {+ const s = this.steps[this.i];+ let els: (HTMLElement | null)[] = [];+ try { els = s?.target?.() ?? []; } catch { els = []; }+ const rs = els.filter((e): e is HTMLElement => !!e && e.isConnected && e.getClientRects().length > 0)+ .map((e) => e.getBoundingClientRect()).filter((r) => r.width > 0 && r.height > 0);+ if (!rs.length) return null;+ const x = Math.min(...rs.map((r) => r.left)), y = Math.min(...rs.map((r) => r.top));+ const r = new DOMRect(x, y, Math.max(...rs.map((r) => r.right)) - x, Math.max(...rs.map((r) => r.bottom)) - y);+ // Nur was im Fenster liegt+ const l = Math.max(0, r.left), t = Math.max(0, r.top), rr = Math.min(innerWidth, r.right), b = Math.min(innerHeight, r.bottom);+ return rr - l > 0 && b - t > 0 ? new DOMRect(l, t, rr - l, b - t) : null;+ }++ /** Rahmen und Karte an das Element legen. Läuft in jedem Frame, schreibt nur bei einer Änderung. */+ private place(): void {+ if (!this.active) return;+ const covered = this.deps.covered();+ this.layer.classList.toggle('covered', covered);+ if (covered) return;+ const s = this.steps[this.i];+ let done = false;+ try { done = !!s.done?.(); } catch { done = false; }+ this.check.hidden = !done;+ if (typeof s.text === 'function') { const t = s.text(); if (this.text.textContent !== t) this.text.textContent = t; }+ const r = this.targetRect();+ const cw = this.card.offsetWidth, ch = this.card.offsetHeight;+ const key = `${r ? [r.left, r.top, r.width, r.height].map(Math.round).join(',') : '-'}|${innerWidth}x${innerHeight}|${cw}x${ch}`;+ if (key === this.last) return;+ this.last = key;+ this.spot.hidden = !r;+ for (const d of this.dims) d.hidden = !r;+ this.layer.classList.toggle('free', !r);+ if (!r) {+ this.card.style.left = `${Math.max(MARGIN, (innerWidth - cw) / 2)}px`;+ this.card.style.top = `${Math.max(MARGIN, (innerHeight - ch) / 2)}px`;+ return;+ }+ const pad = 4;+ const L = r.left - pad, T = r.top - pad, R = r.right + pad, B = r.bottom + pad;+ Object.assign(this.spot.style, { left: `${L}px`, top: `${T}px`, width: `${R - L}px`, height: `${B - T}px` });+ const box = (d: HTMLElement, x: number, y: number, w: number, h: number) => Object.assign(d.style, { left: `${x}px`, top: `${y}px`, width: `${Math.max(0, w)}px`, height: `${Math.max(0, h)}px` });+ box(this.dims[0], 0, 0, innerWidth, T);+ box(this.dims[1], 0, B, innerWidth, innerHeight - B);+ box(this.dims[2], 0, T, L, B - T);+ box(this.dims[3], R, T, innerWidth - R, B - T);+ // Neben das Element, wo Platz ist: rechts, links, darunter, darüber. Sonst innen unten rechts (große Bereiche wie der Viewer)+ const fits = (x: number, y: number) => x >= MARGIN && y >= MARGIN && x + cw <= innerWidth - MARGIN && y + ch <= innerHeight - MARGIN;+ const clampY = (y: number) => Math.max(MARGIN, Math.min(innerHeight - ch - MARGIN, y));+ const clampX = (x: number) => Math.max(MARGIN, Math.min(innerWidth - cw - MARGIN, x));+ const cy = clampY(r.top + r.height / 2 - ch / 2), cx = clampX(r.left + r.width / 2 - cw / 2);+ const tries: [number, number][] = [+ [r.right + GAP, cy], [r.left - GAP - cw, cy], [cx, r.bottom + GAP], [cx, r.top - GAP - ch],+ ];+ const at = tries.find(([x, y]) => fits(x, y)) ?? [clampX(r.right - cw - 24), clampY(r.bottom - ch - 24)];+ this.card.style.left = `${Math.round(at[0])}px`;+ this.card.style.top = `${Math.round(at[1])}px`;+ }++ /** Für die Tests: Schritt, Titel, ob das Ziel gefunden und hervorgehoben ist, Lage der Karte. */+ state() {+ const r = this.active ? this.targetRect() : null;+ const c = this.card.getBoundingClientRect();+ return {+ active: this.active, step: this.i + 1, count: this.steps.length, title: this.active ? this.title.textContent : '',+ text: this.active ? this.text.textContent : '', target: !!r, spot: this.active && !this.spot.hidden, done: this.active && !this.check.hidden,+ next: this.next.textContent, backDisabled: this.back.disabled,+ card: { x: c.left, y: c.top, w: c.width, h: c.height }, view: { w: innerWidth, h: innerHeight },+ titles: this.steps.map((s) => s.title),+ };+ }++ /** Für die Tests: direkt zu einem Schritt (1-basiert). */+ goTo(n: number): Promise<void> { return this.go(n - 1); }+}++/** Was die Schritte von der Oberfläche brauchen (main.ts). */+export interface TourContext {+ showPanel(p: 'params' | 'files' | null): void;+ showCode(on: boolean): void;+ openCode(file: string): void;+ expandAgent(): void;+ /** Gefundene Agenten (Namen), null solange die Suche läuft. */+ agentsFound(): string[] | null;+ selected(): boolean;+ measuring(): boolean;+ stopMeasure(): void;+ marking(): boolean;+ /** Markierung schließen, wenn noch nichts gezeichnet ist (eine Zeichnung wird nicht still verworfen). */+ closeEmptyMarkup(): void;+ paramsChanged(): boolean;+}++const byId = (id: string) => document.getElementById(id);++/**+ * Die Schritte der Tour am Beispielmodell (Kiste mit Deckel aus der Vorlage, Parameter Length, Width, Height, Wall). Texte+ * kurz und schlicht wie in der Anleitung (resources/skills/soma-app.md), Knöpfe mit dem Namen, den sie in der App tragen.+ */+export function tourSteps(c: TourContext): TourStep[] {+ return [+ {+ title: 'Welcome to SOMA',+ text: 'This is an example model: a box with a lid. In the middle is the 3D view, on the right the agent’s terminal, on the left the sidebar. Rotate the view with the left mouse button, zoom with the wheel.',+ target: () => [byId('center')],+ enter: () => { c.showCode(false); c.showPanel(null); },+ },+ {+ title: 'Start your agent',+ text: () => {+ const found = c.agentsFound();+ const intro = 'You describe what you want, an AI agent writes the model. SOMA does not bring its own agent.';+ // Nicht jeder Agent ist in der Liste: über „Empty terminal“ startet man jeden selbst mit seinem Befehl+ const own = 'Yours is not listed? Choose Empty terminal in the same menu and start it there with its command.';+ if (found === null) return `${intro} Click + to start one. ${own}`;+ if (!found.length) return `${intro} None was found on this computer: install one, for example Claude Code or OpenCode, then it appears in the + menu. Or choose Empty terminal there and start yours with its command. You can follow this tutorial without one.`;+ return `${intro} Click + and choose one: ${found.join(', ')}. ${own}`;+ },+ target: () => [byId('btn-term-add')],+ enter: () => c.expandAgent(),+ },+ {+ title: 'The model is code',+ text: 'The agent writes the model as CadQuery code in model.py. You can read it and edit it here too. Files shows everything in the model folder.',+ target: () => [byId('side'), byId('editor')],+ enter: () => { c.showPanel('files'); c.openCode('model.py'); },+ },+ {+ title: 'Click a part',+ text: 'Click the box or the lid. The card shows the part and its line in the code. Send to agent tells the agent exactly which part you mean.',+ target: () => [byId('viewer')],+ enter: () => { c.showCode(false); c.showPanel(null); },+ done: () => c.selected(),+ },+ {+ title: 'Measure',+ text: 'Click Measure, then a face or an edge for its size. A second click gives distance and angle. The values are exact.',+ target: () => [c.measuring() ? byId('measure-card') : byId('btn-measure')],+ leave: () => c.stopMeasure(),+ done: () => c.measuring(),+ },+ {+ title: 'Mark up and send',+ text: 'Mark up freezes the view so you can draw on it: an arrow, a circle, a dimension. Send to agent saves the picture in the model and passes it to the agent.',+ target: () => [c.marking() ? byId('btn-mark-send') : byId('btn-mark')],+ leave: () => c.closeEmptyMarkup(),+ done: () => c.marking(),+ },+ {+ title: 'Change a value',+ text: 'The agent decides which values you can change here. Change Height and watch the model rebuild. The arrow next to a changed value brings back the agent’s value.',+ target: () => [byId('panel-params')],+ enter: () => c.showPanel('params'),+ done: () => c.paramsChanged(),+ },+ {+ title: 'History',+ text: 'Every change the agent commits adds a dot here, Save adds one too. Click a dot to look at an earlier version. Restore brings it back as a new version, nothing is lost.',+ target: () => [byId('versions')],+ enter: () => c.showPanel(null),+ },+ {+ title: 'Save and export',+ text: 'A model is a single .soma file with code, results and history, like a CAD file. Save (Ctrl S) asks for a place the first time. Export writes parts as STL, 3MF, STEP and more.',+ target: () => [byId('btn-export'), byId('btn-save')],+ },+ {+ title: 'Help is always here',+ text: 'Help (F1) explains every part of the window. The agent knows this guide too, so you can just ask it. You can start this tutorial again from Help.',+ target: () => [byId('btn-help')],+ },+ ];+}diff --git a/app/src/shared/settings.ts b/app/src/shared/settings.tsindex 2983597..a7cfa17 100644--- a/app/src/shared/settings.ts+++ b/app/src/shared/settings.ts@@ -22,9 +22,11 @@ export interface ViewerPrefs {/** Nachkommastellen der Messwerte in der Oberfläche. Der Text für den Agenten hat immer drei. */decimals: number;}-export interface AppSettings { viewer: ViewerPrefs }+/** Startseite (E94): Karte „New to SOMA?“ mit dem Tutorial. „Got it“ blendet sie aus. */+export interface StartPrefs { tutorialCard: boolean }+export interface AppSettings { viewer: ViewerPrefs; start: StartPrefs }/** Änderung aus dem Renderer: nur die Werte, die sich ändern sollen. */-export interface SettingsPatch { viewer?: Partial<ViewerPrefs> }+export interface SettingsPatch { viewer?: Partial<ViewerPrefs>; start?: Partial<StartPrefs> }/** `problem`: settings.json war nicht lesbar oder enthielt Unbekanntes, es gelten (teils) die Vorgaben. */export interface SettingsState { settings: AppSettings; problem?: string }export interface SettingsResult extends SettingsState { ok: boolean; error?: string; backup?: string | null }@@ -32,6 +34,7 @@ export interface SettingsResult extends SettingsState { ok: boolean; error?: strexport const DECIMALS = { min: 0, max: 4 };export const DEFAULT_SETTINGS: AppSettings = {viewer: { navigation: 'soma', invertZoom: false, projection: 'perspective', edges: true, wireframe: false, transparent: false, decimals: 2 },+ start: { tutorialCard: true },};const NAV = (spec: string): NavBinding[] => spec.split(',').map((s) => {@@ -88,6 +91,10 @@ const isBool = (v: unknown): v is boolean => typeof v === 'boolean';const VIEWER_CHECKS: { [K in keyof ViewerPrefs]: (v: unknown) => boolean } = {navigation: isNav, invertZoom: isBool, projection: isProjection, edges: isBool, wireframe: isBool, transparent: isBool, decimals: isDecimals,};+const START_CHECKS: { [K in keyof StartPrefs]: (v: unknown) => boolean } = { tutorialCard: isBool };+/** Bereiche der Einstellungen mit der Prüfung je Wert. */+const SECTIONS: Record<keyof AppSettings, Record<string, (v: unknown) => boolean>> = { viewer: VIEWER_CHECKS, start: START_CHECKS };+const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);/*** Gelesene Einstellungen (nicht vertrauenswürdig) auf gültige Werte bringen: Fehlendes bekommt die Vorgabe, Ungültiges@@ -95,33 +102,41 @@ const VIEWER_CHECKS: { [K in keyof ViewerPrefs]: (v: unknown) => boolean } = {*/export function cleanSettings(raw: unknown): { settings: AppSettings; ignored: string[] } {const ignored: string[] = [];- const v = (raw && typeof raw === 'object' ? (raw as Record<string, unknown>).viewer : undefined) as Record<string, unknown> | undefined;- const viewer = { ...DEFAULT_SETTINGS.viewer } as Record<string, unknown>;- if (v !== undefined && (!v || typeof v !== 'object' || Array.isArray(v))) ignored.push('viewer');- else if (v) {- for (const [k, check] of Object.entries(VIEWER_CHECKS)) {- if (!(k in v)) continue;- if (check(v[k])) viewer[k] = v[k]; else ignored.push(`viewer.${k}`);+ const out: Record<string, Record<string, unknown>> = {};+ for (const [sec, checks] of Object.entries(SECTIONS)) {+ const v = raw && typeof raw === 'object' ? (raw as Record<string, unknown>)[sec] : undefined;+ const cur = { ...(DEFAULT_SETTINGS as unknown as Record<string, Record<string, unknown>>)[sec] };+ if (v !== undefined && !isObj(v)) ignored.push(sec);+ else if (v) {+ for (const [k, check] of Object.entries(checks)) {+ if (!(k in v)) continue;+ if (check(v[k])) cur[k] = v[k]; else ignored.push(`${sec}.${k}`);+ }}+ out[sec] = cur;}- return { settings: { viewer: viewer as unknown as ViewerPrefs }, ignored };+ return { settings: out as unknown as AppSettings, ignored };}/** Änderung prüfen und anwenden. Ein ungültiger Wert verhindert die ganze Änderung (Rückgabe: Fehlertext). */export function applyPatch(cur: AppSettings, patch: unknown): { settings: AppSettings } | { error: string } {if (!patch || typeof patch !== 'object') return { error: 'No settings to change.' };const p = patch as Record<string, unknown>;- const unknown = Object.keys(p).filter((k) => k !== 'viewer');+ const unknown = Object.keys(p).filter((k) => !(k in SECTIONS));if (unknown.length) return { error: `Unknown setting “${unknown[0]}”.` };- const v = p.viewer;- if (v === undefined) return { settings: cur };- if (!v || typeof v !== 'object' || Array.isArray(v)) return { error: 'Invalid viewer settings.' };- const viewer = { ...cur.viewer } as Record<string, unknown>;- for (const [k, val] of Object.entries(v as Record<string, unknown>)) {- const check = (VIEWER_CHECKS as Record<string, (x: unknown) => boolean>)[k];- if (!check) return { error: `Unknown setting “viewer.${k}”.` };- if (!check(val)) return { error: `Invalid value for “viewer.${k}”: ${JSON.stringify(val)}.` };- viewer[k] = val;+ const next = { ...cur } as unknown as Record<string, Record<string, unknown>>;+ for (const [sec, v] of Object.entries(p)) {+ if (v === undefined) continue;+ if (!isObj(v)) return { error: `Invalid ${sec} settings.` };+ const checks = SECTIONS[sec as keyof AppSettings];+ const vals = { ...next[sec] };+ for (const [k, val] of Object.entries(v)) {+ const check = checks[k];+ if (!check) return { error: `Unknown setting “${sec}.${k}”.` };+ if (!check(val)) return { error: `Invalid value for “${sec}.${k}”: ${JSON.stringify(val)}.` };+ vals[k] = val;+ }+ next[sec] = vals;}- return { settings: { ...cur, viewer: viewer as unknown as ViewerPrefs } };+ return { settings: next as unknown as AppSettings };}diff --git a/app/src/shared/types.ts b/app/src/shared/types.tsindex 73e6e44..7c2b0a4 100644--- a/app/src/shared/types.ts+++ b/app/src/shared/types.ts@@ -367,7 +367,8 @@ export interface SomaApi {startsHome: boolean;project: {current(): Promise<ProjectInfo>;- create(): Promise<ProjectInfo>;+ /** Neues Modell aus der Vorlage. `tutorial` (E94): dieselbe Vorlage unter dem Namen „Tutorial“. */+ create(kind?: 'tutorial'): Promise<ProjectInfo>;list(): Promise<ProjectListEntry[]>;open(id: string): Promise<ProjectInfo>;onChanged(cb: (p: ProjectInfo) => void): void;diff --git a/app/test/helpshots-spec.mjs b/app/test/helpshots-spec.mjsindex a402e45..be1a859 100644--- a/app/test/helpshots-spec.mjs+++ b/app/test/helpshots-spec.mjs@@ -27,6 +27,7 @@ export const SHOTS = [{file: 'start.png',marks: [+ { label: 'Tutorial', sel: '#start-tour', at: 'tr', box: true },{ label: 'New model', sel: '#start-new', at: 'tr', box: true },{ label: 'Open', sel: '#start-open', at: 'tr', box: true },{ label: 'Recent', sel: '#start-recent', at: 'tr', box: true },diff --git a/app/test/run-all.mjs b/app/test/run-all.mjsindex bd3748a..537fb57 100644--- a/app/test/run-all.mjs+++ b/app/test/run-all.mjs@@ -9,7 +9,7 @@ import path from 'node:path';const DIR = import.meta.dirname;// Längste zuerst, damit sie nicht am Ende allein laufen-const ALL = ['animation', 'fem', 'versions', 'smoke', 'editor', 'skills', 'params', 'explode', 'fasteners', 'drawing', 'section', 'measure', 'groups', 'dxf', 'packages', 'settings', 'unit'];+const ALL = ['animation', 'fem', 'versions', 'smoke', 'editor', 'skills', 'params', 'explode', 'fasteners', 'drawing', 'section', 'measure', 'groups', 'dxf', 'packages', 'settings', 'tutorial', 'unit'];const wanted = process.argv.slice(2);const unknown = wanted.filter((s) => !ALL.includes(s));if (unknown.length) { console.log(`Unbekannte Suite: ${unknown.join(', ')}. Vorhanden: ${ALL.join(', ')}`); process.exit(2); }diff --git a/app/test/tutorial.mjs b/app/test/tutorial.mjsnew file mode 100644index 0000000..1aae76c--- /dev/null+++ b/app/test/tutorial.mjs@@ -0,0 +1,203 @@+// Test des Tutorials (E94): Karte „New to SOMA?“ auf der Startseite (erster Start, „Got it“ bleibt über einen Neustart,+// kaputte settings.json zeigt sie wieder), „Start tutorial“ legt das Modell „Tutorial“ an und zeigt Schritt 1, Next, Back,+// Skip und Escape, jedes Ziel der Schritte vorhanden (fängt Änderungen an der Oberfläche), Karte im Fenster, Haken beim+// Ausprobieren, fehlendes Ziel ohne Rahmen in der Mitte, Neustart aus der Hilfe mit Rückfrage, unverändertes Tutorial-Modell+// verschwindet (E69). Aufruf: node test/run-all.mjs tutorial (nach npm run build). SMOKE_VISIBLE=offscreen SMOKE_SHOTS=1+// legt Bilder in test/shots/ ab.+import fs from 'node:fs';+import path from 'node:path';+import { APP, checker, cleanup, sleep, startApp } from './harness.mjs';++const t = checker();+const { check } = t;+let app;+let ud = null;++try {+ app = await startApp({ name: 'tutorial', env: { SOMA_TEST_START: 'home' } });+ ud = app.ud;+ const settingsFile = path.join(ud, 'settings.json');+ const fileSettings = () => { try { return JSON.parse(fs.readFileSync(settingsFile, 'utf8')); } catch { return null; } };+ const shot = async (name) => {+ if (!process.env.SMOKE_SHOTS) return;+ fs.mkdirSync(path.join(APP, 'test', 'shots'), { recursive: true });+ await sleep(900);+ await app.screenshot(path.join(APP, 'test', 'shots', `${name}.png`)).catch((e) => console.log('Screenshot:', e.message));+ };+ /** Startseite offen und Einstellungen geladen (sonst gilt noch die Vorgabe der Karte). */+ const home = async (a) => {+ await a.waitFor('Startseite', () => !!window.__t && !document.getElementById('start').hidden, 30000);+ await sleep(1500);+ };+ const cardShown = (a) => a.ev(() => !document.getElementById('start-tour').hidden && document.getElementById('start-tour').getClientRects().length > 0);++ // ---- 1) Karte beim ersten Start, „Got it“ und Neustart ------------------------------------------------------------+ await home(app);+ check('Erster Start: Karte „New to SOMA?“ mit Start tutorial und Got it', await cardShown(app)+ && (await app.ev(() => document.getElementById('start-tour').textContent)).includes('New to SOMA?') && fileSettings() === null);+ await shot('tutorial-start');+ await app.domClick('btn-tour-dismiss');+ await app.waitFor('Einstellung geschrieben', () => window.__t.appSettings().settings.start.tutorialCard === false, 10000).catch(() => {});+ check('„Got it“ blendet die Karte aus und steht in settings.json', !(await cardShown(app)) && fileSettings()?.start?.tutorialCard === false, JSON.stringify(fileSettings()));+ check('„Got it“ lässt die übrigen Einstellungen bei den Vorgaben', fileSettings()?.viewer?.navigation === 'soma');++ await app.stop();+ app = await startApp({ name: 'tutorial', userData: ud, env: { SOMA_TEST_START: 'home' } });+ await home(app);+ check('Nach dem Neustart bleibt die Karte aus', !(await cardShown(app)) && (await app.ev(() => window.__t.appSettings().settings.start.tutorialCard)) === false);++ // Kaputte settings.json: Es gelten die Vorgaben, die Karte erscheint wieder, nichts stürzt ab+ await app.stop();+ fs.writeFileSync(settingsFile, '{ kaputt');+ app = await startApp({ name: 'tutorial', userData: ud, env: { SOMA_TEST_START: 'home' } });+ await home(app);+ check('Kaputte settings.json: Karte mit der Vorgabe wieder da, Problem gemeldet', await cardShown(app) && !!(await app.ev(() => window.__t.appSettings().problem)));++ // ---- 2) Tutorial starten ----------------------------------------------------------------------------------------------+ const { ev, waitFor, domClick, page } = app;+ const tour = () => ev(() => window.__t.tour());+ await domClick('btn-tour-start');+ await waitFor('Tutorial-Modell', () => !!window.__t.project() && window.__t.status().state === 'ok' && window.__t.partCount() === 2, 90000);+ await waitFor('Tour', () => window.__t.tour().active, 20000);+ const m1 = await ev(() => window.__t.project());+ let s = await tour();+ check('„Start tutorial“: neues Modell „Tutorial“ mit Kiste und Deckel, Startseite zu', m1.name === 'Tutorial' && fs.existsSync(m1.dir)+ && await ev(() => document.getElementById('start').hidden) && JSON.stringify(await ev(() => window.__t.treeNames())) === '["Body","Lid"]', m1.name);+ check('Schritt 1 von 10 mit Titel, Back gesperrt, Next', s.step === 1 && s.count === 10 && s.title === 'Welcome to SOMA' && s.backDisabled && s.next === 'Next'+ && (await ev(() => document.getElementById('tour-card').textContent)).includes('Step 1 of 10'), JSON.stringify(s).slice(0, 160));+ check('Schritt 1 hebt den Viewer hervor', s.target && s.spot);+ await shot('tutorial-step1');++ await domClick('btn-tour-next');+ await waitFor('Schritt 2', () => window.__t.tour().step === 2, 5000);+ s = await tour();+ check('Next: Schritt 2 „Start your agent“, + hervorgehoben, Agenten genannt oder Hinweis zum Installieren', s.title === 'Start your agent' && s.target+ && /SOMA does not bring its own agent/.test(s.text) && (/Click \+ and choose one: /.test(s.text) || /install one/.test(s.text)), s.text.slice(0, 120));+ await shot('tutorial-step2');+ await domClick('btn-tour-back');+ await waitFor('zurück', () => window.__t.tour().step === 1, 5000);+ check('Back: wieder Schritt 1', (await tour()).title === 'Welcome to SOMA');++ // ---- 3) Jeder Schritt: Ziel vorhanden und hervorgehoben, Karte im Fenster und nicht über dem Ziel ---------------------+ const bad = [];+ const titles = (await tour()).titles;+ for (let n = 1; n <= titles.length; n++) {+ await ev((k) => window.__t.tourGo(k), n);+ await sleep(500);+ s = await tour();+ const inView = s.card.x >= 0 && s.card.y >= 0 && s.card.x + s.card.w <= s.view.w && s.card.y + s.card.h <= s.view.h;+ if (!(s.step === n && s.target && s.spot && inView)) bad.push(`${n} ${s.title}: Ziel ${s.target}, Rahmen ${s.spot}, im Fenster ${inView}`);+ }+ check('Jeder Schritt findet sein Element, hebt es hervor, Karte ganz im Fenster', !bad.length, bad.join(' | '));+ check('Schritte: Agent, Code, Teil, Messen, Markieren, Parameter, Verlauf, Speichern, Hilfe', titles.join('|')+ === 'Welcome to SOMA|Start your agent|The model is code|Click a part|Measure|Mark up and send|Change a value|History|Save and export|Help is always here', titles.join('|'));++ // Schritt 3 öffnet Dateien und Code, Schritt 7 die Parameter+ await ev(() => window.__t.tourGo(3));+ await waitFor('Code offen', () => window.__t.layout().code && window.__t.layout().side === 'files' && window.__t.codeText().includes('add_part'), 10000).catch(() => {});+ check('Schritt 3 öffnet Files und model.py', (await ev(() => window.__t.layout())).side === 'files' && (await ev(() => window.__t.codeText())).includes('add_part'));+ await shot('tutorial-step3');++ // Schritt 4: Klick auf ein Teil gibt den Haken, Next geht auch ohne+ await ev(() => window.__t.tourGo(4));+ await sleep(600);+ check('Schritt 4 schließt Code und Seitenleiste, noch ohne Haken', !(await ev(() => window.__t.layout().code)) && !(await tour()).done);+ const pos = await ev(() => {+ const v = window.__t.viewer; const id = window.__t.parts().find((p) => p.name === 'Lid').id;+ const f = v.facesOf(id).filter((x) => x.surface === 'PLANE').sort((a, b) => b.center[2] - a.center[2])[0];+ return v.screenOf(id, f.id);+ });+ await page.click(pos.x, pos.y);+ await waitFor('Auswahl', () => window.__t.info().includes('Lid'), 10000).catch(() => {});+ await waitFor('Haken', () => window.__t.tour().done, 5000).catch(() => {});+ check('Klick auf den Deckel durch die Abdunklung: Auswahl, Haken im Schritt', (await ev(() => window.__t.info())).includes('Lid') && (await tour()).done);+ await shot('tutorial-step4');+ await ev(() => document.getElementById('btn-sel-close').click());++ // Schritt 5: Messen an, Haken, Next schaltet es wieder aus+ await ev(() => window.__t.tourGo(5));+ await domClick('btn-measure');+ await waitFor('Haken Messen', () => window.__t.tour().done, 5000).catch(() => {});+ check('Schritt 5: Messen an gibt den Haken, das Ziel ist dann die Karte des Messens', (await tour()).done && (await tour()).target);+ await domClick('btn-tour-next');+ await waitFor('Schritt 6', () => window.__t.tour().step === 6, 5000);+ check('Next beendet das Messen', !(await ev(() => window.__t.measure().active)));++ // Schritt 7: Höhe ändern, der Haken kommt nach dem Build+ await ev(() => window.__t.tourGo(7));+ await waitFor('Parameter', () => window.__t.layout().side === 'params' && !!document.getElementById('pm-HEIGHT'), 20000).catch(() => {});+ await ev(() => { const f = document.getElementById('pm-HEIGHT'); f.focus(); f.value = '35'; f.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true })); });+ await waitFor('Haken Parameter', () => window.__t.tour().done, 30000).catch(() => {});+ check('Schritt 7: Parameter offen, Height 35 gibt den Haken', (await tour()).done && (await ev(() => window.__t.params().changed)).includes('HEIGHT'));+ await waitFor('gebaut', () => window.__t.status().state === 'ok', 30000).catch(() => {});+ await shot('tutorial-step7');++ // Fehlendes Ziel (Oberfläche geändert): Karte ohne Rahmen in der Mitte+ await ev(() => window.__t.tourGo(10));+ await sleep(300);+ await ev(() => { document.getElementById('btn-help').style.display = 'none'; });+ await sleep(400);+ s = await tour();+ const mid = Math.abs(s.card.x + s.card.w / 2 - s.view.w / 2) < 3 && Math.abs(s.card.y + s.card.h / 2 - s.view.h / 2) < 3;+ check('Ziel fehlt: Karte ohne Rahmen in der Mitte, Tour läuft weiter', s.active && !s.target && !s.spot && mid, JSON.stringify(s.card));+ await ev(() => { document.getElementById('btn-help').style.display = ''; });+ await sleep(300);+ s = await tour();+ check('Letzter Schritt: „Done“ statt Next, Ziel wieder da', s.next === 'Done' && s.target && s.title === 'Help is always here');+ await shot('tutorial-step10');+ await domClick('btn-tour-next');+ await sleep(500);+ check('„Done“ beendet die Tour, Hinweis auf die Hilfe', !(await tour()).active && (await ev(() => window.__t.toast())).text.includes('Help'));+ await waitFor('Karte aus', () => window.__t.appSettings().settings.start.tutorialCard === false, 10000).catch(() => {});+ check('Durchlaufen blendet die Karte der Startseite aus (settings.json neu, alte gesichert)', fileSettings()?.start?.tutorialCard === false+ && fs.readdirSync(path.join(ud, 'workspace-backups')).some((n) => n.startsWith('settings-')));++ // ---- 4) Neu starten aus der Hilfe, Escape und Skip --------------------------------------------------------------------+ await ev(() => window.__t.openHelp());+ await waitFor('Hilfe', () => window.__t.help().open, 10000);+ check('Hilfe hat oben „Start tutorial“', await ev(() => !!document.getElementById('btn-help-tour').getClientRects().length));+ await app.answers([1]);+ await domClick('btn-help-tour');+ await sleep(1500);+ check('Rückfrage bei offenem Modell, Cancel lässt alles, wie es ist', (await ev(() => window.__t.project().id)) === m1.id && !(await tour()).active && (await ev(() => window.__t.help().open)));+ await app.answers([0]);+ await domClick('btn-help-tour');+ await waitFor('zweites Tutorial-Modell', (id) => window.__t.project()?.id !== id && window.__t.status().state === 'ok' && window.__t.tour().active, 90000, m1.id);+ const m2 = await ev(() => window.__t.project());+ s = await tour();+ check('Aus der Hilfe: neues Modell „Tutorial“, Hilfe zu, Schritt 1', m2.name === 'Tutorial' && s.step === 1 && !(await ev(() => window.__t.help().open)));+ check('Geändertes erstes Tutorial-Modell (Height) bleibt', fs.existsSync(m1.dir));+ await ev(() => window.__t.tourGo(2));+ await ev(() => document.body.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true })));+ await sleep(300);+ check('Escape beendet die Tour', !(await tour()).active);+++ // Hilfe über der Tour: Die Tour wartet unsichtbar+ await app.answers([0]);+ await ev(() => window.__t.openHelp());+ await waitFor('Hilfe', () => window.__t.help().open, 10000);+ await domClick('btn-help-tour');+ await waitFor('drittes Tutorial-Modell', (id) => window.__t.project()?.id !== id && window.__t.status().state === 'ok' && window.__t.tour().active, 90000, m2.id);+ const m3 = await ev(() => window.__t.project());+ const gone = async (dir) => { for (let i = 0; i < 50 && fs.existsSync(dir); i++) await sleep(300); return !fs.existsSync(dir); };+ check('Unverändertes Tutorial-Modell verschwindet beim Wechsel (E69)', await gone(m2.dir));+ await ev(() => window.__t.openHelp());+ await waitFor('Hilfe', () => window.__t.help().open, 10000);+ await sleep(300);+ check('Hilfe offen: Tour verdeckt, läuft weiter', await ev(() => document.getElementById('tour').classList.contains('covered')) && (await tour()).active);+ await ev(() => window.__t.closeHelp());+ await sleep(300);+ await domClick('btn-tour-skip');+ await sleep(300);+ check('Skip beendet die Tour', !(await tour()).active && (await ev(() => window.__t.project().id)) === m3.id);++ const relevant = page.errors.filter((e) => !/favicon/i.test(e));+ check('Keine Konsolenfehler im Renderer', relevant.length === 0, relevant.slice(0, 2).join(' | ').slice(0, 120));+} catch (e) {+ console.log('ABBRUCH:', e.message);+ t.fail();+}+if (app) { await app.stop(); cleanup(app.ud); }+console.log(t.fails ? `\n${t.fails} Prüfung(en) fehlgeschlagen` : '\nALLE PRÜFUNGEN BESTANDEN');+process.exit(t.fails ? 1 : 0);