Skip to content

armgit / SOMA

Public Imported from GitHub
0

Desktop app for designing parametric 3D models in CadQuery together with the coding agent of your choice

37.9 KB
Raw Blame
// Von Hauptprozess, Preload und Renderer gemeinsam genutzte Typen (IPC-Vertrag).
import type { SettingsPatch, SettingsResult, SettingsState } from './settings';

export interface ProjectInfo {
  id: string;
  name: string;
  dir: string;
  /** Gefundene Auffaelligkeiten im Projekt (nur melden, nie automatisch reparieren, E28). */
  problems: string[];
  autoBuild: boolean;
  /** Geöffneter Ordner des Nutzers (Ordner-Modus): kein Speichern als .soma, Verlauf nur lesen. */
  folder: boolean;
  /** Einstiegsdatei laut project.json (meist model.py). */
  entry: string;
}

/** `saved`: Es gibt eine Modelldatei dazu (das Modell wurde mindestens einmal gespeichert). */
/** `folder`: geöffneter Ordner (Ordner-Modus) mit seinem Pfad, `missing`: den Ordner gibt es nicht mehr. */
export interface ProjectListEntry { id: string; name: string; modified: number; saved?: boolean; folder?: string; missing?: boolean }
/** Modell von der Startseite entfernen (E69). `cancelled`: Rückfrage abgebrochen, nichts geändert. */
export interface RemoveResult { removed: boolean; cancelled?: boolean; error?: string }

export interface BuildError { kind: string; message: string; file: string | null; line: number | null; traceback: string }

export interface BuildResult {
  status: 'ok' | 'error';
  parts?: { name: string; role: string; file: string; line: number }[];
  error?: BuildError;
  timings?: Record<string, number>;
  warnings?: string[];
  /** Parameter des Modells (`param()` im Code), auch nach einem Fehler: die bis dahin angelegten. */
  params?: ParamInfo[];
}

/** Wert eines Parameters: Zahl, Schalter oder Text. */
export type ParamValue = number | boolean | string;
/**
 * Ein Parameter aus `soma.param()`, so wie ihn der letzte Build kennt. `default` steht im Code (der Wert des Agenten),
 * `value` hat der Build verwendet, `source` sagt, woher er kam (`user`: aus parameters.json).
 */
export interface ParamInfo {
  name: string; label: string; kind: 'number' | 'int' | 'bool' | 'choice' | 'text';
  default: ParamValue; value: ParamValue; source: 'code' | 'user';
  min: number | null; max: number | null; step: number | null; unit: string | null;
  options: { value: ParamValue; label: string }[] | null;
  group: string | null; help: string | null; file: string; line: number;
}
/**
 * Stand des Parameter-Panels. `params`: Parameter aus dem letzten Build, der sie kannte (null: noch keiner).
 * `values`: Werte des Nutzers aus parameters.json, gelten vor den Werten im Code. `error`: Die Datei ist nicht lesbar.
 * `stale`: Die Liste stammt von einem früheren Build, weil der letzte vor den Parametern scheiterte.
 */
export interface ParamState { params: ParamInfo[] | null; values: Record<string, ParamValue>; error?: string; stale?: boolean }
export interface ParamResult extends ParamState { ok: boolean; message?: string }

export type BuildState = 'idle' | 'building' | 'ok' | 'error';
export interface BuildStatus {
  state: BuildState; result?: BuildResult; startedAt?: number; queued?: boolean; reason?: string;
  /** Gesamtdauer des letzten Builds in Sekunden, vom Start bis zum Ergebnis (inkl. Python-Start). */
  seconds?: number;
  /** Zeitpunkt des Ergebnisses (ms). Hat die App beim Öffnen den letzten Build übernommen, liegt er vor dem Öffnen. */
  builtAt?: number;
  /** Auto-Build ist aus und der Quelltext hat sich seit dem letzten Build geändert. */
  stale?: boolean;
  /** Pakete aus requirements.txt, die gerade installiert werden (E67). Builds warten so lange. */
  installing?: string[];
  /** Projektumgebung oder Pakete ließen sich nicht einrichten (E67). Bleibt, bis eine Installation gelingt. */
  packageError?: string;
}

/** Einzelexport über `soma export` (E34). `files` relativ zum Projekt. */
/**
 * Export über einen Dateidialog. `files`: geschriebene Dateien mit absolutem Pfad, `target`: gewählte Datei oder gewählter
 * Ordner. `cancelled`: Dialog oder Rückfrage abgebrochen, nichts geschrieben.
 */
/**
 * Einstellungen für Netzformate (STL, 3MF, AMF, OBJ, GLB, GLTF) beim Export, Issue #8. Fehlt ein Wert, gilt die Vorgabe des
 * Formats in `soma export`: GLB/GLTF in Metern mit Y nach oben, alles andere in mm mit Z nach oben.
 */
export interface MeshExportOptions { units?: 'mm' | 'm'; up?: 'z' | 'y'; detail?: 'coarse' | 'normal' | 'fine' }

export interface ExportResult { ok: boolean; files: string[]; target?: string; cancelled?: boolean; error?: string; warnings?: string[] }
/** Neues Modell aus einem CadQuery-Skript (E100). `info`: das geöffnete Modell, `warnings`: Hinweise des Imports. */
export interface CadQueryImportResult { info?: ProjectInfo; warnings: string[]; cancelled?: boolean; error?: string }
/** Dateien, die per Ziehen nach inputs/ kopiert wurden (E33). */
export interface ImportResult { files: string[]; errors: string[] }
/**
 * Schreiben aus dem Editor. `conflict`: Die Datei hat sich seit dem Laden außerhalb geändert (meist durch den Agenten),
 * `disk` ist ihr aktueller Inhalt (null: gelöscht). `backup`: Pfad der Sicherung der überschriebenen Fassung.
 */
