ml-time-graph 1.0.0

package/USAGE.md

@@ -0,0 +1,343 @@
+# MLTimeGraph — Usage & API
+
+*[← README](README.md) · [Deutsch](README.de.md)*
+
+## Install
+
+```bash
+pnpm add ml-time-graph    # or npm install / yarn add
+```
+
+## Quick start
+
+```ts
+import { mount } from 'ml-time-graph';
+
+mount('#chart', {
+  height: 320,
+  series: [{
+    name: 'Temperature',
+    style: { line: { color: '#ef4444' } },
+    data: [
+      { time: Date.UTC(2026, 0, 1, 0), value: 18.2 },
+      { time: Date.UTC(2026, 0, 1, 1), value: 19.1 },
+      // …
+    ],
+  }],
+});
+```
+
+`mount` accepts an HTMLElement or a CSS selector, picks up the target's
+width if `options.width` is unset, and returns the chart instance for
+later use (`chart.invertTime` / `chart.setData` / `chart.legendItems`).
+
+Under the hood it's just the three explicit steps:
+
+```ts
+import { MLTimeGraph, SVGRenderer } from 'ml-time-graph';
+
+const chart = new MLTimeGraph({ ...options });
+const { content } = new SVGRenderer().render(chart.renderCommands());
+el.innerHTML = content;
+```
+
+`renderCommands()` returns renderer-agnostic draw commands; `SVGRenderer`
+turns them into an SVG string. It needs **no DOM**, so it works both in
+the browser and server-side. For DOM-specific behaviour, extend
+`SVGRenderer`.
+
+## Series
+
+A `series` entry is either a **raw** time series (`DataPoint[]` = `{ time, value }`)
+or an **aggregated** series (`AggregatedPoint[]` = `{ time, min, max, avg, count }`).
+
+Visual styling lives in a nested `style` block — `line`, `fill`, `markers`, `shadow`,
+`gap`. Any combination is allowed: set `line` for a line, add `fill` for an area
+underneath, add `markers` for points, set `style.line: false` for points only.
+
+```ts
+// Raw line
+{
+  name: 'CPU',
+  data,
+  style: {
+    line: { color: '#4285f4', width: 2, style: 'solid', smoothing: true },
+    markers: { type: 'circle', size: 3 },
+  },
+}
+
+// Step + smoothed overlay (multi-line array — same data, both rendered)
+{
+  name: 'CPU',
+  data,
+  style: { line: [
+    { color: '#999', width: 1, shape: 'step' },
+    { color: '#3b82f6', width: 2, smoothing: true },
+  ] },
+}
+
+// Aggregated min/max/avg band
+{
+  name: 'Temp',
+  showAs: 'minmaxavg',
+  data: aggregateBySlot(raw, 'hourly'),
+  minColor: '#3b82f6', maxColor: '#ef4444', avgColor: '#64748b',
+  avgDashed: true,
+  fillToMax: '#ef444433', fillToMin: '#3b82f633',
+}
+```
+
+`LineVariant` covers `'solid' | 'dotted' | 'sparse-dots' | 'dashed' | 'long-dash' |
+'dense-dash' | 'dash-dot' | 'dash-dot-dot' | 'loose-dash'`.
+
+A point with `value: null` (or a slot with `min/max/avg: null`) marks a **gap** — the
+line breaks there. Two y-axes are supported via `yAxisIndex: 0 | 1` on the series.
+
+## Thresholds (incident analysis)
+
+Define named thresholds once and reference them from a series:
+
+```ts
+new MLTimeGraph({
+  thresholds: [
+    { name: 'warn', value: 22, color: '#f59e0b' },
+    { name: 'crit', value: 28, color: '#ef4444', fill: 'above', label: 'Critical' },
+  ],
+  series: [
+    { name: 'Temp', data, colorByThresholds: ['warn', 'crit'] }, // line coloured per zone
+  ],
+});
+```
+
+- A threshold draws a `line: 'solid' | 'dashed' | 'dotted' | 'none'`, an optional
+  half-plane `fill: 'above' | 'below'`, and a `label`
+  (`false | string | { text?, position? }`; position `left | right | above | below | center`).
+- `colorByThresholds: string[]` colours the line by zone — base colour below the
+  lowest threshold, then each threshold's colour for values above it.
+
+### Fill regions (the structured way)
+
+The new `style.fill` model handles every shape of "fill area":
+
+```ts
+import { fillBetweenThresholds } from 'ml-time-graph';
+
+// A. Above threshold:
+style: { fill: { regions: [
+  { from: { threshold: 'warn' }, to: 'series', side: 'above', fill: '#ef444433' },
+] } }
+
+// B. Between two thresholds (the "OK corridor"):
+style: { fill: { regions: [
+  { from: { threshold: 'low' }, to: { threshold: 'high' }, fill: { color: '#22c55e22', hatch: 'dots' } },
+] } }
+
+// C. Multi-zone heatmap — one call, N+1 colours / hatches:
+style: { fill: fillBetweenThresholds({
+  thresholds: ['cold', 'norm', 'hot'],
+  colors:     ['#60a5fa33', '#22c55e33', '#fbbf2433', '#ef444433'],
+  hatches:    [undefined, 'dots', undefined, 'crosshatch'],
+}) }
+```
+
+A `FillBound` is `'series' | 'chartTop' | 'chartBottom' | { threshold: name } | { value: n }`.
+
+For *classified* (mutually-exclusive) zone bands, give a region both a `side`
+and an `outer` bound — the region renders only in X-spans where the line's
+value is between the fixed inner bound and `outer`:
+
+```ts
+style: { fill: { regions: [
+  // Orange between `high` and `highwarn` only when the line is in that zone
+  { from: 'series', to: { threshold: 'high' }, side: 'above',
+    outer: { threshold: 'highwarn' }, fill: '#f59e0b66' },
+  // Red above `highwarn`
+  { from: 'series', to: { threshold: 'highwarn' }, side: 'above', fill: '#ef444499' },
+] } }
+```
+
+## Legend
+
+```ts
+legend: {
+  show: true,
+  position: 'inside-right' | 'inside-left' | 'outside-right' | 'outside-left' | 'separate',
+  orientation: 'vertical' | 'horizontal',
+}
+```
+
+`outside-*` reserves margin space (the plot shrinks). `'separate'` draws **no** legend
+in the SVG — call `chart.legendItems()` (`{ name, color }[]`) and render your own HTML.
+
+## Axes
+
+Per-axis config — label + tick formatter + tick density + grid + line styling:
+
+```ts
+new MLTimeGraph({
+  axes: {
+    x: {
+      label: 'Time',
+      domain: 'auto',                                       // or [tMin, tMax]
+      format: (d) => d.toISOString().slice(0, 10),
+      axis:  { color: '#7c3aed' },                          // baseline + ticks
+    },
+    left:  {
+      label: 'Temperature (°C)',
+      format: (v) => `${v.toFixed(1)} °C`,
+      ticks: { major: 6 },
+      grid:  { major: { color: '#e2e8f0' } },
+      axis:  { color: '#7c3aed', width: 2 },
+      labels: { color: '#555', fontSize: 12 },
+    },
+    right: { label: 'Humidity (%)', format: (v) => `${v}%` },
+  },
+});
+```
+
+## Gaps
+
+Per-series gaps (the line just breaks at `value: null`) plus chart-level
+auto-detection and manual regions:
+
+```ts
+// chart-level: auto-detect time gaps + a manually flagged region
+new MLTimeGraph({
+  gaps: {
+    autoDetect: true,
+    minGapMs: 60_000,
+    regions: [
+      { startTime: t1, endTime: t2, label: 'Maintenance', style: { display: 'dashed_border' } },
+    ],
+  },
+});
+
+// per-series style.gap — overrides default rendering for the value:null
+// breaks INSIDE this series
+{
+  name: 'CPU', data,
+  style: { gap: { fill: '#ef444422', opacity: 0.3 } },
+}
+
+// 'bridge_line' — dotted bridge across each null gap (missing-data hint)
+{
+  name: 'CPU', data,
+  style: {
+    line: { color: '#3b82f6' },
+    gap:  { display: 'bridge_line',
+            bridge: { color: '#94a3b8', width: 1.5, style: 'dotted' } },
+  },
+}
+```
+
+`gaps:` accepts either the structured `GapsConfig` (preferred) or a plain
+`Gap[]` array for shorthand chart-level regions.
+
+## Statistic overlays
+
+Computed at render time from the series' raw data; each overlay has its own
+style and appears as a sub-element on top of the parent series.
+
+```ts
+{
+  name: 'Fridge sensor', data,
+  style: { line: { color: '#3b82f6' } },
+  overlays: [
+    { kind: 'movingAverage', window: 4 * 60 * 60_000, style: { line: { color: '#7c3aed', style: 'dashed' } } },
+    { kind: 'movingMkt',     window: 24 * 60 * 60_000, activationEnergy: 83144,
+      style: { line: { color: '#ef4444' } } },
+    { kind: 'stdDevBand',    window:  4 * 60 * 60_000, multiplier: 2,
+      style: { fill: '#94a3b833' } },
+    { kind: 'limits',        low: 2, high: 8,
+      style: { line: { color: '#ef4444', style: 'dotted' } } },
+  ],
+}
+```
+
+Supported overlay kinds: `'movingAverage'`, `'movingMkt'` (USP <1079.2>),
+`'stdDevBand'` (mean ± multiplier·σ band), `'limits'`.
+
+## Aggregation & helpers
+
+The full analyse companion is at `ml-time-graph/analyze`:
+
+```ts
+import {
+  aggregateBySlot, downsample, detectGaps,
+  mkt, rollingMkt, DEFAULT_ACTIVATION_ENERGY,
+  stdDev, sampleStdDev, rollingStdDev,
+  computeLimitExcursions,
+  MovingAvg, StatsAggregator,
+} from 'ml-time-graph/analyze';
+
+aggregateBySlot(raw, 'hourly');                 // min/max/avg per slot
+downsample(raw, 2000);                          // LTTB → ~2000 points
+detectGaps(raw, 60_000);                        // time-gap detection
+
+rollingMkt(raw, 24 * 60 * 60_000);              // rolling MKT (USP <1079.2>)
+rollingStdDev(raw, 60 * 60_000);                // rolling σ (population)
+computeLimitExcursions(raw, { low: 2, high: 8 }); // → LimitStats with excursion list
+
+StatsAggregator.compute(raw);                   // { min, max, avg, mean, median, stdDev, count }
+```
+
+The main barrel (`'ml-time-graph'`) carries only the rendering surface; the
+analysis helpers live behind the `'ml-time-graph/analyze'` subpath.
+
+## Annotations (custom overlays)
+
+Draw your own shapes in **data coordinates** (time/value); the chart projects them to
+pixels, so they track the data through zoom/resize:
+
+```ts
+new MLTimeGraph({
+  series,
+  annotations: [
+    { type: 'arrow', from: { time: t1, value: 22 }, to: { time: t2, value: 30 }, color: '#7c3aed' },
+    { type: 'label', at: { time: t2, value: 30 }, text: 'Spike', dy: -8 },
+    { type: 'rect',  from: { time: a, value: 20 }, to: { time: b, value: 26 }, fill: '#7c3aed18' },
+    { type: 'point', at: { time: t, value: v }, shape: 'circle' },
+    { type: 'line',  from: { time: a, value: v }, to: { time: b, value: v }, dash: 'dotted' },
+  ],
+});
+```
+
+A coordinate is a `DataPointRef` = `{ time, value, axis? }` (`axis` selects the y-scale).
+
+Annotations can also be managed **dynamically** (e.g. on a click). Like `setData`,
+these update state — re-render afterwards (`renderCommands()` → renderer):
+
+```ts
+const id = chart.addAnnotation({ type: 'point', at: { time, value } }); // → id
+chart.disableAnnotation(id);   // hide without removing
+chart.enableAnnotation(id);    // show again
+chart.removeAnnotation(id);
+chart.setAnnotations([...]);   // replace all
+chart.clearAnnotations();
+chart.getAnnotations();        // read-only snapshot
+```
+
+For anything beyond these shapes, use the projection directly — the inverse of
+`invertTime` / `invertValue`:
+
+```ts
+chart.renderCommands();
+const { x, y } = chart.project(time, value, axis);  // data → pixel
+```
+
+## Interaction
+
+Zoom/pan and tooltips are intentionally **not** baked into the chart. Map pixels to
+data with `chart.invertTime(px)` / `chart.invertValue(py, axisIndex)` and build the
+interaction in your app — see the demo gallery's "Fridge" (range slider) and
+"Interaction" (tooltip) pages.
+
+## Renderer
+
+`render()` is the only method a renderer must implement
+(`abstract render(commands: DrawCommand[]): RenderOutput`). The shipped `SVGRenderer`
+emits a DOM-free SVG string. To produce live DOM nodes or add interactivity, extend it.
+
+---
+
+Runnable examples of every feature live in the [demo gallery](demos/) — run `pnpm dev`.

