ml-time-graph 1.0.0 → 1.0.5

package/API_DESIGN.md

@@ -0,0 +1,1211 @@
+# MLTimeGraph — API-Referenz (v1.0.0)
+
+*Stand: v1.0.0 — erste npm-Veröffentlichung nach dem Cleanup. Eine API-Form, keine `@deprecated`-Pfade.*
+
+Dieses Dokument ist die **API-Referenz für die aktuelle Library-Form**: nested
+`SeriesStyle`-System, strukturiertes `FillSpec`-Modell (inkl. `outer`-Gate für
+klassifizierte Zonen), Statistik-Overlays (`movingMkt` / `movingAverage` /
+`stdDevBand` / `limits`), First-Class-Achsen, `GapsConfig` mit Auto-Detect +
+`bridge_line`-Mode, Theme-Runtime, sowie die Subpath-Module
+`ml-time-graph/analyze` und `ml-time-graph/interaction`.
+
+Praktische Beispiele leben in [USAGE.md](USAGE.md) und in der Demo-Galerie
+unter [`demos/`](demos/). Die Migrations-Historie ist als **Appendix** am
+Ende dieses Dokuments — als Begründungs-Kontext für Designentscheidungen.
+
+## Inhalt
+
+1. [Ziel der Library](#1-ziel-der-library)
+2. [Design-Prinzipien](#2-design-prinzipien)
+3. [Daten-Vertrag](#3-daten-vertrag)
+4. [Style-System (Serie)](#4-style-system-serie)
+5. [Fill-Modell](#5-fill-modell)
+6. [Achsen + Grid](#6-achsen--grid)
+7. [Gaps](#7-gaps)
+8. [Thresholds](#8-thresholds)
+9. [Annotationen (Marker, Highlights, Overlays, Bands)](#9-annotationen-marker-highlights-overlays-bands)
+10. [Statistik-Overlays (Moving Avg / MKT / Limits)](#10-statistik-overlays-moving-avg--mkt--limits)
+11. [Theme + Patterns (Modul-Struktur)](#11-theme--patterns-modul-struktur)
+12. [MLTimeGraphOptions — Top-Level-Form](#12-mltimegraphoptions--top-level-form)
+
+**Appendix:**
+
+A. [Migrations-Historie (v0.2 → v0.3 → Cleanup)](#a-migrations-historie-v02--v03--cleanup)
+B. [Polish-Backlog (post-v0.3)](#b-polish-backlog-post-v03)
+C. [Aufgelöste Design-Entscheidungen](#c-aufgelöste-design-entscheidungen)
+
+---
+
+## 1. Ziel der Library
+
+> **MLTimeGraph visualisiert Sensor-Messwerte über die Zeit.**
+>
+> - Mehrere Serien pro Chart, optional zwei Y-Achsen (links / rechts).
+> - Beliebige Kombination aus **Linie, Fläche, Punkten, Step** pro Serie —
+>   inkl. mehrerer übereinandergelegter Linien (z. B. Step + Catmull-Smooth)
+>   für dieselben Daten.
+> - Schwerpunkt: **Datenanalyse mit reichen Annotationen** (Marker, Highlights,
+>   Pfeile/Labels/Boxen in Datenkoordinaten, horizontale Annotation-Bänder).
+> - **Statistik-Overlays** auf Roh-Daten: Moving Average, Moving Mean Kinetic
+>   Temperature, Standardabweichungs-Band, Limit-Überschreitungen.
+> - **Hatching auf jeder gefüllten Fläche** (Fill-to-Threshold, Zonen-Fill,
+>   Min/Max/Avg-Fill, Gap-Fill, Threshold-Halbebene, Annotation-Band-Item) —
+>   11 vorgefertigte Muster siehe [Demo Hatch](demos/hatch.html).
+> - Renderer-agnostisch (`DrawCommand[]` → `Renderer.render()`).
+> - Keine Runtime-Dependencies. MIT mit Attribution.
+
+**Begleit-Module** (im selben Repo, eigene Subpath-Exports):
+
+- `ml-time-graph/analyze` — Analyse-Helfer (Aggregation, Downsampling,
+  Gap-Detection, MKT, StdDev, Limit-Statistik, Geometrie-Splits).
+  Kandidat für späteren Ausgliederungs-Schnitt zu `mlcanalyze` (separate
+  Library), sobald (a) das API stabil ist und (b) ein zweiter Konsument
+  auftaucht. Bis dahin one-repo.
+- `ml-time-graph/interaction` — optionale Interaktions-Helfer (Zoom,
+  Minimap, Tooltip). Die Chart selbst bleibt rein darstellend; wer
+  interagieren will, importiert diese Helfer dazu oder baut eigene.
+
+Was die Library **nicht** ist: kein Universal-Chart, kein Finanzchart (kein
+OHLC).
+
+---
+
+
+## 2. Design-Prinzipien
+
+Diese Prinzipien sind verbindlich für alle Entscheidungen unten.
+
+| # | Prinzip | Begründung |
+|---|---------|------------|
+| **P1** | **Eine Sache, ein Konzept.** Nur eine API für "fülle Fläche", nur eine für "Linie zeichnen", nur eine für "Gap konfigurieren". | Reduziert die zu lernende Oberfläche, verhindert Spec-Drift. |
+| **P2** | **Daten sind Daten.** Das Datenmodell trägt nur, was zum Zeichnen des **Werts an einer Zeit** nötig ist. Statistik, Limits, Domain-Kontext sind separate Layer. | Wiederverwendbarkeit, Testbarkeit, klare Verantwortung. |
+| **P3** | **Verschachtelte Styles statt flacher Properties.** `style.line.color` ist auffindbarer als `color` neben `lineWidth` neben `shadowColor`. | Bessere IDE-Completion, weniger "wo war das nochmal?". |
+| **P4** | **Defaults im Theme, nicht im Aufruf.** Wer keinen Style angibt, kriegt sinnvolle Werte aus dem Theme. Theme ist mutierbar pro Chart. | Konsistenz, schnelle Restyling. |
+| **P5** | **Strikte TypeScript-Typen.** Diskriminierte Unions wo immer möglich (`kind:` als Diskriminator), keine `any`, keine offenen `Record`-Typen für interne API. | Compiler-Sicherheit, weniger Laufzeitfehler. |
+| **P6** | **JSDoc auf jedem öffentlichen Member.** Was, optional Default, Beispiel. | Hover-Doku in jedem IDE. |
+| **P7** | **Max 250 Zeilen pro Datei.** | Lesbarkeit (Projekt-Style-Guide). |
+| **P8** | **Separable Begleit-Module.** Analyse + Interaktion sind eigenständige Unterverzeichnisse mit eigenem Barrel und eigenem Subpath-Export. Beide sind reine Add-ons — die Chart selbst funktioniert ohne sie. | Klarer Render-Kern, optionale Schwere, späterer Ausgliederungs-Schnitt ohne API-Bruch möglich. |
+| **P9** | **Kompositions statt Aufzählungs-Typen.** „Welche Darstellungsart" ist keine Enum-Frage (`seriesType: 'line' \| 'area' \| …`), sondern eine Frage *welche Style-Sub-Objekte gesetzt sind*. Linie + Fläche + Punkte gleichzeitig = einfach alle drei setzen. | Aus Anwendersicht naheliegender, beliebige Kombinationen ohne neue Enum-Werte, Renderer-Pipeline klar (jedes Style-Stück = ein Layer). |
+
+---
+
+## 3. Daten-Vertrag
+
+### 3.1 Roh-Daten
+
+```ts
+/** Ein Mess-Sample. `value: null` markiert eine Lücke — die Linie bricht dort. */
+export interface DataPoint {
+  /** Zeitstempel in ms seit Epoch. */
+  time: number;
+  /** Mess-Wert. `null` = Gap. */
+  value: number | null;
+  /** Optionaler punktbezogener Annotationstext (z. B. Event-Marker). */
+  annotation?: string;
+  /**
+   * Synthetischer Punkt — keine echte Messung. Wird automatisch von der
+   * Library auf interpoliert eingefügten Punkten gesetzt (Threshold-Schnitte,
+   * Gap-Ränder), kann aber auch manuell verwendet werden, wenn man eigene
+   * berechnete Werte einbringt (z. B. eine Trendlinie auf zwischengeschobenen
+   * Stützstellen).
+   *
+   * Renderer behandeln `synthetic: true` so:
+   * - **Marker-Renderer**: kein Punkt-Marker (auch bei `style.markers.type !== 'none'`).
+   * - **Tooltip**: nicht hit-testbar — der Tooltip snapt nur auf echte Messungen.
+   * - **Werte-Tabelle**: ausgeblendet (kein "Phantom-Eintrag" in der Values-Tab).
+   *
+   * Default `undefined` = echte Messung.
+   */
+  synthetic?: boolean;
+}
+```
+
+**Neu** gegenüber heute: das optionale `synthetic`-Flag. Begründung: der
+`SeriesProcessor` setzt heute schon Interpolations-Punkte an Threshold-Schnitten
+und Gap-Rändern, damit Zonen-Fills exakt an der Schwelle stoppen. Diese
+Punkte würden bei aktivierten Markern fälschlich als "Datenpunkt" auftauchen.
+Das Flag erlaubt es, sie sauber zu ignorieren — und gleichzeitig macht es das
+Konzept "berechneter / eingefügter Punkt" für Konsumenten verfügbar.
+
+Daten-Modell-Invariante: **`synthetic` betrifft nur das Rendering, nie die
+Skalen-Berechnung** (ein synthetischer Punkt zählt für Min/Max der Y-Achse).
+
+### 3.2 Aggregat (Slim Core + spezialisierte Untertypen)
+
+```ts
+/** Aggregierter Slot — min/max/avg/count über ein Zeitfenster. */
+export interface AggregatedPoint {
+  /** Slot-Start in ms. */
+  time: number;
+  /** Minimum im Slot. `null` = kein Sample im Slot (Gap). */
+  min: number | null;
+  /** Maximum im Slot. `null` = Gap. */
+  max: number | null;
+  /** Durchschnitt im Slot. `null` = Gap. */
+  avg: number | null;
+  /** Anzahl der Roh-Samples im Slot (0 = Gap). */
+  count: number;
+}
+```
+
+**Vom heutigen Stand entfernt:** `mkt`, `deltaMkt`, `stdDev`, `minutesAboveHigh`,
+`minutesBelowLow`. Die wandern in **spezialisierte Aggregat-Typen** — Interfaces
+die `AggregatedPoint` strukturell erweitern:
+
+```ts
+/** Rolling Mean Kinetic Temperature je Zeitslot. */
+export interface MktPoint extends AggregatedPoint {
+  /** MKT-Wert (USP <1079.2>) für diesen Slot. `null` = Gap. */
+  mkt: number | null;
+  /** Delta zum vorherigen Slot (optional). */
+  deltaMkt?: number | null;
+}
+
+/** Aggregat mit Standardabweichung. */
+export interface StdDevPoint extends AggregatedPoint {
+  /** Standardabweichung der Samples im Slot. `null` = Gap. */
+  stdDev: number | null;
+}
+
+/** Aggregat mit Limit-Überschreitungs-Statistik. */
+export interface LimitStatsPoint extends AggregatedPoint {
+  /** Anzahl Minuten oberhalb des oberen Limits im Slot. */
+  minutesAboveHigh?: number | null;
+  /** Anzahl Minuten unterhalb des unteren Limits im Slot. */
+  minutesBelowLow?: number | null;
+}
+```
+
+**Warum strukturell statt diskriminiert** (siehe Q1-Entscheidung in Appendix D):
+
+- Strukturell heisst: `MktPoint[]` ist ein gültiger `AggregatedPoint[]` —
+  jedes Standard-Aggregat-Rendering (Band, Min/Max/Avg) funktioniert automatisch.
+- Spezialisierte Views/Overlays können auf die zusätzlichen Felder zugreifen,
+  indem sie auf den Untertyp casten oder per `'mkt' in point`-Guard fragen.
+- Kein extra `kind`-Diskriminator, weniger Boilerplate für Konsumenten.
+
+**Zwei klare Wege** für Statistik-Werte:
+
+| Use case | Was tun |
+|----------|---------|
+| Ich habe **Roh-Daten** und will im Chart eine Trend-/Stat-Linie obendrauf | `overlays: [{ kind: 'movingAverage', window, … }]` — Library rechnet, siehe §10 |
+| Ich habe **fertig berechnete MKT-Slots** und will sie als primäre Daten zeigen | `series: [{ data: { points: mktSlots /* MktPoint[] */ }, view: 'minmaxavg' }]` — Library nimmt die Werte wie sie sind |
+
+Beides funktioniert nebeneinander; die Library zwingt dich nicht in eine Form.
+
+### 3.3 Eingabe-Pfade — wie man Daten reingibt
+
+Flach, strukturell:
+
+```ts
+/**
+ * Ein Punkt-Array. Strukturell erkannt:
+ * - hat `value`  → Roh-Datenpunkt(e) → DataPoint[]
+ * - hat `min/max/avg` → Aggregat → AggregatedPoint[] (oder spezialisierter Untertyp)
+ */
+export type SeriesPoints = DataPoint[] | AggregatedPoint[];
+
+export interface Series {
+  name: string;
+  /** Die Daten — strukturell erkannt. */
+  points: SeriesPoints;
+  style?: SeriesStyle;
+  // …
+}
+```
+
+Konsumiert wird das so:
+
+```ts
+new MLTimeGraph({
+  series: [
+    {
+      name: 'Temperature',
+      points: rawTemperaturePoints,                              // DataPoint[]
+      style: { /* … */ },
+    },
+    {
+      name: 'Temperature (hourly avg)',
+      points: aggregateBySlot(rawTemperaturePoints, 'hourly'),   // AggregatedPoint[]
+      view: 'minmaxavg',
+      style: { /* … */ },
+    },
+    {
+      name: 'MKT (rolling 7d)',
+      points: rollingMkt(rawTemperaturePoints, 7 * 24 * 3_600_000), // MktPoint[]
+      style: { line: { color: '#7c3aed' } },
+    },
+  ],
+});
+```
+
+Die Library erkennt den Punkt-Typ strukturell (`'min' in points[0]` →
+Aggregat, sonst Roh). Spezialisierte Aggregat-Typen wie `MktPoint` werden
+für Standard-Rendering wie `AggregatedPoint` behandelt — Views/Overlays
+können bei Bedarf auf die Extra-Felder zugreifen.
+
+**Implikation für Phase 4** (siehe Appendix A): `TimeSeries` und `AggregatedSeries`
+gehen weg, eine einzige `Series`-Form bleibt — bis dahin laufen die alten
+Aliase parallel.
+
+### 3.4 Helfer
+
+```ts
+import { aggregateBySlot, downsample, detectGaps, parseSeries } from 'ml-time-graph';
+
+aggregateBySlot(raw, 'hourly');        // DataPoint[] → AggregatedPoint[]
+downsample(raw, 2000);                 // LTTB
+detectGaps(raw, minGapMs);             // automatische Gap-Detektion
+parseSeries(json);                     // JSON → DataPoint[]
+```
+
+Diese sind unverändert und bleiben das einzige offizielle Helfer-Set.
+
+---
+
+## 4. Style-System (Serie)
+
+### 4.1 Series-Definition
+
+```ts
+export interface Series {
+  /** Anzeige-Name (Legende, Tooltip). */
+  name: string;
+
+  /**
+   * Die Mess-Daten. Strukturell erkannt:
+   * - Roh: `DataPoint[]` (Punkt hat `value`)
+   * - Aggregat: `AggregatedPoint[]` oder Untertyp (`MktPoint[]`, `StdDevPoint[]`, …)
+   *   (Punkt hat `min`/`max`/`avg`)
+   */
+  points: SeriesPoints;
+
+  /**
+   * Visuelles Styling. Welche Sub-Objekte gesetzt sind, entscheidet was
+   * dargestellt wird: `line` → Linie, `fill` → Fläche, `markers` → Punkte.
+   * Beliebige Kombination. Alle weglassen = unsichtbar (kein gültiger Zustand).
+   * Defaults aus dem Theme.
+   */
+  style?: SeriesStyle;
+
+  /** Welche Y-Achse: 0 = links, 1 = rechts. Default 0. */
+  axis?: 0 | 1;
+
+  /** Optionale Enum-Map (numerischer Wert → Label) für kategoriale Sensoren. */
+  enumMap?: Record<number, string>;
+
+  /**
+   * Wie eine aggregierte Serie dargestellt wird. Nur bei Aggregat-Punkten.
+   * 'band' = gefülltes Rechteck min→max pro Slot, optional + avg-Linie.
+   * 'minmaxavg' = drei Linien (min, max, avg) + optionale Fills.
+   * Default: 'minmaxavg'.
+   */
+  view?: 'band' | 'minmaxavg';
+
+  /** Optionale Statistik-Overlays (siehe §10). */
+  overlays?: SeriesOverlay[];
+
+  /** Stabile id für DOM-Selektoren. Auto-generiert, falls leer. */
+  id?: string;
+}
+```
+
+**Kein `seriesType`-Enum.** Stattdessen Komposition durch Style-Sub-Objekte
+(Prinzip P9):
+
+| Was du willst | Style |
+|---------------|-------|
+| Nur Linie | `{ line: { color: '#4285f4' } }` |
+| Nur Fläche (Area) | `{ line: false, fill: '#4285f422' }` |
+| Nur Punkte | `{ line: false, markers: { type: 'circle' } }` |
+| Linie + Fläche | `{ line: { color: '#4285f4' }, fill: '#4285f422' }` |
+| Linie + Punkte | `{ line: {...}, markers: { type: 'circle' } }` |
+| Linie + Fläche + Punkte | alle drei Sub-Objekte setzen |
+| Step + Catmull-Smooth gleichzeitig | `line: [{ shape: 'step', color: '#999', width: 1 }, { shape: 'line', smoothing: true, color: '#3b82f6' }]` |
+
+`line: LineStyle[]` legt mehrere Linien durch dieselben Punkte — Reihenfolge =
+Z-Reihenfolge. Saubere Lösung für „Schritt-Daten plus geglättete Trendlinie"
+ohne die Daten zu duplizieren.
+
+### 4.2 `SeriesStyle`
+
+```ts
+export interface SeriesStyle {
+  /**
+   * Linien-Stil. Drei Formen:
+   *   LineStyle       → eine Linie
+   *   LineStyle[]     → mehrere übereinander (z. B. Step + Catmull-Smooth)
+   *   false           → keine Linie zeichnen
+   * Default: eine Linie mit Theme-Defaults.
+   */
+  line?: LineStyle | LineStyle[] | false;
+
+  /** Flächen-Stil (siehe §5). */
+  fill?: FillSpec;
+
+  /** Punkt-Marker auf den Samples. */
+  markers?: MarkerStyle;
+
+  /** Drop-Shadow für Linie und Punkte. */
+  shadow?: ShadowStyle;
+
+  /** Pro-Serie Override für Gap-Darstellung (siehe §7). */
+  gap?: GapStyle;
+}
+
+export interface LineStyle {
+  /** Stroke-Farbe (Hex / rgba). */
+  color?: string;
+  /** Strichbreite in px. Default Theme-`strokeWidth`. */
+  width?: number;
+  /** Strich-Muster. Default 'solid'. */
+  style?: LineVariant;
+  /** Catmull-Rom-Glättung. Default false. */
+  smoothing?: boolean;
+  /** Linienform — 'line' (Default) oder 'step' (Treppe). */
+  shape?: 'line' | 'step';
+  /** Max. Zeitabstand (ms) zwischen Punkten, bevor die Linie bricht. 0 = aus. */
+  gapThreshold?: number;
+  /** Deckkraft 0..1 (z. B. um eine darunterliegende Step-Linie scheinen zu lassen). */
+  opacity?: number;
+}
+
+/** Alle Strich-Varianten (Quelle: theme.ts). */
+export type LineVariant =
+  | 'solid'
+  | 'dotted'
+  | 'sparse-dots'
+  | 'dashed'
+  | 'long-dash'
+  | 'dense-dash'
+  | 'dash-dot'
+  | 'dash-dot-dot'
+  | 'loose-dash';
+
+export interface MarkerStyle {
+  /** Marker-Shape (Default 'none'). */
+  type?: PointStyleType;
+  /** Größe (Radius oder Halb-Breite) in px. */
+  size?: number;
+  /** Outline-Farbe. */
+  stroke?: string;
+  /** Füll-Farbe (für gefüllte Shapes). */
+  fill?: string;
+  /** Strichbreite des Outlines. */
+  strokeWidth?: number;
+  /** Marker nur zeigen, wenn die Serie ≤ n Samples hat (Anti-Clutter). */
+  threshold?: number;
+}
+
+/** Alle Marker-Shapes (Quelle: theme.ts — 13 Varianten). */
+export type PointStyleType =
+  | 'none'
+  | 'circle'           // gefüllter Kreis
+  | 'cross'            // zwei diagonale Linien
+  | 'square'           // gefülltes Quadrat
+  | 'diamond'          // gedrehtes Quadrat
+  | 'triangle'         // Dreieck (Spitze oben)
+  | 'triangle-down'    // Dreieck (Spitze unten)
+  | 'star'             // 5-zackiger Stern
+  | 'arrow'            // Chevron nach oben
+  | 'plus'             // Plus-Zeichen
+  | 'hexagon'          // Sechseck
+  | 'hourglass'        // Sanduhr-Form
+  | 'line-horizontal'; // horizontaler Strich
+
+export interface ShadowStyle {
+  color?: string;
+  blur?: number;
+  offsetX?: number;
+  offsetY?: number;
+}
+```
+
+**Entfernt** gegenüber heute:
+
+- `dashed: boolean` (nur noch `line.style = 'dashed'`).
+- Separate `lineWidth`, `smoothing`, `pointStyle`, `pointSize`, `shadowColor/Blur/OffsetX/OffsetY` auf der Serie — alle in `style.{line,markers,shadow}` umgezogen.
+
+---
+
+## 5. Fill-Modell
+
+**Das zentrale Aufräum-Stück.** Eine Fill-Beschreibung, mehrere Geometrie-Ziele.
+
+### 5.1 `FillStyle` — die Form
+
+```ts
+/**
+ * Eine Füllung. Drei Formen, klar diskriminiert:
+ *
+ *   string                                 // einfache Farbe ('#ef444433' oder 'rgba(…)')
+ *   { color: string }                      // explizite Farbe, sonst gleich
+ *   { color: string, hatch: HatchVariant,  // Farbe + Hatch (mit eigener Linien-Farbe)
+ *     hatchColor?: string, hatchWidth?: number }
+ *
+ * Wo gefüllt wird, beschreibt `region` (siehe 6.2) — nicht `FillStyle` selbst.
+ */
+export type FillStyle =
+  | string
+  | { color: string; hatch?: HatchVariant; hatchColor?: string; hatchWidth?: number };
+```
+
+Das bildet exakt deine Anforderung ab: *"farbe, oder farbe+hatching(+farbe)"*.
+
+### 5.2 Wo gefüllt wird — `FillRegion`
+
+```ts
+/**
+ * Eine Füllungs-Region. `from` und `to` definieren das Y-Intervall;
+ * der X-Bereich ist immer die Serie.
+ */
+export interface FillRegion {
+  /** Untere Grenze. Default 'chartBottom'. */
+  from?: FillBound;
+  /** Obere Grenze. Default 'series' (die Linie selbst). */
+  to?: FillBound;
+  /** Die Füllung. */
+  fill: FillStyle;
+  /** Nur an dieser Seite des Übergangs zwischen `from`/`to` füllen. */
+  side?: 'above' | 'below';
+}
+
+export type FillBound =
+  | 'series'                              // die Linie selbst
+  | 'chartTop' | 'chartBottom'            // Plot-Kanten
+  | { threshold: string }                 // benannter Threshold (siehe §8)
+  | { value: number };                    // fester Wert
+```
+
+### 5.3 Wie `SeriesStyle.fill` aussieht
+
+```ts
+export type FillSpec =
+  // Häufiger Fall: durchgehende Füllung vom Plot-Boden bis zur Linie
+  | FillStyle
+  // Erweitert: eine oder mehrere Regionen
+  | { regions: FillRegion[] };
+```
+
+### 5.4 Beispiele — die häufigen Fälle
+
+Alle drei Threshold-bezogenen Anwendungsfälle, die im Hatch-Demo vorkommen,
+plus die Brücke zur heutigen API:
+
+**A. „Werte oberhalb eines Werts hervorheben"** — der Klassiker.
+
+```ts
+thresholds: [{ name: 'warn', value: 22 }],
+series: [{
+  // …
+  style: {
+    line: { color: '#ef4444' },
+    fill: { regions: [{
+      from: { threshold: 'warn' },
+      to: 'series',          // bis hoch zur Linie
+      side: 'above',         // nur wo die Linie über 'warn' liegt
+      fill: { color: '#ef444433', hatch: 'crosshatch' },
+    }] },
+  },
+}]
+```
+
+**B. „Bereich zwischen zwei Thresholds einfärben"** — z. B. den "OK"-Korridor
+zwischen low und high markieren, oder umgekehrt einen Warnbereich.
+
+```ts
+thresholds: [
+  { name: 'low',  value: 18 },
+  { name: 'high', value: 26 },
+],
+series: [{
+  // …
+  style: {
+    line: { color: '#3b82f6' },
+    fill: { regions: [{
+      from: { threshold: 'low' },
+      to:   { threshold: 'high' },
+      fill: { color: '#22c55e22', hatch: 'dots' },
+    }] },
+  },
+}]
+```
+
+Mit `from` und `to` als Threshold-Referenzen ist der Korridor zwischen zwei
+benannten Schwellen eine Zeile.
+
+**C. „Zonen-Fill (mehrere Bereiche, je eigene Farbe + Hatch)"** — der
+Multi-Zone-Fall aus dem Hatch-Demo.
+
+```ts
+thresholds: [
+  { name: 'cold', value: 10 },
+  { name: 'norm', value: 18 },
+  { name: 'hot',  value: 24 },
+],
+series: [{
+  // …
+  style: {
+    line: { color: '#2c0a0a', smoothing: true },
+    fill: { regions: [
+      { to: { threshold: 'cold' },                              fill: { color: '#60a5fa33', hatch: 'classic-diagonal' } },
+      { from: { threshold: 'cold' }, to: { threshold: 'norm' }, fill: { color: '#22c55e33', hatch: 'crosshatch' } },
+      { from: { threshold: 'norm' }, to: { threshold: 'hot'  }, fill: { color: '#fbbf2433', hatch: 'dots' } },
+      { from: { threshold: 'hot'  },                            fill: { color: '#ef444433', hatch: 'waves' } },
+    ] },
+  },
+}]
+```
+
+Mit dem Helper (§11, Q9 entschieden: Haupt-Barrel):
+
+```ts
+import { fillBetweenThresholds } from 'ml-time-graph';
+
+style: {
+  fill: fillBetweenThresholds({
+    thresholds: ['cold', 'norm', 'hot'],
+    colors:     ['#60a5fa33', '#22c55e33', '#fbbf2433', '#ef444433'],
+    hatches:    ['classic-diagonal', 'crosshatch', 'dots', 'waves'],
+  }),
+}
+```
+
+Ein Helper kann den Threshold-Zonen-Fall kürzer schreiben:
+
+```ts
+import { fillBetweenThresholds } from 'ml-time-graph';
+
+fill: fillBetweenThresholds({
+  thresholds: ['warn', 'crit'],
+  colors: ['#22c55e22', '#fbbf2433', '#ef444433'],
+  hatches: [undefined, 'dots', 'crosshatch'],
+}),
+```
+
+→ liefert eine `{ regions: [...] }`-Spec zurück. Die Library selbst kennt nur
+das `regions`-Konzept; `fillBetweenThresholds` ist syntaktischer Zucker.
+
+---
+
+## 6. Achsen + Grid
+
+`axisLabels` und `grid` werden zu einem zusammenhängenden `axes`-Objekt.
+
+```ts
+export interface MLTimeGraphOptions {
+  axes?: {
+    x?:     XAxisConfig;
+    left?:  YAxisConfig;
+    right?: YAxisConfig;
+  };
+  // …
+}
+
+export interface YAxisConfig {
+  /** Achsen-Beschriftung (rotiert neben der Achse). */
+  label?: string;
+  /** Override für den Wertebereich. Default: automatisch. */
+  domain?: [number, number] | 'auto';
+  /** Wert-Formatter für Tick-Labels. */
+  format?: (value: number) => string;
+  /** Tick-Konfiguration. */
+  ticks?: TickConfig;
+  /** Grid-Linien-Stil. */
+  grid?: GridStyle;
+  /** Achsen-Linie + Tick-Stroke-Stil. */
+  axis?: AxisStyle;
+  /** Beschriftungs-Stil. */
+  labels?: { color?: string; fontSize?: number };
+}
+
+export interface XAxisConfig {
+  label?: string;
+  /** Tick-Formatter — bekommt das Date. Default: i18n via `locale`. */
+  format?: (d: Date) => string;
+  ticks?: TickConfig;
+  grid?: GridStyle;
+  axis?: AxisStyle;
+  labels?: { color?: string; fontSize?: number };
+}
+
+export interface TickConfig {
+  /** Zielanzahl der Major-Ticks. */
+  major?: number;
+  /** Wie viele Minor-Ticks zwischen zwei Major-Ticks (Default 0 = aus). */
+  minor?: number;
+  /** Tick-Länge in px. */
+  size?: number;
+}
+
+export interface GridStyle {
+  /** Major-Grid: durchgehende Linien an den Major-Ticks. */
+  major?: { color?: string; width?: number; style?: LineVariant; opacity?: number } | false;
+  /** Minor-Grid (Default: keiner). */
+  minor?: { color?: string; width?: number; style?: LineVariant; opacity?: number } | false;
+}
+
+export interface AxisStyle {
+  /** Farbe der Achsen-Linie + Ticks. */
+  color?: string;
+  /** Strichbreite. */
+  width?: number;
+}
+```
+
+Damit fällt das alte `axisLabels` weg, und `grid: GridOptions` wird zu
+`axes.{x|left|right}.grid`.
+
+---
+
+## 7. Gaps
+
+Gap-Logik konsolidiert zu **einem** Pfad mit klarer Hierarchie:
+
+1. **Default**: Punkte mit `value: null` brechen die Linie automatisch.
+2. **Auto-Detect** (`gaps: { autoDetect, minGapMs }`) erzeugt Gap-Regionen aus
+   den Zeitabständen.
+3. **Manuelle Gaps** (`gaps: { regions: [{ startTime, endTime, label, … }] }`)
+   werden zusätzlich gezeichnet.
+4. **Per-Serie-Style** (`series.style.gap`) übersteuert das chart-weite Aussehen
+   nur für diese Serie.
+
+```ts
+export interface GapsConfig {
+  /** Automatisch erkennen anhand des Zeitabstands. Default true. */
+  autoDetect?: boolean;
+  /** Min. Zeitabstand für Auto-Detect in ms. Default 60000. */
+  minGapMs?: number;
+  /** Manuell deklarierte Gap-Regionen. */
+  regions?: GapRegion[];
+  /** Default-Style für alle Gaps. */
+  style?: GapStyle;
+}
+
+export interface GapRegion {
+  startTime: number;
+  endTime: number;
+  label?: string;
+  /** Override des Default-Styles. */
+  style?: GapStyle;
+}
+
+export interface GapStyle {
+  /** Wie der Gap-Bereich dargestellt wird. */
+  display?: 'empty' | 'dashed_border' | 'filled';
+  /** Hintergrund-Fill (nur bei display='filled'). */
+  fill?: FillStyle;
+  /** Opacity. Default 0.15. */
+  opacity?: number;
+  /** Label-Konfiguration. */
+  label?: GapLabel;
+}
+
+export interface GapLabel {
+  /** Vertikale Position. Default 'middle'. */
+  baseline?: 'above' | 'middle' | 'below';
+  /** Rotation in Grad. Default 0. */
+  rotate?: number;
+  /** Schriftfarbe. */
+  color?: string;
+  /** Schriftgrösse. */
+  fontSize?: number;
+}
+
+// Auf der Serie: nur Override-Slot
+export interface SeriesStyle {
+  // …
+  gap?: GapStyle;
+}
+```
+
+Die heutigen 6 `gap*`-Properties auf `TimeSeries` (`gapFill`, `gapFillOpacity`,
+`gapLabel`, `gapLabelBaseline`, `gapLabelRotate`, `gapFontFill`) kollabieren zu
+**einem** `style.gap`-Objekt mit den klar benennbaren Sub-Feldern oben.
+
+---
+
+## 8. Thresholds
+
+`Threshold` bleibt im Konzept gleich (benannter Wert, referenzierbar), aber
+der Fill wird ans neue `FillStyle` angeglichen.
+
+```ts
+export interface Threshold {
+  /** Eindeutiger Name, mit dem Serien diese Grenze referenzieren. */
+  name: string;
+  /** Wert. */
+  value: number;
+  /** Zugehörige Y-Achse. Default 0. */
+  axis?: 0 | 1;
+  /** Linie-Stil (`false` = keine Linie zeichnen, nur als Referenz). */
+  line?: LineStyle | false;
+  /** Halb-Ebene füllen. */
+  halfPlane?: { side: 'above' | 'below'; fill: FillStyle; opacity?: number };
+  /** Label. */
+  label?: ThresholdLabelConfig | false;
+  /** Drop-Shadow. */
+  shadow?: ShadowStyle;
+  id?: string;
+}
+
+export interface ThresholdLabelConfig {
+  text?: string;
+  position?: 'left' | 'right' | 'above' | 'below' | 'center';
+  rotate?: number;
+  baseline?: 'top' | 'middle' | 'bottom';
+  color?: string;
+  fontSize?: number;
+}
+```
+
+Auf der Serie:
+
+```ts
+export interface Series {
+  // …
+  /** Linie pro Threshold-Zone einfärben. */
+  colorByThresholds?: string[];
+}
+```
+
+---
+
+## 9. Annotationen (Marker, Highlights, Overlays, Bands)
+
+Bleibt im Wesentlichen wie heute — die API ist hier bereits sauber. Kleinere
+Anpassungen für Konsistenz:
+
+### 9.1 `Marker`
+
+```ts
+export interface Marker {
+  time: number;
+  value?: number;
+  label?: string;
+  /** Stil-Block (statt flacher color/pointStyle/…-Felder). */
+  style?: { color?: string; point?: PointStyleType; size?: number; line?: 'full' | 'to-value' | 'to-top' };
+  /** Ziel-Serie für 'to-value' / 'to-top'. */
+  seriesIndex?: number;
+}
+```
+
+### 9.2 `Highlight` — unverändert
+
+`Highlight` ist bereits in Ordnung (inkl. `labelPosition: 'above' | 'top' | …`).
+
+### 9.3 Freie Overlays — `Annotation`
+
+`Annotation` (`line | arrow | rect | point | label` in Datenkoordinaten) bleibt
+strukturell gleich. `rect` kriegt — wie heute — optional `hatch`.
+
+### 9.4 Annotation-Bands (horizontale Streifen)
+
+`AnnotationBandConfig` ist bereits sauber (`name`, `height`, `spacing`, `items`).
+Nur die Item-Properties werden ans neue `FillStyle` angepasst:
+
+```ts
+export interface AnnotationBandItem {
+  startTime: number;
+  endTime: number;
+  fill?: FillStyle;          // statt fill + hatch separat
+  label?: { text: string; baseline?: 'top' | 'middle' | 'bottom'; color?: string; fontSize?: number };
+  stroke?: { color: string; width: number };
+}
+```
+
+---
+
+## 10. Statistik-Overlays (Moving Avg / MKT / StdDev)
+
+Statt Stat-Werte ins Datenmodell einzubacken (`AggregatedPoint.mkt`,
+`AggregatedPoint.stdDev`), werden sie als **Overlays** deklariert und vom
+`SeriesProcessor` zur Render-Zeit aus den Roh-/Aggregat-Daten berechnet.
+
+```ts
+export interface Series {
+  // …
+  overlays?: SeriesOverlay[];
+}
+
+export type SeriesOverlay =
+  | { kind: 'movingAverage'; window: number; type?: 'simple' | 'exponential'; style?: SeriesStyle }
+  | { kind: 'movingMkt';     window: number; activationEnergy?: number;       style?: SeriesStyle }
+  | { kind: 'stdDevBand';    multiplier?: number;                              style?: SeriesStyle }
+  | { kind: 'limits';        low?: number; high?: number;                      style?: SeriesStyle };
+```
+
+Beispiel:
+
+```ts
+const tempSeries: Series = {
+  name: 'Temperature',
+  data: { kind: 'raw', points: rawTemp },
+  style: { line: { color: '#4285f4' } },
+  overlays: [
+    { kind: 'movingAverage', window: 60_000, style: { line: { color: '#fbbf24', style: 'dashed' } } },
+    { kind: 'stdDevBand', multiplier: 2, style: { fill: '#4285f422' } },
+  ],
+};
+```
+
+Statt:
+
+```ts
+// heute — Stats müssten vorgängig in AggregatedPoint.stdDev gerechnet sein
+// und werden dann implizit irgendwo gerendert
+```
+
+Vorteil: die Roh-Daten bleiben unberührt, Overlays sind komponierbar,
+sie haben ihren eigenen Style-Block und tauchen automatisch in der Legende auf.
+
+**Bestehende + neue Helfer wandern alle in `src/analyze/`** (Subpath-Export
+`ml-time-graph/analyze`, siehe §11). Dort liegen sie als pur funktionale
+Module — `(input, opts) => result` — ohne Render-Abhängigkeit, damit sie
+isoliert testbar sind und später als `mlcanalyze` ausziehen können.
+
+| Datei | Inhalt |
+|-------|--------|
+| `src/analyze/aggregator.ts` | `aggregateBySlot`, `downsample` (LTTB), `detectGaps` — heute in `src/data/aggregator.ts` |
+| `src/analyze/processor.ts` | Interpolation, `getRuns`, `splitByBoundaries`, `splitByThreshold` — heute in `src/data/series_processor.ts` |
+| `src/analyze/moving_avg.ts` | Simple + Exponential — heute in `src/statistics/moving_avg.ts` |
+| `src/analyze/stats.ts` | `StatsAggregator.compute()` — heute in `src/statistics/stats.ts` |
+| `src/analyze/mkt.ts` | **NEU.** Mean Kinetic Temperature mit `activationEnergy` (Default 83144, USP <1079.2>) |
+| `src/analyze/std_dev.ts` | **NEU.** Standardabweichungs-Band |
+| `src/analyze/limits.ts` | **NEU.** Aus `{ low, high }` → "Minuten ausserhalb"-Statistik (bisher `AggregatedPoint.minutesAboveHigh/Below`) |
+| `src/analyze/index.ts` | Barrel-Export — die öffentliche `ml-time-graph/analyze`-Oberfläche |
+
+`src/statistics/stats_overlay.ts` (der Render-Layer für Stats) **bleibt** unter
+`src/series/` — das ist die Render-Seite, nicht Analyse.
+
+Beispiel-Import:
+
+```ts
+import { aggregateBySlot, mkt, stdDev } from 'ml-time-graph/analyze';
+// Daten transformieren BEVOR sie an die Chart gehen, falls man die
+// Berechnung nicht der Chart überlassen will:
+const hourly = aggregateBySlot(raw, 'hourly');
+```
+
+Die Chart kann beides: entweder bereits berechnete Werte zeigen, oder die
+Berechnung intern per `overlays:` selbst anstoßen.
+
+---
+
+## 11. Modul-Struktur (Render-Kern + Begleit-Module)
+
+```
+src/
+├── MLTimeGraph.ts                  // Facade
+├── options.ts                      // MLTimeGraphOptions, LegendOptions, …
+├── index.ts                        // public barrel: ml-time-graph
+│
+├── core/                           // Skalen, Layout, Geometrie-Basics
+│   ├── layout.ts
+│   ├── scale.ts
+│   └── clip.ts
+│
+├── theme/                          // ⟵ aufgespalten aus theme.ts (542 LoC)
+│   ├── defaults.ts                 // theme-Objekt (Farben, Default-Sizes)
+│   └── palette.ts                  // Farb-Palette
+│
+├── patterns/                       // SVG-Pattern-Generatoren
+│   ├── hatch.ts                    // HatchVariant + getHatch()
+│   ├── line.ts                     // LineVariant + getLineStyle()
+│   └── points.ts                   // PointStyleType-Geometrie (Marker-Pfade)
+│
+├── style/                          // Style-Typen (öffentlich)
+│   └── types.ts                    // LineStyle, FillStyle, FillRegion, MarkerStyle, ShadowStyle, SeriesStyle
+│
+├── data/                           // reines Daten-Modell + Parsing
+│   ├── types.ts                    // DataPoint, AggregatedPoint, Series, Threshold, Annotation, …
+│   └── parser.ts                   // parseSeries, parseAggregated, …
+│
+├── axis/                           // Zeit-/Wert-Achsen
+│   ├── time_axis.ts
+│   ├── value_axis.ts
+│   └── enum_axis.ts
+│
+├── renderer/                       // DrawCommand-Renderer
+│   ├── renderer.ts                 // abstract
+│   ├── svg_renderer.ts             // DOM-freier SVG-String
+│   ├── command_builder.ts
+│   ├── grid_renderer.ts
+│   ├── legend_renderer.ts
+│   └── series_renderer.ts          // Series → DrawCommand[]
+│
+├── series/                         // Per-Serie-Geometrie & Render-Layer
+│   ├── line_series.ts
+│   ├── step_series.ts
+│   ├── band_series.ts
+│   ├── minmaxavg_series.ts
+│   ├── zoned_line_series.ts        // Multi-Zone-Coloring + Region-Fills
+│   ├── threshold_renderer.ts
+│   ├── gap_renderer.ts
+│   ├── annotation_band.ts
+│   └── stats_overlay.ts            // ⟵ aus statistics/ hierher; ist Render-Layer
+│
+├── annotation/                     // Marker / Highlights / Annotations
+│   ├── marker.ts
+│   ├── highlight.ts
+│   └── annotation_renderer.ts
+│
+├── analyze/                        // ⟵ Begleit-Modul, Subpath-Export ml-time-graph/analyze
+│   ├── index.ts                    // Barrel
+│   ├── aggregator.ts               // aggregateBySlot, downsample, detectGaps
+│   ├── processor.ts                // Interpolation, getRuns, splitByBoundaries
+│   ├── moving_avg.ts
+│   ├── stats.ts                    // StatsAggregator
+│   ├── mkt.ts                      // NEU
+│   ├── std_dev.ts                  // NEU
+│   └── limits.ts                   // NEU
+│
+└── interaction/                    // ⟵ Begleit-Modul, Subpath-Export ml-time-graph/interaction
+    ├── index.ts                    // Barrel
+    ├── zoom.ts
+    ├── minimap.ts
+    └── tooltip.ts
+```
+
+Jede Datei < 250 Zeilen (Projekt-Style-Guide). `interaction/` ist heute schon
+ein eigenes Verzeichnis — bekommt nur das Barrel + Subpath-Export.
+
+### Subpath-Exports in `package.json`
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./analyze": {
+      "import": "./dist/analyze.js",
+      "require": "./dist/analyze.cjs",
+      "types": "./dist/analyze.d.ts"
+    },
+    "./interaction": {
+      "import": "./dist/interaction.js",
+      "require": "./dist/interaction.cjs",
+      "types": "./dist/interaction.d.ts"
+    }
+  }
+}
+```
+
+Konsumenten importieren je nach Bedarf:
+
+```ts
+import { MLTimeGraph, SVGRenderer } from 'ml-time-graph';           // Render-Kern
+import { aggregateBySlot, mkt, stdDev } from 'ml-time-graph/analyze';
+import { Zoom, Minimap, Tooltip } from 'ml-time-graph/interaction';
+```
+
+Wer nur die Chart braucht, holt sich nicht die Analyse-Helfer in den Bundle.
+
+### Theme — global default + per-Chart-Override
+
+Zwei Ebenen:
+
+```ts
+import { setDefaultTheme, getDefaultTheme, MLTimeGraph } from 'ml-time-graph';
+
+// 1. Globales Default einmal setzen (z. B. beim App-Start) — optional.
+setDefaultTheme({
+  stroke: '#0f172a',
+  gridStroke: '#f1f5f9',
+  palette: ['#3b82f6', '#ef4444', '#22c55e', '#f59e0b'],
+});
+
+// 2. Per-Chart-Override — wird auf das globale Default gemergt.
+new MLTimeGraph({
+  theme: { stroke: '#7c3aed' },   // nur stroke wird übersteuert
+  // …
+});
+```
+
+**Resolutions-Reihenfolge** beim Chart-Konstruktor:
+
+```
+resolvedTheme = { ...BUILTIN_DEFAULTS, ...globalDefault, ...options.theme }
+```
+
+Wenn nirgends gesetzt: nur `BUILTIN_DEFAULTS` (die Werte aus
+`src/theme/defaults.ts`). Wenn nur global gesetzt: alle Charts kriegen den
+globalen Look. Per-Chart-Override schlägt beides.
+
+```ts
+// API:
+export function setDefaultTheme(partial: Partial<Theme>): void;
+export function getDefaultTheme(): Readonly<Theme>;
+export function resetDefaultTheme(): void;  // zurück auf BUILTIN_DEFAULTS
+```
+
+**Vorsicht** (im Doc dokumentieren!): das globale Default ist ein
+**Module-Level-Side-Effect**. Konsequenzen:
+
+- **SSR**: in einer Node.js-Server-Umgebung mit mehreren parallelen Renders
+  würde `setDefaultTheme` aus Request A auch Request B beeinflussen. Empfehlung
+  für SSR: Theme **per-Chart** übergeben, `setDefaultTheme` nur in
+  Browser-/CLI-Kontexten benutzen.
+- **Tests**: nach Tests, die `setDefaultTheme` setzen, `resetDefaultTheme()`
+  in `afterEach` aufrufen, damit Test-Reihenfolge keine Rolle spielt.
+
+Diese Caveats stehen so auch in der JSDoc von `setDefaultTheme`, damit
+TypeScript-Hover sie zeigt.
+
+### Späterer Ausgliederungs-Schnitt
+
+Wenn (a) das Analyse-API stabil ist und (b) ein zweiter Konsument auftaucht,
+kann `src/analyze/` 1:1 zu einem separaten Package `mlcanalyze` (oder
+`@mlc/analyze`) auf einem eigenen Repo ausziehen. `ml-time-graph` würde dann
+`mlcanalyze` als (Peer-)Dependency listen, oder die `overlays:`-Berechnung
+würde komplett vom Konsumenten kommen. Solange das nicht ansteht — bleibt
+einrepoig.
+
+---
+
+## 12. MLTimeGraphOptions — Top-Level-Form
+
+Das Ziel-Top-Level-API:
+
+```ts
+export interface MLTimeGraphOptions {
+  // — Geometrie
+  width?: number;
+  height?: number;
+  margin?: Margin;
+
+  // — Renderer (DI)
+  renderer?: Renderer;
+
+  // — Daten
+  series: Series[];
+
+  // — Achsen + Grid
+  axes?: { x?: XAxisConfig; left?: YAxisConfig; right?: YAxisConfig };
+
+  // — Hintergrund-Layer (in Z-Reihenfolge: thresholds → highlights → gaps → series → annotations)
+  thresholds?: Threshold[];
+  highlights?: Highlight[];
+  gaps?: GapsConfig;
+
+  // — Vordergrund-Annotationen
+  markers?: Marker[];
+  annotations?: Annotation[];
+  annotationBands?: AnnotationBandConfig[];
+
+  // — Theme + Locale
+  theme?: Partial<typeof theme>;
+  locale?: string;
+
+  // — Legende
+  legend?: LegendOptions;
+}
+```
+
+`AxisLabels`, `GridOptions` (flach), `GapConfig` (alt) entfallen — ihre Inhalte
+sind jetzt strukturiert unter `axes` / `gaps`.
+
+---
+
+## A. Migrations-Historie (v0.2 → v0.3 → Cleanup)
+
+Die heutige API entstand in vier Phasen über mehrere Branches. Detail-Logs
+stehen in [`cleanup_progress.md`](docs/cleanup_progress.md) und in den
+Git-Commit-Messages; hier nur die Eckpunkte als Begründungs-Kontext.
+
+**Phase 1 — Interner Cleanup (kein API-Bruch).** `theme.ts` (542 LoC) in vier
+fokussierte Module aufgespalten. Analyse-Helfer aus `src/data/` und
+`src/statistics/` nach `src/analyze/` umgezogen, Subpath-Export
+`ml-time-graph/analyze` eingeführt. `src/interaction/` analog mit eigenem
+Barrel + Subpath. Tote Code-Blöcke entfernt, leere Files gelöscht. Alle 211
+Tests blieben grün, kein Aufrufer brach.
+
+**Phase 2 — Style-System additiv eingeführt.** `SeriesStyle` (nested:
+`line`/`fill`/`markers`/`shadow`/`gap`) als alternative Form zu den ~30 flachen
+Style-Feldern auf `TimeSeries`. `FillSpec` / `FillRegion` als strukturiertes
+Fill-Modell (heute auch für legacy `fillToThreshold(s)` der zugrundeliegende
+Render-Pfad). `axes: AxesConfig` als First-Class-Block. `GapsConfig` als
+Union-Form für `gaps`. `setDefaultTheme` / `getDefaultTheme` / `resetDefaultTheme`
+für globale Theme-Defaults. Spezialisierte Aggregat-Typen `MktPoint` /
+`StdDevPoint` / `LimitStatsPoint`. `synthetic?: boolean` auf `DataPoint`.
+`SeriesOverlay`-Union (Typ-only, Rendering folgt). `LineVariant` + 13
+Marker-Shapes vollständig im SVG-Renderer verdrahtet. ~80 % der flachen
+Style-Felder auf den Series-Interfaces mit `@deprecated`-Migrations-Hinweisen
+markiert. Alle 211 Phase-1-Tests + 58 neue (= 269) grün.
+
+**Phase 3 — Statistik-Overlays + Schließen der Wiring-Lücken.** Drei
+pur-funktionale Compute-Helfer in `src/analyze/`: `mkt`/`rollingMkt` (USP
+<1079.2>), `stdDev`/`sampleStdDev`/`rollingStdDev`, `computeLimitExcursions`.
+`SeriesOverlay`-Rendering verdrahtet (`movingAverage`, `movingMkt`, `limits`;
+`stdDevBand` blieb no-op). Alle weiteren Style-Sub-Objekte (`style.line[]`,
+`style.markers`, `style.shadow`, `style.gap`, `axes.*.format` / `ticks`,
+`axes.*.domain`) im Renderer verdrahtet. Legacy `fillToThreshold(s)` per
+Resolver-Mapping auf den `FillSpecRenderer` umgelenkt — heute ein einziger
+Fill-Render-Pfad. `GapsConfig.autoDetect` aktiv. 49 neue Tests (= 318).
+
+**Phase 4 — Stabilisierung 0.3.0.** `USAGE.md` durchgängig auf die neue
+API umgeschrieben. `VERSION` + `package.json` von `0.2.0` → `0.3.0`. Die
+legacy flachen Felder blieben noch mit `@deprecated`-Hinweis erhalten.
+
+**Phase 5 — Hart-Removal-Bruch (durchgeführt 2026-06-01).** Alle
+`@deprecated`-Pfade entfernt:
+
+- Flache Style-Felder auf `TimeSeries` (`color`, `lineWidth`, `dashed`,
+  `smoothing`, `shadow*`, `pointStyle/Size/Threshold`, `gapThreshold`,
+  `gapFill*`, `gapLabel*`, `gapFontFill`) gelöscht — alles über
+  `style.{line,fill,markers,shadow,gap}`.
+- `fillToThreshold` / `fillToThresholds` / `fillByThresholds*` entfernt
+  — Konsumenten nutzen `style.fill.regions[]` oder den
+  `fillBetweenThresholds()`-Helper.
+- `AggregatedSeries` flache `color` / `smoothing` / `lineWidth` entfernt.
+- `axisLabels` / `grid`-Top-Level entfernt — alles über
+  `axes.{x,left,right}`.
+- `AggregatedPoint`-Extras (`mkt`, `deltaMkt`, `stdDev`,
+  `minutesAboveHigh/BelowLow`) auf die spezialisierten Untertypen
+  (`MktPoint`, `StdDevPoint`, `LimitStatsPoint`, `StatsAggregatedPoint`)
+  umgezogen. Interne Konsumenten (`aggregator`, `heatmap`,
+  `model/apotheken`) auf `StatsAggregatedPoint` umgetypt.
+- 8 Renderer-Klassen → freie Funktionen (`renderMarkers`,
+  `renderHighlights`, `renderAnnotations`, `renderGrid`,
+  `renderThresholds`, `renderLegend`, `renderGaps`, plus die 6
+  Funktionen aus dem ehemaligen `SeriesRenderer`-Static-Container).
+- `src/style/types.ts` (244 LoC Monolith) in vier konzept-fokussierte
+  Files aufgespalten (`enums.ts`, `series.ts`, `fill.ts`, `gap.ts`).
+- `#config`-Pattern auf alle restlichen Series-/Axis-Klassen statt
+  Feld-für-Feld-Kopie.
+- Demo-Migration: 9 Demo-Files auf nested-Style umgestellt.
+
+Resultat: **0 × `@deprecated`** in `src/`, `demos/src/`, `tests/`. Eine
+API-Form überall. 340 Tests grün.
+
+## B. Polish-Backlog (post-v0.3)
+
+Liste der Polish-Ideen, die im Backlog (`.mlcai/BACKLOG.md`) leben:
+
+- `mount()`-One-Liner-Helper — landed (2026-06-01).
+- Tooltip-Helper mit Multi-Series-Callback (`I-20260601-01`).
+- `validate`-Option für klarere Fehler bei kaputten Options (`I-20260601-02`).
+- Public-vs-Internal-Type-Split via Subpath-Exports (`I-20260601-03`).
+- CSS-Class-basiertes Theming statt SVG-Attribute (`I-20260601-04`).
+- Journey-Format auf alle Demo-HTMLs ausrollen (`T-20260601-01`).
+
+## C. Aufgelöste Design-Entscheidungen
+
+Während des Cleanups gefällte Entscheidungen, jeweils mit Datum + Kurz-Begründung:
+
+| # | Frage | Entscheidung |
+|---|-------|--------------|
+| Q1 | `Series.data`: diskriminiert oder flach? | **flach** — `points: DataPoint[] \| AggregatedPoint[]`, strukturell erkannt. Spezialisierte Aggregate erweitern `AggregatedPoint` strukturell. |
+| Q2 | `TimeSeries`/`AggregatedSeries` als Alias erhalten? | **ja**, als `@deprecated`-Type-Aliase bis Phase 5. |
+| Q3 | Wie wird die Darstellungsart ausgewählt? | **kein `seriesType`-Enum** — Komposition durch Style-Sub-Objekte (`line` da → Linie, `fill` → Fläche, `markers` → Punkte). `line: LineStyle[]` für Multi-Line-Stack. |
+| Q4 | `fillBetweenThresholds()` als offizieller Helper? | **ja**, im Haupt-Barrel. |
+| Q5 | Theme per-Chart oder global? | **beides** — `options.theme` per Chart + `setDefaultTheme(partial)` global. Resolution: `BUILTIN_DEFAULTS` ← `globalDefault` ← `options.theme`. SSR-/Test-Caveats in JSDoc. |
+| Q6 | `interaction/` (Zoom/Minimap/Tooltip): bleiben oder raus? | **bleibt** als Begleit-Modul mit eigenem Barrel + Subpath-Export `ml-time-graph/interaction`. |
+| Q7 | JSDoc-Tiefe? | **Top-Ebene** ist Pflicht; Property-Doku ergänzt der Konsument bei Bedarf. |
+| Q8 | Major-Bump direkt nach Phase 4? | **nein**, erst Stabilisierungs-Phase (`0.3.x`/`0.5.x`), dann `1.0`. |
+| Q9 | Wo lebt `fillBetweenThresholds()`? | **Haupt-Barrel** (`ml-time-graph`). Style-Konstruktion ist Konsumenten-API, kein Analyse-Schritt. |
+| Q10 | Bei `line: LineStyle[]`: gleiche oder eigene Daten pro Sub-Linie? | **gleiche Daten**. Eigene Daten für Trendlinien gehen über `overlays: [{ kind: 'movingAverage', … }]`. |
+| Q11 | Wie mit künstlich eingefügten Punkten (Threshold-Schnitte, Gap-Ränder)? | **`DataPoint.synthetic?: boolean`** — wird vom internen `SeriesProcessor` automatisch gesetzt, kann auch manuell verwendet werden. Renderer-Konsequenz: kein Marker, nicht hit-testbar, nicht in Werte-Tabelle. Skalen zählen den Punkt mit. |