export interface WriteResult { ok: boolean; conflict?: boolean; disk?: string | null; backup?: string; error?: string }
/** Gespeicherte Markierung (E16). `path` relativ zum Projekt, z. B. `.soma/feedback/markierung-20260930-1405.png`. */
export interface FeedbackResult { ok: boolean; path?: string; error?: string }

/** Anlegen, Umbenennen oder Löschen im Dateibaum. `path` relativ zum Projekt (neuer Pfad), `canceled`: Rückfrage abgelehnt. */
export interface FileOpResult { ok: boolean; path?: string; error?: string; canceled?: boolean }

/**
 * DXF für die Ansicht im Code-Panel (E80), gezeichnet von `soma dxfview` mit ezdxf. Ein Stapel ist Geometrie gleicher Art,
 * Layer, Farbe und Strichstärke. `ops`: Befehle 0 M, 1 L, 2 Q, 3 C, 4 Z, ihre Koordinaten der Reihe nach in `xy` (bei
 * Punkten nur `xy`). Alle Koordinaten relativ zu `origin`, Strichstärke `lw` in mm.
 */
export interface DxfBatch { kind: 'line' | 'fill' | 'text' | 'point'; layer: number; color: string; lw: number; ops: Uint8Array; xy: Float32Array }
/** `off`: in der Datei aus- oder eingefroren, die Ansicht blendet ihn zunächst aus. `count`: Objekte darauf im gezeigten Bereich. */
export interface DxfLayer { name: string; color: string; off: boolean; count: number }
export interface DxfDrawing {
  /** Einheit aus $INSUNITS (z. B. 'mm'), null ohne Angabe. */
  units: string | null;
  /** Name des Papierbereichs, wenn der Modellbereich leer war und er stattdessen gezeigt wird. */
  layout: string | null;
  origin: [number, number];
  /** Umgebendes Rechteck relativ zu `origin`, null wenn nichts zu zeichnen ist. */
  box: [number, number, number, number] | null;
  layers: DxfLayer[];
  batches: DxfBatch[];
  /** Nicht gezeichnete Objekte je Typ (z. B. 3DSOLID). */
  skipped: Record<string, number>;
  /** Probleme beim Lesen, die ezdxf umgangen hat. Die Datei bleibt, wie sie ist. */
  issues: number;
  /** Sehr große Zeichnung, nur ein Teil ist da. */
  truncated: boolean;
  entities: number;
}
/** `sig`: Fingerabdruck der Datei (Größe, Änderungszeit). `unchanged`: gleich dem bekannten, nichts mitgeschickt. `gone`: Datei weg. */
export interface DxfResult { ok: boolean; sig?: string; unchanged?: boolean; gone?: boolean; error?: string; drawing?: DxfDrawing }

export interface FileNode { name: string; path: string; dir: boolean; children?: FileNode[] }

export interface AgentInfo { id: string; label: string; command: string; found: boolean }

export interface PartMap {
  id: string; name: string; step_name: string; role: string;
  file?: string; line?: number; end_line?: number; volume?: number;
  /** Gruppe mit „/“ verschachtelt, z. B. „Gehäuse/Schrauben“ (aus add_part(group=…) oder einer importierten Baugruppe). */
  group?: string | null;
  /** Achsparallele Hülle [[xmin, ymin, zmin], [xmax, ymax, zmax]] in mm. */
  bbox?: number[][];
  /** Nur bei Netzdateien (STL, 3MF …): Anzahl Dreiecke und ob das Netz geschlossen ist. */
  triangles?: number; closed?: boolean;
}
/** `build`: Kennung des Builds. Sie verbindet GLB, Mapping und die exakte Geometrie für das Messen. */
/** `mesh`: aus einer Netzdatei (STL, 3MF, AMF, OBJ), ohne CAD-Geometrie und ohne `build`, also nicht messbar. */
export interface ModelMap { version: number; build?: string; mesh?: boolean; notes?: string[]; parts: PartMap[] }

/** Art eines Elements beim Messen: Fläche, Kante oder Eckpunkt. */
export type MeasureKind = 'face' | 'edge' | 'vertex';
/**
 * Angeklicktes Element (E9). `point`: Klickpunkt auf dem Netz, bei Eckpunkten ihre Lage (zum Abgleich).
 * `check`: Flächeninhalt bzw. Länge laut Viewer, zum Abgleich.
 */
export interface MeasureEntity { part: string; kind: MeasureKind; id: number; point: number[] | null; check?: number }
export interface MeasureRequest { build: string; a: MeasureEntity; b?: MeasureEntity }
/** Exakte Angaben zu einem Element, Längen in mm, Winkel in Grad. `point`: Klickpunkt, exakt auf das Element gelegt. */
export interface MeasureInfo {
  kind: MeasureKind; part: string; name?: string; type: string; point: number[] | null;
  area?: number; length?: number; radius?: number; normal?: number[]; origin?: number[];
  axis?: { point: number[]; dir: number[] }; center?: number[]; start?: number[]; end?: number[]; dir?: number[];
  semiAngle?: number; refRadius?: number; majorRadius?: number; minorRadius?: number; closed?: boolean;
}
/** Eine Strecke: Wert und die beiden Endpunkte (zum Zeichnen). */
export interface MeasureSpan { value: number; p1: number[]; p2: number[]; delta?: number[] }
/**
 * `planes`: Abstand paralleler Ebenen, `axes`: Abstand paralleler Achsen, `min`: kürzester Abstand, `points`: Klickpunkt zu
 * Klickpunkt. Mit einem Eckpunkt: `toPlane`, `toAxis`, `toLine` (Lot auf die unbegrenzte Ebene, Achse bzw. Gerade).
 */