package/dist/aggregated_subtypes-DZNZyFTX.d.ts

@@ -0,0 +1,43 @@
+import { A as AggregatedPoint } from './scale-Cbr0KpPz.js';
+
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+
+/** Slot carrying a rolling Mean Kinetic Temperature value (USP <1079.2>). */
+interface MktPoint extends AggregatedPoint {
+    /** Mean kinetic temperature for this slot. `null` = gap. */
+    mkt: number | null;
+    /** Delta vs the previous slot's MKT (optional). */
+    deltaMkt?: number | null;
+}
+/** Slot carrying the standard deviation of the samples in the window. */
+interface StdDevPoint extends AggregatedPoint {
+    /** Standard deviation of the samples in this slot. `null` = gap. */
+    stdDev: number | null;
+}
+/**
+ * Slot carrying minutes-above-/below-limit statistics. At least one of
+ * `minutesAboveHigh` or `minutesBelowLow` must be set.
+ */
+interface LimitStatsPoint extends AggregatedPoint {
+    /** Minutes above the upper limit in this slot. */
+    minutesAboveHigh?: number | null;
+    /** Minutes below the lower limit in this slot. */
+    minutesBelowLow?: number | null;
+}
+/**
+ * The "full-stats" aggregated slot — combines all three specialised
+ * subtypes via intersection. This is what `aggregateBySlot(data, mode,
+ * thresholds)` returns when thresholds are provided: per-slot MKT (USP
+ * <1079.2>), standard deviation, and out-of-bounds minute counters.
+ *
+ * Prefer this typed alias over plain `AggregatedPoint` whenever you
+ * downstream-consume `aggregateBySlot`'s output and want guaranteed access
+ * to the stat fields.
+ */
+type StatsAggregatedPoint = MktPoint & StdDevPoint & LimitStatsPoint;
+
+export type { LimitStatsPoint as L, MktPoint as M, StatsAggregatedPoint as S, StdDevPoint as a };

