@skyhook-io/k8s-ui 1.6.1 → 1.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyhook-io/k8s-ui",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/skyhook-io/radar",
@@ -35,6 +35,11 @@
       "./src/components/timeline/*.tsx",
       "./src/components/timeline/*.ts"
     ],
+    "./components/charts": "./src/components/charts/index.ts",
+    "./components/charts/*": [
+      "./src/components/charts/*.tsx",
+      "./src/components/charts/*.ts"
+    ],
     "./hooks/*": [
       "./src/hooks/*.ts",
       "./src/hooks/*.tsx"

package/src/components/charts/AreaChart.tsx

@@ -0,0 +1,371 @@
+import { useCallback, useMemo, useRef, useState } from 'react'
+import type * as React from 'react'
+import { seriesColor, seriesFill, computeShortLabels } from './colors'
+import { formatMetricValue, formatTimestamp } from './format'
+import type { TimeSeries, ReferenceLine } from './types'
+
+export function AreaChart({ series, color, fillColor, unit, referenceLines }: {
+  series: TimeSeries[]
+  color: string
+  fillColor: string
+  unit: string
+  referenceLines?: ReferenceLine[]
+}) {
+  const svgRef = useRef<SVGSVGElement>(null)
+  const [hoverX, setHoverX] = useState<number | null>(null)
+  const multiSeries = series.length > 1
+
+  const chartData = useMemo(() => {
+    if (!series.length) return null
+
+    let minTs = Infinity
+    let maxTs = -Infinity
+    let maxVal = 0
+
+    for (const s of series) {
+      for (const dp of s.dataPoints) {
+        if (dp.timestamp < minTs) minTs = dp.timestamp
+        if (dp.timestamp > maxTs) maxTs = dp.timestamp
+        if (dp.value > maxVal) maxVal = dp.value
+      }
+    }
+
+    if (minTs === maxTs) maxTs = minTs + 60
+    if (maxVal === 0) {
+      // Unit-appropriate floor so the Y-axis isn't misleadingly large.
+      maxVal = unit === 'cores' ? 0.01 : unit === 'bytes' ? 1024 * 1024 : unit === 'bytes/s' ? 1024 : 1
+    }
+
+    // Extend axis to include reference lines so request/limit aren't clipped
+    // at the top, which would make usage-vs-limit unreadable.
+    if (referenceLines) {
+      for (const rl of referenceLines) {
+        if (rl.value > maxVal) maxVal = rl.value
+      }
+    }
+
+    const padding = maxVal * 0.1
+    const yMax = maxVal + padding
+
+    return { minTs, maxTs, yMax, series }
+  }, [series, unit, referenceLines])
+
+  // Layout constants. marginLeft sized for the widest expected Y-tick label
+  // ("422.4 MiB" etc.) — narrow grid panels squeeze the X axis so labels
+  // need extra viewBox-space to survive the down-scale.
+  const width = 1000
+  const height = 300
+  const marginLeft = 84
+  const marginRight = 40
+  const marginTop = 10
+  const marginBottom = 30
+  const plotWidth = width - marginLeft - marginRight
+  const plotHeight = height - marginTop - marginBottom
+
+  // Coord transforms. When chartData is null (empty series) these return 0;
+  // the hooks downstream check chartData and bail to empty results so no
+  // bad coords ever reach the DOM.
+  const toX = (ts: number) => {
+    if (!chartData) return marginLeft
+    return marginLeft + ((ts - chartData.minTs) / (chartData.maxTs - chartData.minTs)) * plotWidth
+  }
+  const toY = (val: number) => {
+    if (!chartData) return marginTop + plotHeight
+    return marginTop + plotHeight - (val / chartData.yMax) * plotHeight
+  }
+
+  const yTicks = useMemo(() => {
+    if (!chartData) return []
+    const { yMax } = chartData
+    const count = 4
+    return Array.from({ length: count + 1 }, (_, i) => {
+      const val = (yMax / count) * i
+      return { val, y: toY(val), label: formatMetricValue(val, unit) }
+    })
+  }, [chartData, unit])
+
+  const xTicks = useMemo(() => {
+    if (!chartData) return []
+    const { minTs, maxTs } = chartData
+    const count = 6
+    return Array.from({ length: count + 1 }, (_, i) => {
+      const ts = minTs + ((maxTs - minTs) / count) * i
+      return { ts, x: toX(ts), label: formatTimestamp(ts) }
+    })
+  }, [chartData])
+
+  const paths = useMemo(() => {
+    if (!chartData) return []
+    return chartData.series.map((s, seriesIdx) => {
+      if (s.dataPoints.length < 2) return null
+      const points = s.dataPoints.map(dp => ({ x: toX(dp.timestamp), y: toY(dp.value) }))
+
+      const linePath = points.map((p, i) => `${i === 0 ? 'M' : 'L'}${p.x},${p.y}`).join(' ')
+      const areaPath = linePath +
+        ` L${points[points.length - 1].x},${marginTop + plotHeight}` +
+        ` L${points[0].x},${marginTop + plotHeight} Z`
+
+      return {
+        linePath,
+        areaPath,
+        strokeColor: multiSeries ? seriesColor(seriesIdx, color) : color,
+        areaFillColor: multiSeries ? seriesFill(seriesIdx, fillColor) : fillColor,
+        key: seriesIdx,
+      }
+    }).filter(Boolean)
+  }, [chartData])
+
+  // Hover: only emit a tooltip row when the hovered timestamp lies within
+  // the series' actual sample range (with 2× median-step tolerance). Without
+  // this filter a series that ended mid-window leaves stale ghost entries.
+  const hoverData = useMemo(() => {
+    if (!chartData || hoverX === null) return null
+    const { minTs, maxTs } = chartData
+    const clampedX = Math.max(marginLeft, Math.min(marginLeft + plotWidth, hoverX))
+    const frac = (clampedX - marginLeft) / plotWidth
+    const ts = minTs + frac * (maxTs - minTs)
+
+    const validSeries = chartData.series
+      .map((s, i) => ({ s, i }))
+      .filter(({ s }) => s.dataPoints.length >= 2)
+
+    const fullLabels = validSeries.map(({ s, i }) =>
+      s.labels.pod || s.labels.instance || s.labels.node || `series-${i}`
+    )
+    const shortLabels = computeShortLabels(fullLabels)
+
+    const points = validSeries.map(({ s, i }, vi) => {
+      const dps = s.dataPoints
+      const seriesMin = dps[0].timestamp
+      const seriesMax = dps[dps.length - 1].timestamp
+      const medianStep = dps.length >= 2
+        ? (seriesMax - seriesMin) / (dps.length - 1)
+        : 30
+      const tolerance = Math.max(medianStep * 2, 60)
+      if (ts < seriesMin - tolerance || ts > seriesMax + tolerance) {
+        return null
+      }
+      let closest = dps[0]
+      let closestDist = Infinity
+      for (const dp of dps) {
+        const dist = Math.abs(dp.timestamp - ts)
+        if (dist < closestDist) {
+          closestDist = dist
+          closest = dp
+        }
+      }
+      return {
+        label: shortLabels[vi],
+        fullLabel: fullLabels[vi],
+        value: closest.value,
+        y: toY(closest.value),
+        color: multiSeries ? seriesColor(i, color) : color,
+      }
+    }).filter((p): p is NonNullable<typeof p> => p !== null)
+
+    return { ts, x: clampedX, points }
+  }, [hoverX, chartData])
+
+  const handleMouseMove = useCallback((e: React.MouseEvent<SVGRectElement>) => {
+    const svg = svgRef.current
+    if (!svg) return
+    const ctm = svg.getScreenCTM()
+    if (!ctm) return
+    setHoverX((e.clientX - ctm.e) / ctm.a)
+  }, [])
+
+  // Hook calls above run unconditionally; bail out of rendering only after
+  // every hook has been invoked (Rules of Hooks).
+  if (!chartData) return null
+
+  return (
+    <div className="relative">
+      <svg
+        ref={svgRef}
+        viewBox={`0 0 ${width} ${height}`}
+        className="w-full h-full"
+        preserveAspectRatio="xMidYMid meet"
+      >
+        {/* Grid lines */}
+        {yTicks.map((tick, i) => (
+          <line
+            key={`grid-${i}`}
+            x1={marginLeft}
+            y1={tick.y}
+            x2={width - marginRight}
+            y2={tick.y}
+            stroke="currentColor"
+            className="text-theme-border/30"
+            strokeWidth="1"
+            strokeDasharray={i === 0 ? undefined : '4 4'}
+          />
+        ))}
+
+        {/* Y axis labels */}
+        {yTicks.map((tick, i) => (
+          <text
+            key={`ylabel-${i}`}
+            x={marginLeft - 8}
+            y={tick.y + 4}
+            textAnchor="end"
+            className="fill-theme-text-secondary"
+            fontSize="11"
+            fontFamily="ui-monospace, monospace"
+          >
+            {tick.label}
+          </text>
+        ))}
+
+        {/* X axis labels */}
+        {xTicks.map((tick, i) => (
+          <text
+            key={`xlabel-${i}`}
+            x={tick.x}
+            y={height - 4}
+            textAnchor="middle"
+            className="fill-theme-text-secondary"
+            fontSize="11"
+            fontFamily="ui-monospace, monospace"
+          >
+            {tick.label}
+          </text>
+        ))}
+
+        {/* Area fills */}
+        {paths.map(p => p && (
+          <path
+            key={`area-${p.key}`}
+            d={p.areaPath}
+            fill={p.areaFillColor}
+          />
+        ))}
+
+        {/* Lines */}
+        {paths.map(p => p && (
+          <path
+            key={`line-${p.key}`}
+            d={p.linePath}
+            fill="none"
+            stroke={p.strokeColor}
+            strokeWidth="2"
+            strokeLinejoin="round"
+          />
+        ))}
+
+        {/* Reference lines (request / limit overlays). Label sits on a subtle
+            background pill so it stays legible against the chart fill. */}
+        {referenceLines?.map((rl, i) => {
+          const y = Math.max(marginTop, Math.min(marginTop + plotHeight, toY(rl.value)))
+          const stroke = rl.kind === 'limit' ? '#f59e0b' : '#94a3b8'
+          const labelText = rl.label
+          // Sized to fit common label widths ("limit 384MiB", "request 100m"
+          // ≈ 90px at fontSize 11). Conservative to prevent right-edge overlap.
+          const labelWidth = labelText.length * 6.5 + 10
+          const labelHeight = 14
+          const labelX = width - marginRight - labelWidth
+          const labelY = Math.max(marginTop + labelHeight + 2, y - 6)
+          return (
+            <g key={`ref-${i}`}>
+              <line
+                x1={marginLeft}
+                y1={y}
+                x2={width - marginRight}
+                y2={y}
+                stroke={stroke}
+                strokeWidth="1"
+                strokeDasharray="6 4"
+                opacity="0.75"
+              />
+              <rect
+                x={labelX}
+                y={labelY - labelHeight + 2}
+                width={labelWidth}
+                height={labelHeight}
+                rx="3"
+                fill="currentColor"
+                className="text-theme-surface"
+                opacity="0.85"
+              />
+              <text
+                x={width - marginRight - 5}
+                y={labelY - 2}
+                textAnchor="end"
+                fontSize="11"
+                fontFamily="ui-monospace, monospace"
+                fontWeight="500"
+                fill={stroke}
+              >
+                {labelText}
+              </text>
+            </g>
+          )
+        })}
+
+        {/* Hover crosshair + dots */}
+        {hoverData && (
+          <>
+            <line
+              x1={hoverData.x} y1={marginTop}
+              x2={hoverData.x} y2={marginTop + plotHeight}
+              stroke="currentColor"
+              className="text-theme-text-tertiary"
+              strokeWidth="1"
+              strokeDasharray="4 4"
+            />
+            {hoverData.points.map((p, i) => (
+              <circle
+                key={i}
+                cx={hoverData.x} cy={p.y}
+                r="4"
+                fill={p.color}
+                stroke="var(--color-theme-surface, #1a1a2e)"
+                strokeWidth="2"
+              />
+            ))}
+          </>
+        )}
+
+        {/* Invisible overlay for mouse events — must be last for event capture */}
+        <rect
+          x={marginLeft} y={marginTop}
+          width={plotWidth} height={plotHeight}
+          fill="transparent"
+          style={{ cursor: 'crosshair' }}
+          onMouseMove={handleMouseMove}
+          onMouseLeave={() => setHoverX(null)}
+        />
+      </svg>
+
+      {/* Tooltip outside SVG for HTML rendering */}
+      {hoverData && (
+        <div
+          className="absolute top-0 pointer-events-none z-10"
+          style={{
+            left: `${(hoverData.x / width) * 100}%`,
+            transform: hoverData.x > width * 0.65 ? 'translateX(calc(-100% - 12px))' : 'translateX(12px)',
+          }}
+        >
+          <div className="bg-theme-surface border border-theme-border rounded-lg shadow-lg px-3 py-2 text-xs whitespace-nowrap">
+            <div className="text-theme-text-tertiary mb-1.5 font-mono">
+              {new Date(hoverData.ts * 1000).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' })}
+            </div>
+            {hoverData.points.map((p, i) => (
+              <div key={i} className="flex items-center gap-2 py-0.5">
+                <div
+                  className="w-2 h-2 rounded-full shrink-0"
+                  style={{ backgroundColor: p.color }}
+                />
+                <span className="text-theme-text-secondary font-mono" title={p.fullLabel}>
+                  {p.label}
+                </span>
+                <span className="text-theme-text-primary font-semibold ml-auto pl-3 tabular-nums">
+                  {formatMetricValue(p.value, unit)}
+                </span>
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/charts/MetricsSummary.tsx

@@ -0,0 +1,49 @@
+import { useMemo } from 'react'
+import { clsx } from 'clsx'
+import { formatMetricValue } from './format'
+import type { TimeSeries } from './types'
+
+export function MetricsSummary({ series, unit, currentColorClass }: {
+  series: TimeSeries[]
+  unit: string
+  /** Tailwind text class for the "Current" pill — caller's accent color. */
+  currentColorClass?: string
+}) {
+  const stats = useMemo(() => {
+    const allValues: number[] = []
+    for (const s of series) {
+      for (const dp of s.dataPoints) {
+        allValues.push(dp.value)
+      }
+    }
+    if (allValues.length === 0) return null
+
+    // Current = sum of each series' most recent data point (matches
+    // operator mental model of "total across pods right now").
+    const lastValues = series.map(s => s.dataPoints[s.dataPoints.length - 1]?.value ?? 0)
+    const current = lastValues.reduce((a, b) => a + b, 0)
+    const max = Math.max(...allValues)
+    const avg = allValues.reduce((a, b) => a + b, 0) / allValues.length
+
+    return { current, max, avg }
+  }, [series])
+
+  if (!stats) return null
+
+  return (
+    <div className="flex items-center gap-6">
+      <StatPill label="Current" value={formatMetricValue(stats.current, unit)} className={currentColorClass} />
+      <StatPill label="Average" value={formatMetricValue(stats.avg, unit)} className="text-theme-text-secondary" />
+      <StatPill label="Peak" value={formatMetricValue(stats.max, unit)} className="text-theme-text-secondary" />
+    </div>
+  )
+}
+
+function StatPill({ label, value, className }: { label: string; value: string; className?: string }) {
+  return (
+    <div className="flex items-baseline gap-1.5">
+      <span className="text-xs text-theme-text-quaternary uppercase tracking-wide">{label}</span>
+      <span className={clsx('text-sm font-semibold tabular-nums', className)}>{value}</span>
+    </div>
+  )
+}

package/src/components/charts/SeriesLegend.tsx

@@ -0,0 +1,27 @@
+import { seriesColor } from './colors'
+import type { TimeSeries } from './types'
+
+// Caps visible entries to match AreaChart's SERIES_COLORS length; extras
+// collapse to "+N more".
+export function SeriesLegend({ series, color }: { series: TimeSeries[]; color: string }) {
+  const labels = series.map((s, i) => s.labels.pod || s.labels.instance || `series-${i}`)
+  return (
+    <div className="flex flex-wrap gap-x-4 gap-y-1 px-1">
+      {series.slice(0, 10).map((_, i) => {
+        const shortName = labels[i].length > 40 ? '...' + labels[i].slice(-37) : labels[i]
+        return (
+          <div key={i} className="flex items-center gap-1.5 text-xs text-theme-text-tertiary">
+            <div
+              className="w-2.5 h-2.5 rounded-full shrink-0"
+              style={{ backgroundColor: seriesColor(i, color) }}
+            />
+            <span className="truncate" title={labels[i]}>{shortName}</span>
+          </div>
+        )
+      })}
+      {series.length > 10 && (
+        <span className="text-xs text-theme-text-quaternary">+{series.length - 10} more</span>
+      )}
+    </div>
+  )
+}

package/src/components/charts/colors.ts

@@ -0,0 +1,49 @@
+// Distinct colors for multi-series charts (up to 10 series).
+// Uses 500-level shades for adequate contrast on both dark (#1e293b) and
+// light (#ffffff) surfaces.
+export const SERIES_COLORS: readonly string[] = [
+  '#3b82f6', // blue-500
+  '#10b981', // emerald-500
+  '#f97316', // orange-500
+  '#a855f7', // purple-500
+  '#ec4899', // pink-500
+  '#eab308', // yellow-500
+  '#06b6d4', // cyan-500
+  '#84cc16', // lime-500
+  '#ef4444', // red-500
+  '#6366f1', // indigo-500
+]
+
+export function seriesColor(index: number, fallback: string): string {
+  return SERIES_COLORS[index % SERIES_COLORS.length] ?? fallback
+}
+
+export function seriesFill(index: number, fallback: string): string {
+  return (SERIES_COLORS[index % SERIES_COLORS.length] ?? fallback) + '22'
+}
+
+/**
+ * Strip the shared prefix from a set of labels so the differentiating suffix
+ * is what's shown. Example:
+ *   ["backend-podinfo-849bd668f9-4tzkg", "backend-podinfo-849bd668f9-5z79f"]
+ *   → ["4tzkg", "5z79f"]
+ *
+ * If stripping would leave empty strings or duplicates, falls back to the
+ * original labels — we'd rather show a long-but-correct label than a short
+ * misleading one.
+ */
+export function computeShortLabels(labels: string[]): string[] {
+  if (labels.length <= 1) return labels
+  let prefix = labels[0]
+  for (let i = 1; i < labels.length; i++) {
+    while (!labels[i].startsWith(prefix)) {
+      prefix = prefix.slice(0, -1)
+    }
+  }
+  const lastSep = Math.max(prefix.lastIndexOf('-'), prefix.lastIndexOf('/'))
+  if (lastSep > 0) prefix = prefix.slice(0, lastSep + 1)
+
+  const suffixes = labels.map(l => l.slice(prefix.length))
+  if (suffixes.some(s => s === '') || new Set(suffixes).size !== suffixes.length) return labels
+  return suffixes
+}

package/src/components/charts/format.ts

@@ -0,0 +1,41 @@
+// Compact human-readable formatters for chart values and timestamps.
+// Unit-tier breakpoints chosen so the rendered text stays short enough to
+// fit inside chart axis labels and tooltips at typical font sizes.
+
+export function formatMetricValue(value: number, unit: string): string {
+  if (value === 0) return '0'
+
+  switch (unit) {
+    case 'cores': {
+      if (value < 0.0001) return '< 0.1m'
+      if (value < 0.001) return `${(value * 1000).toFixed(1)}m`
+      if (value < 1) return `${(value * 1000).toFixed(0)}m`
+      return `${value.toFixed(2)}`
+    }
+    case 'bytes': {
+      if (value < 1) return '< 1 B'
+      if (value < 1024) return `${value.toFixed(0)} B`
+      if (value < 1024 * 1024) return `${(value / 1024).toFixed(1)} KiB`
+      if (value < 1024 * 1024 * 1024) return `${(value / (1024 * 1024)).toFixed(1)} MiB`
+      return `${(value / (1024 * 1024 * 1024)).toFixed(2)} GiB`
+    }
+    case 'bytes/s': {
+      if (value < 1) return '< 1 B/s'
+      if (value < 1024) return `${value.toFixed(0)} B/s`
+      if (value < 1024 * 1024) return `${(value / 1024).toFixed(1)} KiB/s`
+      if (value < 1024 * 1024 * 1024) return `${(value / (1024 * 1024)).toFixed(1)} MiB/s`
+      return `${(value / (1024 * 1024 * 1024)).toFixed(2)} GiB/s`
+    }
+    default:
+      if (value < 0.01) return value.toExponential(1)
+      if (value < 1) return value.toFixed(3)
+      if (value < 100) return value.toFixed(2)
+      if (value < 10000) return value.toFixed(0)
+      return `${(value / 1000).toFixed(1)}k`
+  }
+}
+
+export function formatTimestamp(unix: number): string {
+  const d = new Date(unix * 1000)
+  return d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
+}

package/src/components/charts/index.ts

@@ -0,0 +1,14 @@
+export { AreaChart } from './AreaChart'
+export { MetricsSummary } from './MetricsSummary'
+export { SeriesLegend } from './SeriesLegend'
+export { SERIES_COLORS, seriesColor, seriesFill, computeShortLabels } from './colors'
+export { formatMetricValue, formatTimestamp } from './format'
+export { computeSaturation } from './saturation'
+export type {
+  TimeSeriesPoint,
+  TimeSeries,
+  ReferenceLine,
+  // Deprecated Prom-prefixed aliases — see types.ts.
+  PrometheusDataPoint,
+  PrometheusSeries,
+} from './types'

package/src/components/charts/saturation.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+import { computeSaturation } from './saturation'
+import type { ReferenceLine, TimeSeries } from './types'
+
+const series = (values: number[]): TimeSeries => ({
+  labels: { pod: 'p' },
+  dataPoints: values.map((value, i) => ({ timestamp: i, value })),
+})
+
+const refRequest: ReferenceLine = { value: 100, label: 'request 100', kind: 'request' }
+const refLimit: ReferenceLine = { value: 200, label: 'limit 200', kind: 'limit' }
+
+describe('computeSaturation', () => {
+  it('returns undefined for empty series array', () => {
+    expect(computeSaturation([], [refLimit])).toBeUndefined()
+  })
+
+  it('returns undefined when all datapoints are zero', () => {
+    expect(computeSaturation([series([0, 0, 0])], [refLimit])).toBeUndefined()
+  })
+
+  it('returns undefined when no references are provided', () => {
+    expect(computeSaturation([series([10, 20, 30])], [])).toBeUndefined()
+  })
+
+  it('returns undefined when the chosen ref has zero value', () => {
+    const zeroLimit: ReferenceLine = { value: 0, label: 'limit 0', kind: 'limit' }
+    expect(computeSaturation([series([10, 20])], [zeroLimit])).toBeUndefined()
+  })
+
+  it('uses request when only request is present', () => {
+    const result = computeSaturation([series([25, 50])], [refRequest])
+    expect(result).toEqual({ ratio: 0.5, against: 'request' })
+  })
+
+  it('prefers limit over request when both are present', () => {
+    const result = computeSaturation([series([100])], [refRequest, refLimit])
+    // peak=100, against limit=200 → 0.5
+    expect(result).toEqual({ ratio: 0.5, against: 'limit' })
+  })
+
+  it('peaks across all data points and all series', () => {
+    const result = computeSaturation(
+      [series([10, 20]), series([5, 180, 30])],
+      [refLimit],
+    )
+    expect(result).toEqual({ ratio: 180 / 200, against: 'limit' })
+  })
+
+  it('handles ratio > 1 (workload exceeds its ceiling)', () => {
+    const result = computeSaturation([series([300])], [refLimit])
+    expect(result?.ratio).toBeCloseTo(1.5)
+    expect(result?.against).toBe('limit')
+  })
+
+  it('ignores zero-valued samples but uses positive ones for peak', () => {
+    const result = computeSaturation([series([0, 0, 50, 0])], [refLimit])
+    expect(result?.ratio).toBeCloseTo(0.25)
+  })
+})

package/src/components/charts/saturation.ts

@@ -0,0 +1,32 @@
+import type { ReferenceLine, TimeSeries } from './types'
+
+/**
+ * Compute panel saturation as a ratio of peak observed value to its
+ * operational ceiling. Picks the limit reference when both are present
+ * (limit is the OOM/throttle boundary; request is the scheduler reservation —
+ * the operationally meaningful number).
+ *
+ * Returns `undefined` for:
+ * - empty series (nothing to derive a peak from)
+ * - all-zero data (peak <= 0)
+ * - no usable reference (missing, or ref.value <= 0)
+ *
+ * Callers should treat `undefined` as "don't render a saturation chip".
+ */
+export function computeSaturation(
+  series: TimeSeries[],
+  refs: ReferenceLine[],
+): { ratio: number; against: 'limit' | 'request' } | undefined {
+  let peak = 0
+  for (const s of series) {
+    for (const dp of s.dataPoints) {
+      if (dp.value > peak) peak = dp.value
+    }
+  }
+  if (peak <= 0) return undefined
+  const limit = refs.find(r => r.kind === 'limit')
+  const request = refs.find(r => r.kind === 'request')
+  const ref = limit ?? request
+  if (!ref || ref.value <= 0) return undefined
+  return { ratio: peak / ref.value, against: limit ? 'limit' : 'request' }
+}