export interface MeasurePair {
  min: MeasureSpan; points?: MeasureSpan; planes?: MeasureSpan; axes?: MeasureSpan;
  toPlane?: MeasureSpan; toAxis?: MeasureSpan; toLine?: MeasureSpan; angle?: number;
}
export interface MeasureResult { build: string; a: MeasureInfo; b?: MeasureInfo; pair?: MeasurePair }
/**
 * `stale`: Die Anfrage gehört zu einem älteren Build, die Auswahl ist neu zu treffen. `rebuilt`: Auf der Platte liegt ein
 * neuerer Build als im Viewer (`soma build` im Terminal), der Viewer muss ihn erst laden.
 */
export interface MeasureResponse { ok: boolean; result?: MeasureResult; error?: string; stale?: boolean; rebuilt?: boolean }
export interface MeasurePrepared { ok: boolean; error?: string; stale?: boolean; rebuilt?: boolean }

/** Wert einer Einstellung eines Skills: Zahl oder gewählter Eintrag. */
export type SkillValue = number | string;
/** Einstellung eines Skills, im Kopf der Skill-Datei erklärt (`var …`) und im Text als `{{name}}` eingesetzt. */
export interface SkillVar {
  name: string; label: string;
  /** Einheit hinter der Zahl, etwa „mm“ oder „°“, sonst leer. */
  unit: string;
  kind: 'number' | 'choice';
  value: SkillValue; default: SkillValue;
  /** Erlaubter Bereich (Zahlen). */
  min?: number; max?: number;
  /** Auswahl: Wert für den Agenten und Anzeige in der Oberfläche. */
  options?: { value: string; label: string }[];
}

/**
 * Wie ein Skill für ein Modell gilt (E55): `off` (Aus) der Agent sieht ihn nicht, `demand` (Bei Bedarf) er liegt im Projekt
 * und `AGENTS.md` nennt ihn mit Anlass, der Agent liest ihn, wenn das Thema aufkommt, `always` (Immer) der Agent befolgt ihn
 * bei jeder Änderung.
 */
export type SkillMode = 'off' | 'demand' | 'always';

/** Ein Skill (E17): Regelwerk für den Agenten, pro Modell einstellbar. */
export interface SkillInfo {
  id: string;
  /** Titel und Kurzbeschreibung für die Oberfläche, Themen aus den Zwischenüberschriften. */
  title: string; summary: string; topics: string[]; order: number;
  /** Überschrift im Panel, leer: ohne Kategorie (steht unter „Weitere“). */
  category: string;
  /** Herkunft in der Bibliothek (E78), null: nicht in der Bibliothek, er liegt nur im Projekt (neuere App, anderer Rechner). */
  source: SkillSource | null;
  /** Stufe bei neuen Modellen (E46, E55), gilt für die ganze App, nicht für dieses Modell. */
  defaultMode: SkillMode;
  /** Stufe laut project.json. */
  mode: SkillMode;
  /** Kopie im Projekt (`.soma/skills/<id>.md`), null wenn keine da ist. */
  file: string | null;
  /** Die Kopie im Projekt weicht von der mitgelieferten Fassung (mit den eingestellten Werten) ab. */
  changed: boolean;
  /** Einstellungen mit ihren aktuellen Werten (nur bei mitgelieferten Skills). */
  vars: SkillVar[];
  /** Auffälligkeiten, nur gemeldet (E28). */
  problems: string[];
}
export interface SkillResult { ok: boolean; error?: string; warning?: string; backup?: string | null; skills: SkillInfo[] }