package/dist/analyze/index.d.ts

@@ -0,0 +1,296 @@
+import { l as DataPoint, A as AggregatedPoint, d as AggregationThresholds, J as Gap, ae as TimeScale, W as LinearScale, _ as Point, p as DrawCommand } from '../scale-Cbr0KpPz.js';
+import { S as StatsAggregatedPoint } from '../aggregated_subtypes-DZNZyFTX.js';
+
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+
+/**
+ * Utility for processing time-series data: sorting, gap detection,
+ * and splitting by value boundaries (thresholds).
+ */
+declare class SeriesProcessor {
+    /**
+     * Standard interpolation for scalar DataPoints.
+     */
+    static interpolateDataPoint(p1: DataPoint, p2: DataPoint, t: number): DataPoint;
+    /**
+     * Standard interpolation for AggregatedPoints (interpolates min, max, avg and count).
+     */
+    static interpolateAggregatedPoint(p1: AggregatedPoint, p2: AggregatedPoint, t: number): AggregatedPoint;
+    /**
+     * Splits a data array into contiguous runs based on null values or time jumps.
+     *
+     * @param data The raw data points.
+     * @param isNull A predicate to identify "gap" points (e.g. value === null).
+     * @param gapThreshold Max time distance between points before a new run starts.
+     */
+    static getRuns<T extends {
+        time: number;
+    }>(data: T[], isNull: (p: T) => boolean, gapThreshold?: number): T[][];
+    /**
+     * Splits a contiguous run into sub-segments at the given boundary values.
+     * Inserts interpolated points at every boundary crossing so segments
+     * meet exactly at the boundary.
+     *
+     * @param run A gap-free array of points.
+     * @param boundaries Values at which to split the run.
+     * @param getValue Function to extract the numeric value used for splitting.
+     * @param interpolate Function to create an interpolated point between p1 and p2 at factor t [0..1].
+     */
+    static splitByBoundaries<T>(run: T[], boundaries: number[], getValue: (p: T) => number, interpolate: (p1: T, p2: T, t: number) => T): {
+        data: T[];
+        zoneIndex: number;
+    }[];
+    /**
+     * Splits a contiguous run into two groups: those below and those at/above a threshold.
+     * Internally uses splitByBoundaries to ensure exact intersection points.
+     */
+    static splitByThreshold<T>(run: T[], threshold: number, getValue: (p: T) => number, interpolate: (p1: T, p2: T, t: number) => T): {
+        above: T[][];
+        below: T[][];
+    };
+}
+
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+
+type ProductType = "pharma_cold" | "pharma_ambient" | "blood" | "food_chilled" | "frozen" | "custom";
+interface ProductConfig {
+    limitLow: number;
+    limitHigh: number;
+    activationEnergy?: number;
+}
+declare const PRODUCT_PROFILES: Record<Exclude<ProductType, "custom">, ProductConfig>;
+declare function aggregateBySlot(data: DataPoint[], mode?: "hourly" | "daily" | "custom", customInterval?: number, thresholds?: AggregationThresholds, minCountForMkt?: number): StatsAggregatedPoint[];
+declare function createAggr(time: number, values: number[]): AggregatedPoint;
+/**
+ * Detect gaps in time-series data (autoDetect).
+ * Gibt alle Zeitenrücken zurück wo das Zeitintervall > minGapMs ist.
+ */
+declare function detectGaps(data: DataPoint[], minGapMs?: number): Gap[];
+interface LongTermInsight {
+    type: "warning" | "info" | "critical";
+    message: string;
+    metric?: string;
+}
+declare function analyzeLongTermTrends(aggregatedData: StatsAggregatedPoint[]): LongTermInsight[];
+declare function downsample(data: DataPoint[], target: number): DataPoint[];
+/**
+ * Typed aggregation wrapper — returns slots with MKT + StdDev + Limit-Excursion
+ * fields all guaranteed present (as `number | null`). Equivalent to calling
+ * {@link aggregateBySlot} with thresholds, but with a clean typed return so
+ * downstream code can rely on the stats fields without `'mkt' in slot` guards.
+ *
+ * @example
+ * import { aggregateWithStats } from 'ml-time-graph/analyze';
+ * const slots = aggregateWithStats(rawTempData, 'hourly', { low: 2, high: 8 });
+ * for (const s of slots) {
+ *   if (s.mkt !== null) console.log(s.time, 'MKT', s.mkt, 'σ', s.stdDev);
+ * }
+ */
+declare function aggregateWithStats(data: DataPoint[], mode: "hourly" | "daily" | "custom" | undefined, opts: {
+    /** Lower bound for the limit-excursion counter (°C). */
+    low: number;
+    /** Upper bound for the limit-excursion counter (°C). */
+    high: number;
+    /** Activation energy in J/mol (default 83144 per USP <1079.2>). */
+    activationEnergy?: number;
+    /** Slot interval in ms — required when `mode === 'custom'`. */
+    interval?: number;
+    /** Minimum sample count per slot before MKT is computed; below → `null`. */
+    minCountForMkt?: number;
+}): StatsAggregatedPoint[];
+
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+
+/**
+ * Statistics aggregator.
+ * Computes min, max, avg, median from a set of data points.
+ */
+interface StatsResult {
+    min: number;
+    max: number;
+    avg: number;
+    mean: number;
+    median: number;
+    stdDev: number;
+    count: number;
+}
+declare class StatsAggregator {
+    /** Compute statistics from data points */
+    static compute(data: DataPoint[]): StatsResult;
+    /** Compute stats for a specific time range (viewport-scoped) */
+    static computeInRange(data: DataPoint[], startTime: number, endTime: number): StatsResult;
+}
+
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+
+/** Moving average type */
+type MovingAvgType = "simple" | "exponential";
+interface MovingAvgConfig {
+    /** Data points */
+    data: DataPoint[];
+    /** Window size (number of data points) */
+    windowSize: number;
+    /** MA type */
+    type?: MovingAvgType;
+    /** Time scale for X-axis */
+    timeScale: TimeScale;
+    /** Value scale for Y-axis */
+    valueScale: LinearScale;
+    /** Stroke color */
+    stroke?: string;
+    /** Stroke width */
+    strokeWidth?: number;
+}
+declare class MovingAvg {
+    #private;
+    constructor(config: MovingAvgConfig);
+    /** Compute simple moving average points */
+    static simple(data: DataPoint[], windowSize: number): {
+        time: number;
+        value: number;
+    }[];
+    /** Compute exponential moving average (EMA) */
+    static exponential(data: DataPoint[], windowSize: number): {
+        time: number;
+        value: number;
+    }[];
+    /** Get computed moving average as pixel points */
+    points(): Point[];
+    /** Render MA as a path command */
+    render(): DrawCommand[];
+}
+
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+
+/** Default activation energy for pharma stability (USP <1079.2>): 83144 J/mol. */
+declare const DEFAULT_ACTIVATION_ENERGY = 83144;
+/**
+ * Compute the Mean Kinetic Temperature (in °C) of a list of temperature
+ * samples (also in °C). All samples are weighted equally. Returns `null`
+ * if the input is empty or contains no non-null values.
+ *
+ * Formula (USP <1079.2>):
+ *
+ *   T_mkt = (E_a / R) / (-ln( (1/N) · Σ exp(-E_a / (R · T_i)) ))
+ *
+ * where `T_i` are the per-sample temperatures in Kelvin and `N` is the
+ * count of valid samples.
+ */
+declare function mkt(samples: (number | null)[], activationEnergy?: number): number | null;
+/**
+ * Rolling Mean Kinetic Temperature over a sliding time window. For each
+ * input point at time `t`, emits an output point whose value is the MKT
+ * of all samples in the closed interval `[t - windowMs, t]`. The output
+ * has the same length and timestamps as the input. A `value: null` in
+ * the output marks a window that contained no valid samples.
+ *
+ * `data` must be sorted by `time` ascending. `value: null` inputs are
+ * skipped (treated as gaps).
+ *
+ * @param data              Input DataPoints in °C, sorted by time ascending.
+ * @param windowMs          Window length in ms (e.g. `7 * 24 * 3_600_000` for 7d).
+ * @param activationEnergy  Default `83144` J/mol (USP <1079.2>).
+ */
+declare function rollingMkt(data: DataPoint[], windowMs: number, activationEnergy?: number): DataPoint[];
+
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+
+/**
+ * Population standard deviation (σ, divisor `N`) of the non-null samples.
+ * Returns `null` for an empty or all-null input.
+ */
+declare function stdDev(samples: (number | null)[]): number | null;
+/**
+ * Sample standard deviation (s, divisor `N - 1`). Returns `null` for fewer
+ * than 2 non-null samples (the sample-stddev is undefined for a single point).
+ */
+declare function sampleStdDev(samples: (number | null)[]): number | null;
+/**
+ * Rolling standard deviation over a sliding time window. For each input
+ * point at time `t`, emits an output point whose value is the population
+ * standard deviation of all valid samples in `[t - windowMs, t]`. The
+ * output has the same length / timestamps as the input.
+ *
+ * `data` must be sorted by `time` ascending. `value: null` is skipped.
+ *
+ * @param data              Sorted input DataPoints.
+ * @param windowMs          Window length in ms.
+ * @param sample            Use sample-stddev (divisor N-1) instead of
+ *                          population-stddev (divisor N). Default `false`.
+ */
+declare function rollingStdDev(data: DataPoint[], windowMs: number, sample?: boolean): DataPoint[];
+
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+
+/** A single out-of-bounds episode. */
+interface LimitExcursion {
+    /** Start time of the excursion (ms epoch). */
+    startTime: number;
+    /** End time of the excursion (ms epoch). */
+    endTime: number;
+    /** 'above' = exceeded `high`. 'below' = fell under `low`. */
+    side: "above" | "below";
+    /** Maximum (for 'above') or minimum (for 'below') value reached in the episode. */
+    extremum: number;
+    /** Duration in ms. */
+    durationMs: number;
+}
+/** Aggregate metrics computed over the full input series. */
+interface LimitStats {
+    /** Total time (ms) the series spent above `high`. */
+    msAboveHigh: number;
+    /** Total time (ms) the series spent below `low`. */
+    msBelowLow: number;
+    /** Maximum value reached anywhere (ignoring nulls). `null` if no samples. */
+    globalMax: number | null;
+    /** Minimum value reached anywhere (ignoring nulls). `null` if no samples. */
+    globalMin: number | null;
+    /** All excursion episodes in chronological order. */
+    excursions: LimitExcursion[];
+}
+interface ComputeLimitsOpts {
+    /** Upper bound — values strictly greater are 'above'. */
+    high?: number;
+    /** Lower bound — values strictly less are 'below'. */
+    low?: number;
+}
+/**
+ * Compute limit-excursion intervals and aggregate metrics for a temperature
+ * series. `data` must be sorted by `time` ascending. `value: null` is treated
+ * as a gap and breaks any in-progress excursion.
+ *
+ * The duration attributed to an in-bounds-to-out-of-bounds transition is
+ * the elapsed time between two adjacent samples — there is no sub-sample
+ * interpolation in this v1; pass denser data for finer accuracy.
+ */
+declare function computeLimitExcursions(data: DataPoint[], opts: ComputeLimitsOpts): LimitStats;
+
+export { type ComputeLimitsOpts, DEFAULT_ACTIVATION_ENERGY, type LimitExcursion, type LimitStats, type LongTermInsight, MovingAvg, type MovingAvgConfig, type MovingAvgType, PRODUCT_PROFILES, type ProductConfig, type ProductType, SeriesProcessor, StatsAggregator, type StatsResult, aggregateBySlot, aggregateWithStats, analyzeLongTermTrends, computeLimitExcursions, createAggr, detectGaps, downsample, mkt, rollingMkt, rollingStdDev, sampleStdDev, stdDev };