/** Herkunft eines Skills (E78): mitgeliefert, mitgeliefert und vom Nutzer bearbeitet, eigener des Nutzers. */
export type SkillSource = 'builtin' | 'edited' | 'own';
/** Ein Skill der Bibliothek in den Einstellungen (E78), unabhängig vom offenen Modell. */
export interface LibrarySkill {
  id: string; title: string; summary: string; category: string; order: number;
  source: SkillSource;
  /** Stufe bei neuen Modellen (Vorgabe des Nutzers oder Kopf des Skills). */
  defaultMode: SkillMode;
  /** Bei „edited“: Die App bringt inzwischen eine andere Fassung mit als die, auf der die Bearbeitung beruht. */
  newerBuiltin: boolean;
}
/** Datei im Ordner der eigenen Skills, die die App nicht liest (falscher Name, zu groß), mit Grund. */
export interface IgnoredSkillFile { name: string; reason: string }
export interface LibraryState { skills: LibrarySkill[]; ignored: IgnoredSkillFile[]; dir: string }
/** Text eines Skills zum Bearbeiten. `builtin`: die mitgelieferte Fassung, wenn es eine gibt. */
export interface LibraryText { id: string; source: SkillSource; text: string; builtin: string | null }
/** Prüfung eines Skill-Texts: Fehler verhindern das Speichern, Hinweise nicht (E28). */
export interface SkillCheck { errors: string[]; warnings: string[] }
export interface LibraryResult {
  ok: boolean; error?: string;
  /** Kennung des angelegten, gespeicherten oder importierten Skills. */
  id?: string;
  /** Sicherung einer ersetzten oder entfernten Fassung. */
  backup?: string | null;
  /** Hinweise zum gespeicherten Text oder zum Import. */
  warnings?: string[];
  /** Import: nichts gewählt oder abgebrochen. */
  canceled?: boolean;
  /** Import: Kennungen der übernommenen Skills. */
  imported?: string[];
  library: LibraryState;
}
/** Bereich der App-Daten in den Einstellungen (E81). Der Renderer nennt nur die Kennung, den Ordner kennt der Hauptprozess. */
export type StorageArea = 'appdata' | 'workspaces' | 'backups' | 'previews' | 'thumbnails' | 'skills' | 'logs';
/** Größe eines Bereichs. `other`: alles Übrige in den App-Daten. `models`: Zahl der Arbeitsordner. */
export interface StorageEntry { id: StorageArea | 'other'; path: string | null; bytes: number; files: number; models?: number }
export interface StorageStats { dir: string; total: number; areas: StorageEntry[] }
/** Vorschau-Cache leeren. `kept`: Die Vorschauen des offenen Modells blieben. `canceled`: Rückfrage abgelehnt. */
export interface StorageClear { ok: boolean; canceled?: boolean; freed?: number; kept?: boolean; error?: string; stats?: StorageStats }

/**
 * Neue Version unter GitHub Releases (Startseite). `skipped`: nicht gefragt (Test ohne Adresse). `url`: Seite der neuesten
 * Veröffentlichung, sonst die Liste aller.
 */
export interface UpdateInfo {
  state: 'newer' | 'current' | 'error' | 'skipped';
  current: string; latest?: string; url: string; published?: string; error?: string;
}

/** Eine mitgelieferte Komponente: npm-Paket der App oder Python-Paket, das soma voraussetzt. Lizenz wie in ihren Metadaten. */
export interface ComponentInfo { name: string; version: string; license: string }
/** Angaben für „About“ in den Einstellungen (E81). */
export interface AboutInfo {
  version: string; electron: string; chrome: string; node: string; os: string;
  /** Version des mitgelieferten Git (dugite), null wenn es nicht antwortet. */
  git: string | null;
  python: { exe: string; version?: string; packages: ComponentInfo[]; error?: string };
  agents: AgentInfo[];
  paths: { label: string; path: string }[];
  components: ComponentInfo[];
}

/**
 * Was vermessen wird: der aktuelle Stand, die Vorschau eines alten Stands oder eine STEP-Datei aus dem Projekt (`key`: die
 * Kennung ihres Inhalts aus `project.viewFile`, damit eine inzwischen geänderte Datei nicht still anders vermessen wird).
 */
export type MeasureSource = 'live' | { preview: string } | { file: string; key: string };

/** Stand der Speicherung: was ist gesichert, was nicht (E21). */
export interface SaveState {
  /** Modelldatei (.soma, bei älteren oder als ZIP geöffneten Modellen bis zum nächsten Speichern eine .zip, E79). */
  zipPath: string | null;
  savedHead: string | null;
  head: string | null;
  /** Geänderte Dateien seit dem letzten Commit (ohne output/). */
  dirtyFiles: number;
  unsaved: boolean;
  hasRepo: boolean;
  /** Zeitpunkt des letzten Speicherns (ms seit 1970), null wenn noch nie gespeichert. */
  savedAt: number | null;
}
export interface SaveResult { cancelled: boolean; zipPath?: string; snapshot?: string | null; files?: number; bytes?: number; warnings?: string[]; error?: string }
export interface OpenResult { cancelled: boolean; opened?: boolean; error?: string }

/** `byApp`: Stand hat die App angelegt (Start, Snapshot, Wiederherstellen), sonst der Agent oder der Nutzer. */
export interface CommitInfo { hash: string; short: string; author: string; date: string; subject: string; byApp: boolean }
export interface GitLog { commits: CommitInfo[]; problems: string[]; head: string | null; dirtyFiles: number }
export interface PreviewResult { commit: CommitInfo | null; glb: ArrayBuffer; map: ModelMap; error?: string }
/** STEP-Datei aus dem Projekt im Viewer (`project.viewFile`). `key`: SHA-1 des Inhalts, unter dem die Umwandlung im Cache liegt. */
export interface FileViewResult { rel: string; key: string; glb: ArrayBuffer; map: ModelMap; error?: string }
export interface RestoreResult { cancelled: boolean; commit?: string | null; safety?: string | null; error?: string }

/** Animation aus animations/*.py (E58), gebaut nach `glb`. `stale`: Code oder Animationsdatei sind neuer. */
export interface AnimEntry { id: string; name: string; file: string; line: number | null; duration: number; glb: string; parts: number; stale: boolean }
/** Fehler einer Animationsdatei (sie hat dann keine Einträge). */
export interface AnimFileError { file: string; line: number | null; message: string }
export interface AnimList { animations: AnimEntry[]; errors: AnimFileError[]; building: boolean }
export interface AnimBuildResult extends AnimList { ok: boolean; error?: string }

/**
 * Technische Zeichnungen (E76) aus .soma/drawings/index.json. Blattmaße in mm ab der linken unteren Papierecke, Punkte und
 * Richtungen im Modell (mm, Z oben) wie im Viewer. Die Felder ab Index-Version 2 fehlen bei älteren Builds.
 */
export interface DrawingView {
  name: string; kind: string; scale: string; line: number | null; file: string | null;
  /** Vom Teil zum Betrachter. */
  direction: number[];
  /** Lage auf dem Blatt [x0, y0, x1, y1]. */
  bbox: number[];
  parts?: string[]; right?: number[]; up?: number[]; center?: number[]; size?: number;
  /** Schnitt: Ebene durch `point`, `normal` zeigt zur weggenommenen Seite (zum Betrachter). Stufenschnitte ohne Ebene. */
  section?: { kind: string; point?: number[]; normal?: number[] };
  detail?: { center: number[]; radius: number; parent: string };
}
export interface DrawingDim {
  kind: string; value: number; label: string; view: string; line: number | null; file: string | null;
  points?: number[][]; radius?: number | null;
  /** Maß mit Linien und Text auf dem Blatt, und nur der Text. */
  box?: number[]; textBox?: number[];
}
export interface DrawingWarning { message: string; file: string | null; line: number | null; box?: number[] }
export interface DrawingEntry {
  id: string; name: string; file: string | null; line: number | null;
  size: string; width: number; height: number; scale: string;
  pdf: string; dxf: string | null;
  /** Was die PDF-Seite vom Blatt zeigt, falls nicht genau das Papier. */
  pageBox: number[];
  views: DrawingView[]; dims: DrawingDim[]; warnings: DrawingWarning[];
  /** Zeitpunkt der PDF (ms), Modell oder Zeichnungsdatei neuer: veraltet. */
  built: number; stale: boolean;
  /** Mit Teilen, Achsen und Maßpunkten gebaut (Index ab Version 2)? Sonst kennt die App nur die Lage der Ansichten. */
  linked: boolean;
}
export interface DrawingFileError { file: string; line: number | null; message: string }
export interface DrawingList { drawings: DrawingEntry[]; errors: DrawingFileError[]; building: boolean }
export interface DrawingBuildResult extends DrawingList { ok: boolean; error?: string }

/** Ergebnis einer Auswertung (`soma analyze`, E58), Metadaten aus extras.soma_result der GLB. */
export interface ResultPart {
  name: string; group: string | null; area: number; critical: number; min?: number; max?: number;
  worst?: { value: number; at: number[] }; overlap?: number; contact?: number;
  /** Nur FEM: höchste Vergleichsspannung (MPa), größte Verschiebung (mm), Werkstoff. */
  stress?: { value: number; at: number[] }; displacement?: { value: number; at: number[] };
  /** Werkstoff. Querdehnzahl `nu` und Dichte (g/cm³) für den Bericht (E82), sie fehlen bei älteren Ergebnissen. */
  material?: { name: string; E: number; strength: number; nu?: number; density?: number; note?: string | null };
  /** Nur FEM mit Netzprüfung: höchste Spannung mit dem gröberen Netz und die Änderung zum feinen (0.2 = 20 %). */
  coarse?: { stress: number; change: number };
}
/** Randbedingung einer FEM-Studie (soma analyze fem): fest, Kraft oder Druck auf Flächen eines Teils. */
export interface FemBc {
  kind: 'fix' | 'force' | 'pressure'; part: string; label: string; area: number; at: number[];
  axes?: string; reaction?: number[]; total?: number[]; value?: number;
}
/** Teile, die sich berühren (E84): verklebt oder als Kontakt der Studie. Fläche in mm². */
export interface FemTouching { a: string; b: string; area: number; joint: 'bonded' | 'contact' | 'bolt'; friction: number | null }
/**
 * Kontaktpaar (E84): getragene Kraft (N), höchste Pressung (MPa), offene Fläche (mm², hebt ab) mit größtem Spalt (mm),
 * größter Gleitweg (mm), mit Reibung die Fläche, die an der Haftgrenze gleitet.
 */
export interface FemContact {
  a: string; b: string; friction: number; area: number; force: number; maxPressure: { value: number; at: number[] };
  openArea: number; maxGap: number; maxSlip: number; slideArea?: number;
}
/**
 * Vorgespannte Schraube (bolt()): Vorspannung und Kraft am Ende (N), Querkraft im Schaft (N), Zugspannung im
 * Spannungsquerschnitt (MPa), Auslastung der Streckgrenze aus Zug und Schub (1 = 100 %). `limit`: was die automatische
 * Vorspannung begrenzt hat ("screw" oder das Teil unter dem Kopf).
 */
export interface FemBolt {
  part: string; designation: string; grade: string; preload: number; auto: boolean; limit: string | null;
  force: number; shear: number; stress: number; utilization: number; engaged: string; at: number[];
}
export interface FemInfo {
  study: string; bcs: FemBc[]; applied: number[]; reaction: number[]; maxDisp: number; diag: number;
  /** `auto`: Die Studie gibt keine Netzgröße vor (fehlt bei älteren Ergebnissen). */
  mesh: { size: number; elements: number; dofs: number; solver: string; nodes?: number; auto?: boolean };
  /** Abweichung des Gleichgewichts (0.001 = 0.1 %), gröberes Netz der Prüfung, Schwerkraft (m/s², null: ohne). */
  balance?: number; coarse?: { size: number; elements: number } | null; gravity?: number[] | null;
  /** Berührende Teile und Kontaktpaare (E84, fehlen bei älteren Ergebnissen). */
  touching?: FemTouching[]; contacts?: FemContact[]; bolts?: FemBolt[];
}
export interface ResultMeta {
  id: string; kind: string; title: string; quantity: string; unit: string;
  /** Welche Seite des Grenzwerts kritisch ist. */
  bad: 'high' | 'low';
  threshold: number; range: [number, number];
  /** Werte in diesem Band gelten als Berührung, nicht als kritisch (Abstand). */
  neutral?: [number, number] | null;
  parts: ResultPart[]; summary: string; created: number; command: string[];
  /** Rechenzeit in Sekunden. */
  seconds?: number;
  /** Hinweise der Auswertung (FEM: Netzabhängigkeit, große Verformung, Werkstoff). */
  notes?: string[];
  fem?: FemInfo | null;
}
export interface ResultEntry extends ResultMeta { file: string; stale: boolean }

/** Auftrag an das unsichtbare Render-Fenster (E58). Die Dateien kommen als Inhalt mit, das Fenster liest selbst nichts. */
export interface RenderJob {
  id: number; kind: 'still' | 'sheet' | 'video'; width: number; height: number;
  view: string | null; at: number; grid: [number, number]; fps: number;
  /** Freie Blickrichtung (vom Modell zur Kamera) statt `view`, Teile oder Gruppen ausblenden, nur zeigen, einpassen, Zoom. */
  dir: [number, number, number] | null; hide: string[]; only: string[]; fit: string[]; zoom: number;
  model: ArrayBuffer; anim: ArrayBuffer | null; result: ArrayBuffer | null;
}
/** Antwort des Render-Fensters. Video: MP4, Untertitel (WebVTT) und eine Übersicht als PNG. */
export interface RenderOutput { ok: boolean; error?: string; warnings?: string[]; png?: ArrayBuffer; mp4?: ArrayBuffer; vtt?: string | null; sheet?: ArrayBuffer }
export interface RenderResult { ok: boolean; files: string[]; warnings: string[]; error?: string }
/** Meldung an das Hauptfenster: Bild oder Video fertig (auch auf Auftrag des Agenten). */
export interface RenderNotice extends RenderResult { kind: 'still' | 'sheet' | 'video'; byAgent: boolean }

export interface SomaApi {
  testMode: boolean;
  /** Die App beginnt auf der Startseite (E69). Im Testmodus öffnet der Hauptprozess gleich ein Modell, außer SOMA_TEST_START=home. */
  startsHome: boolean;
  project: {
    current(): 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;
    saveState(): Promise<SaveState>;
    save(saveAs?: boolean): Promise<SaveResult>;
    /** Öffnet eine Modelldatei (.soma, auch .zip, E79). */
    openZip(): Promise<OpenResult>;
    /** „Open folder“ (Ordner-Modus): Ordner wählen, Hinweis, was angelegt und geändert wird, dann öffnen. */
    openFolder(): Promise<OpenResult>;
    /** Das ganze Modell als ZIP exportieren (E79), ohne Snapshot. Die Modelldatei bleibt, wie sie ist. */
    exportZip(): Promise<ExportResult>;
    /** Neues Modell aus einem CadQuery-Skript (E100): Dateidialog, Import, erster Build. */
    createFromCadQuery(): Promise<CadQueryImportResult>;
    /** Schritte von createFromCadQuery nach dem Dateidialog, für die Ladeanzeige: `step` ist der laufende Schritt. */
    onCadQueryStep(cb: (s: { step: string; file: string }) => void): void;
    /** Das Modell als reines CadQuery-Skript (E100): eine .py, mit parts/ ein Ordner. */
    exportCadQuery(): Promise<ExportResult>;
    onSaveState(cb: (s: SaveState) => void): void;
    /** Zeigt die Modelldatei im Dateimanager (noch nicht gespeichert: den Arbeitsordner). */
    reveal(): Promise<void>;
    /** Pfad des Arbeitsordners in die Zwischenablage, für Agenten-Apps außerhalb der App (Claude Desktop, Codex-App). */
    copyPath(): Promise<FileOpResult>;
    /** Vorschaubild des offenen Modells für die Startseite (JPEG als Data-URL). */
    setThumb(dataUrl: string): Promise<void>;
    thumb(id: string): Promise<string | null>;
    /** Arbeitsordner eines Modells in den Papierkorb, nach Rückfrage. Nicht das gerade geöffnete. */
    remove(id: string): Promise<RemoveResult>;
    /**
     * Eine STEP-Datei des Projekts (.step, .stp) für den Viewer umwandeln, im Basismodus wie die Vorschau alter Stände.
     * Unveränderte Dateien kommen aus dem Cache. Fehler stehen in `error`.
     */
    viewFile(rel: string): Promise<FileViewResult>;
  };
  versions: {
    log(): Promise<GitLog>;
    preview(hash: string): Promise<PreviewResult>;
    restore(hash: string): Promise<RestoreResult>;
    onChanged(cb: () => void): void;
  };
  /** Nur im Testmodus (SOMA_TEST=1) vorhanden. */
  test?: {
    answers(a: unknown[]): Promise<void>; screenshot(file: string, rect?: { x: number; y: number; width: number; height: number }): Promise<{ width: number; height: number }>; bridge(): Promise<Record<string, string>>; close(): Promise<void>;
    /** Was die App in die Zwischenablage legen wollte (im Test bleibt die echte unberührt). */
    clipboard(): Promise<string>;
  };
  build: {
    run(): Promise<void>;
    cancel(): Promise<void>;
    setAuto(on: boolean): Promise<void>;
    status(): Promise<BuildStatus>;
    onStatus(cb: (s: BuildStatus) => void): void;
    /** `part` null = alle Bauteile ohne Referenzen. `mesh` gilt nur für Netzformate, bei anderen ignoriert. */
    export(format: string, part: string | null, mesh?: MeshExportOptions): Promise<ExportResult>;
  };
  fs: {
    list(): Promise<FileNode[]>;
    readText(rel: string): Promise<string>;
    readBinary(rel: string): Promise<ArrayBuffer>;
    onChanged(cb: () => void): void;
    /** Kopiert gezogene Dateien nach inputs/. Vorhandenes wird nie überschrieben. */
    importFiles(files: File[]): Promise<ImportResult>;
    /** Wie importFiles, die Dateien wählt der Nutzer im Dialog. null: abgebrochen. */
    importPick(): Promise<ImportResult | null>;
    /** Neue, leere Datei oder neuer Ordner in `parent` ('' = Projektordner). Vorhandenes wird nie überschrieben. */
    create(parent: string, name: string, dir: boolean): Promise<FileOpResult>;
    /** Benennt eine Datei oder einen Ordner im selben Ordner um. Vorhandenes wird nie überschrieben. */
    rename(rel: string, name: string): Promise<FileOpResult>;
    /** Fragt nach und verschiebt dann in den Papierkorb. Endgültig gelöscht wird nie. */
    trash(rel: string): Promise<FileOpResult>;
    /** Zeigt die Datei im Explorer ('' = Projektordner). */
    reveal(rel: string): Promise<FileOpResult>;
    /** Öffnet die Datei mit dem Standardprogramm des Systems. Ausführbares lehnt der Hauptprozess ab. */
    openExternal(rel: string): Promise<FileOpResult>;
    /** Legt ein PNG der Markierung in .soma/feedback/ ab. Vorhandenes wird nie überschrieben. */
    saveFeedback(png: Uint8Array): Promise<FeedbackResult>;
    /**
     * Schreibt eine Datei aus dem Editor, nur wenn sie auf der Platte noch `base` entspricht (sonst Konflikt).
     * `force` schreibt trotzdem und sichert vorher die Fassung auf der Platte. `projectId` schützt vor Schreiben ins falsche Modell.
     */
    writeText(projectId: string, rel: string, text: string, base: string | null, force?: boolean): Promise<WriteResult>;
    /** Legt einen Text als Sicherung in den App-Daten ab und gibt den Pfad zurück. */
    backupText(projectId: string, rel: string, text: string): Promise<string>;
    /** Anfragen des Hauptprozesses an den Editor beim Beenden: ungespeicherte Dateien nennen, speichern oder verwerfen. */
    onEditorRequest(cb: (action: 'status' | 'save' | 'discard') => Promise<{ dirty?: string[]; ok?: boolean }>): void;
  };
  /** DXF-Ansicht im Code-Panel (E80). `known`: Fingerabdruck des gezeigten Stands, bei gleicher Datei kommt nur `unchanged`. */
  dxf: { view(rel: string, known?: string | null): Promise<DxfResult> };
  term: {
    create(opts?: { command?: string; title?: string }): Promise<number>;
    write(id: number, data: string): void;
    resize(id: number, cols: number, rows: number): void;
    kill(id: number): void;
    onData(cb: (id: number, data: string) => void): void;
    onExit(cb: (id: number, code: number) => void): void;
  };
  agents: { detect(): Promise<AgentInfo[]> };
  /** Exakte Messung über den Python-Dienst (E9, E24). */
  measure: {
    query(source: MeasureSource, req: MeasureRequest): Promise<MeasureResponse>;
    /** Den Messdienst starten (cadquery laden), noch ohne Modell. Dauert beim ersten Mal einige Sekunden. */
    start(): Promise<MeasurePrepared>;
    /** Den Stand vorab in den Messdienst laden, damit der erste Klick nicht darauf wartet (große Baugruppen: Sekunden). */
    prepare(source: MeasureSource, build: string): Promise<MeasurePrepared>;
  };
  /** Parameter des Modells (`param()` im Code) und die Werte des Nutzers in parameters.json. */
  params: {
    state(): Promise<ParamState>;
    /** Wert des Nutzers setzen (null: zurück auf den Wert aus dem Code) und bauen. */
    set(values: Record<string, ParamValue | null>): Promise<ParamResult>;
    /** Alle Werte des Nutzers entfernen: Es gelten wieder die Werte aus dem Code. */
    resetAll(): Promise<ParamResult>;
  };
  /** Anleitung (E83): Text (der mitgelieferte Skill soma-app.md, null wenn er fehlt) und ein Bild daraus nach Dateiname. */
  help: { read(): Promise<string | null>; image(name: string): Promise<Uint8Array | null> };
  /** Skills des offenen Modells (E17): auflisten, Stufe wählen (E55). */
  skills: {
    list(): Promise<SkillInfo[]>;
    set(id: string, mode: SkillMode): Promise<SkillResult>;
    /** Einstellungen ändern, null setzt auf den Standard zurück. Die Kopie eines eingeschalteten Skills wird neu geschrieben. */
    configure(id: string, values: Record<string, SkillValue | null>): Promise<SkillResult>;
    /** Stufe für neue Modelle festlegen (für die ganze App, das offene Modell bleibt, wie es ist). */
    setDefault(id: string, mode: SkillMode): Promise<SkillResult>;
  };
  /** Bibliothek der Skills in den Einstellungen (E78): mitgelieferte und eigene, ohne offenes Modell. */
  library: {
    list(): Promise<LibraryState>;
    read(id: string): Promise<LibraryText>;
    /** Text prüfen, ohne zu speichern. */
    check(text: string): Promise<SkillCheck>;
    /** Speichern. `base`: der Text beim Laden, weicht die Datei davon ab, kommt sie vorher in die Sicherung. */
    save(id: string, text: string, base: string | null): Promise<LibraryResult>;
    /** Neuer eigener Skill mit dem Namen `title`, leer aus der Vorlage oder als Kopie von `from`. */
    create(title: string, from?: string): Promise<LibraryResult>;
    /** Eigenen Skill löschen oder bearbeiteten zurücksetzen. Die Datei kommt in die Sicherung. */
    remove(id: string): Promise<LibraryResult>;
    /** Markdown-Dateien wählen und als eigene Skills übernehmen. */
    import(): Promise<LibraryResult>;
    setDefault(id: string, mode: SkillMode): Promise<LibraryResult>;
    /** Datei eines eigenen Skills (oder ohne Kennung den Ordner) im Explorer zeigen. */
    reveal(id?: string): Promise<void>;
  };
  /** Einstellungen der App (E81), in settings.json. `set` ändert nur die genannten Werte. */
  settings: { get(): Promise<SettingsState>; set(patch: SettingsPatch): Promise<SettingsResult> };
  /** Speicherplatz der App-Daten (E81). */
  storage: {
    stats(): Promise<StorageStats>;
    /** Ordner eines Bereichs im Explorer öffnen (wird angelegt, falls er fehlt). */
    open(area: StorageArea): Promise<FileOpResult>;
    /** Vorschau-Cache leeren, nach Rückfrage. Die Vorschauen des offenen Modells bleiben. */
    clearPreviews(): Promise<StorageClear>;
  };
  /** Angaben für „About“ (E81). `copy` legt sie als Text in die Zwischenablage. */
  /** Der Viewer bekam keinen WebGL-Kontext. true: Die App startet mit Software-Rendering neu (nur Linux, einmal). */
  gpu: { webglFailed(): Promise<boolean> };
  about: { info(): Promise<AboutInfo>; copy(): Promise<FileOpResult> };
  /** Neueste Version auf GitHub, einmal je Sitzung gefragt. */
  updates: { check(): Promise<UpdateInfo> };
  /** Animationen (E58): Liste aus .soma/anim/index.json, bauen über `soma anim build`. */
  anim: {
    list(): Promise<AnimList>;
    /** `file` (animations/x.py) baut nur diese Datei, ohne alle. */
    build(file?: string): Promise<AnimBuildResult>;
    onChanged(cb: () => void): void;
  };
  /** Technische Zeichnungen (E76): Liste aus .soma/drawings/index.json, bauen über `soma drawing build`. */
  drawings: {
    list(): Promise<DrawingList>;
    /** `file` (drawings/x.py) baut nur diese Datei, ohne alle. */
    build(file?: string): Promise<DrawingBuildResult>;
    /** Exportieren mit Dateidialog: alle Blätter als eine PDF, je Blatt PDF/DXF/beides in einen Ordner, mit `sheet` (id) nur dieses Blatt. */
    export(what: 'set' | 'pdf' | 'dxf' | 'both', sheet?: string): Promise<ExportResult>;
    /** Index neu geschrieben, Zeichnungsdatei geändert oder Bauen begonnen. */
    onChanged(cb: () => void): void;
  };
  /** Ergebnisse von `soma analyze` (E58). */
  results: {
    list(): Promise<ResultEntry[]>;
    /** Dieselbe Auswertung noch einmal (mit den gespeicherten Angaben). */
    rerun(id: string): Promise<{ ok: boolean; error?: string }>;
  };
  /** Bilder und Videos über das Render-Fenster (E58). */
  render: {
    video(animId: string): Promise<RenderResult>;
    onProgress(cb: (fraction: number) => void): void;
    onNotice(cb: (n: RenderNotice) => void): void;
  };
  /**
   * Rückfrage mit Knöpfen, liefert den Index. Der letzte Knopf gilt als Abbrechen. Im Test über `test.answers` beantwortbar.
   * `onShow`: Der Renderer zeigt die Rückfragen selbst an (dunkel, im Stil der App), sonst nimmt der Hauptprozess den Dialog des Systems.
   */
  dialog: {
    choose(o: { title: string; message: string; detail?: string; buttons: string[] }): Promise<number>;
    onShow(cb: (o: { title: string; message: string; detail?: string; buttons: string[] }) => Promise<number>): void;
  };
  /** Öffnet eine Web-Adresse (http, https, mailto) im Browser des Systems. Andere Adressen lehnt der Hauptprozess ab. */
  openUrl(url: string): Promise<FileOpResult>;
  /** Text in die Zwischenablage (etwa „Send to agent“ für Agenten-Apps außerhalb der App). */
  copyText(text: string): Promise<FileOpResult>;
}

/** Schnittstelle des unsichtbaren Render-Fensters (E58, render-preload.ts). */
export interface RenderApi {
  onJob(cb: (job: RenderJob) => void): void;
  done(id: number, out: RenderOutput): void;
  progress(id: number, fraction: number): void;
  ready(): void;
}

declare global { interface Window { soma: SomaApi; somaRender: RenderApi } }