@titan-design/react-ui 0.10.0 → 0.12.0

package/src/components/custom/Fatigue/DualGhostSpark.stories.tsx

@@ -0,0 +1,258 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View, Text } from 'react-native'
+import { DualGhostSpark } from './DualGhostSpark'
+import { greyRamp } from '../../../theme/tokens/primitives'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { buildMockModel, TARGET_TEMPO_SECONDS } from './fatigue-mock'
+import { GRIND_THRESHOLD } from './fatigue-tokens'
+import type { RepVelocityCurve } from './fatigue-model'
+
+const PANEL_BG = greyRamp[950]
+const PAGE_BG = greyRamp[975]
+const t = getSemanticColors('dark')
+
+const meta: Meta<typeof DualGhostSpark> = {
+  title: 'Workout/Fatigue/Dual Ghost Spark',
+  component: DualGhostSpark,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Dual-Voltra ghost sparkline: ONE shared phase-coloured band with two mirrored blooms — the ' +
+          'LEFT device grows UP, the RIGHT device is the SAME bloom flipped `orientation="down"`. Both ' +
+          'wings share one time scale and one magnitude scale, so an L/R imbalance reads as bloom size ' +
+          'rather than as two independently normalized charts. Each wing is tinted INDEPENDENTLY by its ' +
+          'own current rep — silver while the rep stays controlled, warming through shades of red once ' +
+          'that side crosses the grind threshold — so one arm can go red while the other stays silver.',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof DualGhostSpark>
+
+/**
+ * The HEALTHY baseline both stories start from: an early, controlled, on-tempo stretch of
+ * the mock set (through rep 3), whose current rep sits well under `GRIND_THRESHOLD` and so
+ * tints SILVER. The deep end of the mock set is already grinding, so starting there would
+ * paint every story red regardless of what the story is trying to say.
+ */
+const HEALTHY = buildMockModel(2).velocityCurves
+
+/**
+ * A device that is GRINDING: its concentric collapses AND its grind signature crosses
+ * `GRIND_THRESHOLD` — the signal `ghostLineColor` reads to warm the line silver → red.
+ * Magnitude and tint move together because on the wall they have ONE cause: the rep is
+ * failing. Degradation ramps across the set so the ghost fan shows the side fading, and
+ * the current rep carries the full `grind`.
+ *
+ * @param grind the current rep's grindSignature. Below {@link GRIND_THRESHOLD} (0.35) the
+ *   line stays silver; 1 is a full collapse and the deepest red.
+ */
+function grinding(curves: RepVelocityCurve[], grind: number): RepVelocityCurve[] {
+  const last = Math.max(1, curves.length - 1)
+  return curves.map((c, i) => {
+    const g = grind * (i / last)
+    return {
+      ...c,
+      // Only the concentric slows — a grind is a failure to move the load, not a slow lower.
+      samples: c.samples.map((s) => ({
+        ...s,
+        velocityMps: s.phase === 'concentric' ? s.velocityMps * (1 - 0.6 * g) : s.velocityMps,
+      })),
+      grindSignature: Math.max(c.grindSignature, g),
+      tempoDeviation: Math.max(c.tempoDeviation ?? 0, g),
+    }
+  })
+}
+
+/** A weaker but still CONTROLLED device: the same reps at a fraction of the velocity —
+ *  a strength imbalance, not a collapse, so the tint signals stay untouched and silver. */
+function weaken(curves: RepVelocityCurve[], factor: number): RepVelocityCurve[] {
+  return curves.map((c) => ({
+    ...c,
+    samples: c.samples.map((s) => ({ ...s, velocityMps: s.velocityMps * factor })),
+  }))
+}
+
+/** A device still mid-rep: its current rep's stream is cut short. */
+function lagging(curves: RepVelocityCurve[], fraction: number): RepVelocityCurve[] {
+  const cur = curves[curves.length - 1]
+  const keep = Math.max(2, Math.round(cur.samples.length * fraction))
+  const samples = cur.samples.slice(0, keep)
+  const endMs = samples[samples.length - 1].tMs
+  return [
+    ...curves.slice(0, -1),
+    {
+      ...cur,
+      samples,
+      phaseSegments: cur.phaseSegments
+        .filter((s) => s.startMs < endMs)
+        .map((s) => ({ ...s, endMs: Math.min(s.endMs, endMs) })),
+    },
+  ]
+}
+
+const label = (s: string) => (
+  <Text
+    style={{ fontSize: 9, letterSpacing: 1, fontFamily: 'monospace', color: t['text-tertiary'] }}
+  >
+    {s}
+  </Text>
+)
+
+const panel = (caption: string, child: React.ReactNode) => (
+  <View style={{ gap: 8, alignItems: 'flex-start' }}>
+    {label(caption)}
+    <View style={{ width: 400, backgroundColor: PANEL_BG, borderRadius: 12, padding: 16 }}>
+      {child}
+    </View>
+  </View>
+)
+
+const page = (children: React.ReactNode) => (
+  <View
+    style={{
+      backgroundColor: PAGE_BG,
+      padding: 28,
+      gap: 24,
+      flexDirection: 'row',
+      flexWrap: 'wrap',
+      alignItems: 'flex-start',
+    }}
+  >
+    {children}
+  </View>
+)
+
+/** Both devices moving the same load the same way, both still in control — the blooms
+ *  mirror each other and BOTH wings read silver. This is the healthy baseline. */
+export const Symmetric: Story = {
+  render: () =>
+    page(
+      panel(
+        'SYMMETRIC · MATCHED DEVICES · BOTH SILVER',
+        <DualGhostSpark
+          left={HEALTHY}
+          right={HEALTHY}
+          width={360}
+          height={232}
+          targetTempoSeconds={TARGET_TEMPO_SECONDS}
+        />
+      )
+    ),
+}
+
+/** The money shot: the LEFT arm holds its rep and stays SILVER while the RIGHT arm's
+ *  concentric collapses — it crosses the grind threshold, so its wing warms into RED and,
+ *  because both wings share ONE magnitude scale, shrinks at the same time. */
+export const AsymmetricLeftRight: Story = {
+  render: () =>
+    page(
+      panel(
+        'ASYMMETRIC · LEFT SILVER · RIGHT GRINDING RED',
+        <DualGhostSpark
+          targetTempoSeconds={TARGET_TEMPO_SECONDS}
+          left={HEALTHY}
+          right={grinding(HEALTHY, 0.85)}
+          width={360}
+          height={232}
+          leftLabel="LEFT ARM"
+          rightLabel="RIGHT ARM"
+        />
+      )
+    ),
+}
+
+/** A strength imbalance with control intact: the right device only reaches ~55% of the
+ *  left's velocity, so its bloom is visibly smaller — but nothing is FAILING, so both
+ *  wings stay silver. The contrast with {@link AsymmetricLeftRight} is the point: bloom
+ *  size reads output, tint reads control, and they are independent readouts. */
+export const AsymmetricControlled: Story = {
+  render: () =>
+    page(
+      panel(
+        'ASYMMETRIC · RIGHT AT ~55% VELOCITY · BOTH STILL SILVER',
+        <DualGhostSpark
+          targetTempoSeconds={TARGET_TEMPO_SECONDS}
+          left={HEALTHY}
+          right={weaken(HEALTHY, 0.55)}
+          width={360}
+          height={232}
+          leftLabel="LEFT ARM"
+          rightLabel="RIGHT ARM"
+        />
+      )
+    ),
+}
+
+/** One side lagging: the right device is still mid-rep, so its line stops short of the
+ *  left's and the band goes idle where the two devices no longer share a phase. Both sides
+ *  are CONTROLLED, so both read silver — the only difference here is temporal. */
+export const OneSideLagging: Story = {
+  render: () =>
+    page(
+      panel(
+        'LAGGING · RIGHT STILL MID-REP · BOTH CONTROLLED',
+        <DualGhostSpark
+          left={HEALTHY}
+          right={lagging(HEALTHY, 0.6)}
+          width={360}
+          height={232}
+          targetTempoSeconds={TARGET_TEMPO_SECONDS}
+        />
+      )
+    ),
+}
+
+/** The tint ramp itself, one panel per step: the LEFT arm is held healthy as a silver
+ *  reference while the RIGHT arm's grind signature is walked from controlled up to a full
+ *  collapse. The first two steps sit BELOW `GRIND_THRESHOLD` and stay silver (dimming a
+ *  touch as tempo drifts); every step at or above it is a shade of red. */
+export const TintRange: Story = {
+  render: () =>
+    page(
+      <>
+        {[0, 0.2, GRIND_THRESHOLD, 0.55, 0.8, 1].map((grind) => (
+          <View key={grind}>
+            {panel(
+              `RIGHT GRIND ${grind.toFixed(2)} · ${grind < GRIND_THRESHOLD ? 'CONTROLLED · SILVER' : 'GRINDING · RED'}`,
+              <DualGhostSpark
+                targetTempoSeconds={TARGET_TEMPO_SECONDS}
+                left={HEALTHY}
+                right={grinding(HEALTHY, grind)}
+                width={360}
+                height={232}
+                leftLabel="LEFT · HEALTHY"
+                rightLabel={`RIGHT · GRIND ${grind.toFixed(2)}`}
+              />
+            )}
+          </View>
+        ))}
+      </>
+    ),
+}
+
+/** No data on either device — a reserved empty box, no axis furniture. */
+export const Empty: Story = {
+  render: () =>
+    page(
+      <>
+        {panel(
+          'EMPTY · NO REPS ON EITHER DEVICE',
+          <DualGhostSpark left={[]} right={[]} width={360} height={232} />
+        )}
+        {panel(
+          'SINGLE-SIDED · ONLY THE LEFT DEVICE BOUND',
+          <DualGhostSpark
+            left={HEALTHY}
+            right={[]}
+            width={360}
+            height={232}
+            targetTempoSeconds={TARGET_TEMPO_SECONDS}
+          />
+        )}
+      </>
+    ),
+}

package/src/components/custom/Fatigue/DualGhostSpark.test.tsx

@@ -0,0 +1,138 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { DualGhostSpark, mergePhaseSegments } from './DualGhostSpark'
+import { buildMockModel } from './fatigue-mock'
+import type { PhaseSegment, RepVelocityCurve } from './fatigue-model'
+
+const CURVES = buildMockModel(5).velocityCurves
+
+function scaled(curves: RepVelocityCurve[], factor: number): RepVelocityCurve[] {
+  return curves.map((c) => ({
+    ...c,
+    samples: c.samples.map((s) => ({ ...s, velocityMps: s.velocityMps * factor })),
+  }))
+}
+
+/** On-curve points of a smoothPath `d`: the `M` point then each cubic's endpoint. */
+function anchors(d: string): Array<[number, number]> {
+  const nums = (d.match(/-?\d+(?:\.\d+)?/g) ?? []).map(Number)
+  const pairs: Array<[number, number]> = []
+  for (let i = 0; i + 1 < nums.length; i += 2) pairs.push([nums[i], nums[i + 1]])
+  return pairs.filter((_, i) => i === 0 || i % 3 === 0)
+}
+
+/** The current (tinted) line of one wing — the last path drawn in its group. */
+function wingLine(container: HTMLElement, side: 'left' | 'right'): Array<[number, number]> {
+  const paths = container.querySelectorAll(`[data-testid="dual-ghost-bloom-${side}"] path`)
+  const d = paths[paths.length - 1].getAttribute('d') ?? ''
+  return anchors(d)
+}
+
+const ySpan = (pts: Array<[number, number]>) =>
+  Math.max(...pts.map((p) => p[1])) - Math.min(...pts.map((p) => p[1]))
+const xMax = (pts: Array<[number, number]>) => Math.max(...pts.map((p) => p[0]))
+
+function renderDual(left: RepVelocityCurve[], right: RepVelocityCurve[]) {
+  return render(<DualGhostSpark left={left} right={right} width={360} height={232} />)
+}
+
+describe('DualGhostSpark', () => {
+  it('renders both device blooms for a populated dual set', () => {
+    const { container } = renderDual(CURVES, CURVES)
+    expect(screen.getByTestId('dual-ghost-spark')).toBeInTheDocument()
+    expect(container.querySelector('[data-testid="dual-ghost-bloom-left"]')).toBeInTheDocument()
+    expect(container.querySelector('[data-testid="dual-ghost-bloom-right"]')).toBeInTheDocument()
+  })
+
+  it('draws exactly ONE shared band for the two blooms', () => {
+    const { container } = renderDual(CURVES, CURVES)
+    expect(container.querySelectorAll('[data-testid="ghost-band-floor"]')).toHaveLength(1)
+    expect(screen.getByText('ECC')).toBeInTheDocument()
+    expect(screen.getByText('CON')).toBeInTheDocument()
+  })
+
+  it('mirrors the wings: the left bloom stays above the band, the right below', () => {
+    const { container } = renderDual(CURVES, CURVES)
+    const l = wingLine(container, 'left')
+    const r = wingLine(container, 'right')
+    expect(Math.max(...l.map((p) => p[1]))).toBeLessThan(Math.min(...r.map((p) => p[1])))
+    // Each wing starts at zero velocity ON its baseline and grows away from the band.
+    expect(l[0][1]).toBe(Math.max(...l.map((p) => p[1])))
+    expect(r[0][1]).toBe(Math.min(...r.map((p) => p[1])))
+  })
+
+  it('gives matched devices identical bloom extents (one magnitude scale)', () => {
+    const { container } = renderDual(CURVES, CURVES)
+    expect(ySpan(wingLine(container, 'left'))).toBeCloseTo(ySpan(wingLine(container, 'right')), 1)
+  })
+
+  it('scales a weaker device DOWN instead of re-normalizing it to its own wing', () => {
+    const { container } = renderDual(CURVES, scaled(CURVES, 0.5))
+    const ratio = ySpan(wingLine(container, 'left')) / ySpan(wingLine(container, 'right'))
+    expect(ratio).toBeGreaterThan(1.9)
+    expect(ratio).toBeLessThan(2.1)
+  })
+
+  it('shares one time scale — a shorter side ends earlier, it is not stretched to full width', () => {
+    const short = CURVES.map((c) => ({
+      ...c,
+      samples: c.samples.slice(0, Math.round(c.samples.length * 0.5)),
+    }))
+    const { container } = renderDual(CURVES, short)
+    expect(xMax(wingLine(container, 'right'))).toBeLessThan(xMax(wingLine(container, 'left')) * 0.7)
+  })
+
+  it('draws no band furniture past the end of the phase runs', () => {
+    const { container } = renderDual(CURVES, CURVES)
+    const right = (r: Element) =>
+      Number(r.getAttribute('x') ?? 0) + Number(r.getAttribute('width') ?? 0)
+    const floor = container.querySelector('[data-testid="ghost-band-floor"]')!
+    const rects = Array.from(container.querySelectorAll('rect'))
+    expect(Math.max(...rects.map(right))).toBeCloseTo(right(floor), 1)
+  })
+
+  it('renders an empty box when neither device has reps', () => {
+    const { container } = renderDual([], [])
+    expect(screen.getByTestId('dual-ghost-spark')).toBeInTheDocument()
+    expect(container.querySelectorAll('path')).toHaveLength(0)
+  })
+
+  it('renders the bound side alone when only one device has reps', () => {
+    const { container } = renderDual(CURVES, [])
+    expect(container.querySelector('[data-testid="dual-ghost-bloom-left"]')).toBeInTheDocument()
+    expect(container.querySelector('[data-testid="dual-ghost-bloom-right"]')).toBeNull()
+  })
+})
+
+describe('mergePhaseSegments', () => {
+  const a: PhaseSegment[] = [
+    { phase: 'eccentric', startMs: 0, endMs: 1000 },
+    { phase: 'concentric', startMs: 1000, endMs: 2000 },
+  ]
+
+  it('keeps a phase both devices agree on', () => {
+    expect(mergePhaseSegments(a, a)).toEqual(a)
+  })
+
+  it('reads idle where the devices are in different phases', () => {
+    const b: PhaseSegment[] = [
+      { phase: 'eccentric', startMs: 0, endMs: 1400 },
+      { phase: 'concentric', startMs: 1400, endMs: 2000 },
+    ]
+    expect(mergePhaseSegments(a, b)).toEqual([
+      { phase: 'eccentric', startMs: 0, endMs: 1000 },
+      { phase: 'idle', startMs: 1000, endMs: 1400 },
+      { phase: 'concentric', startMs: 1400, endMs: 2000 },
+    ])
+  })
+
+  it('lets the covered side speak where the other has no stream yet', () => {
+    const short: PhaseSegment[] = [{ phase: 'eccentric', startMs: 0, endMs: 1000 }]
+    expect(mergePhaseSegments(a, short)).toEqual(a)
+  })
+
+  it('falls back to the only populated side', () => {
+    expect(mergePhaseSegments(a, [])).toEqual(a)
+    expect(mergePhaseSegments([], a)).toEqual(a)
+  })
+})

package/src/components/custom/Fatigue/DualGhostSpark.tsx

@@ -0,0 +1,208 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+/**
+ * DualGhostSpark — the DUAL-VOLTRA ghost sparkline: ONE shared {@link GhostBand} with TWO
+ * {@link GhostBloom}s mirrored around it, the LEFT device blooming UP and the RIGHT device
+ * blooming DOWN. Up/down is spent on DEVICE identity, so phase rides the band COLOUR alone
+ * (magenta ecc / cyan con) with the ECC / CON labels INSIDE the band.
+ *
+ * It is built exactly the way the single {@link GhostSpark} is — the same band, the same
+ * bloom, the bottom one just `orientation="down"`. There is no forked path / band / tint
+ * code, so any bloom improvement (the paper-inspired line ground, the silver→red tint)
+ * reaches the dual for free; single↔dual drift is structurally impossible rather than
+ * merely avoided. (The ghost analogue of the diverging VelocityStrip = two composed
+ * VelocityStrips.)
+ *
+ * Both wings share ONE time scale and ONE magnitude scale (a single `vmax` over every
+ * sample on both sides, and equal wing heights), so an L/R asymmetry reads as BLOOM SIZE.
+ * Per-side scales would let a weak side fill its wing and hide the imbalance.
+ *
+ * Layout is the locked B3 exploration
+ * (`lab/north-star/DualGhostLine.exploration.stories.tsx`): centred band + silver line.
+ */
+import { View } from 'react-native'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { alpha } from '../../../utils/colors'
+import { FONT_UI, ghostLineColor, clamp01 } from './fatigue-tokens'
+import { GhostBand, BAND_H, BAND_GAP } from './GhostBand'
+import type { TempoTuple } from './tempo-pacing'
+import { GhostBloom, type Pt } from './GhostBloom'
+import type { PhaseSegment, RepVelocityCurve } from './fatigue-model'
+
+const t = getSemanticColors('dark')
+
+export interface DualGhostSparkProps {
+  /** LEFT device per-rep curves, oldest first (last = current rep) — blooms UP. */
+  left: RepVelocityCurve[]
+  /** RIGHT device per-rep curves, oldest first (last = current rep) — blooms DOWN. */
+  right: RepVelocityCurve[]
+  width: number
+  /** Plot height in px. Default 232. */
+  height?: number
+  /** Caption above the upper wing. Default `LEFT`. */
+  leftLabel?: string
+  /** Caption below the lower wing. Default `RIGHT`. */
+  rightLabel?: string
+  /** Reveal the device captions. Default `true`. */
+  showDeviceLabels?: boolean
+  /** Prescribed tempo — turns on the shared band's phase pacing. */
+  targetTempoSeconds?: TempoTuple | null
+}
+
+/** The phase covering `ms`, or `null` where the side has no coverage. */
+function phaseAt(segments: PhaseSegment[], ms: number): PhaseSegment['phase'] | null {
+  const hit = segments.find((s) => ms >= s.startMs && ms < s.endMs)
+  return hit ? hit.phase : null
+}
+
+/**
+ * The SHARED band's phase runs: the two devices' current-rep runs reconciled onto one
+ * timeline. Where both sides are in the same phase the band takes it; where they are in
+ * DIFFERENT phases it reads `idle`, so the band never claims a phase the devices are not
+ * actually sharing. Where only one side has a stream at all (the other lags, or is still
+ * mid-rep), the covered side speaks for the band — a lagging device shouldn't grey out the
+ * phase the other device is genuinely in.
+ */
+export function mergePhaseSegments(a: PhaseSegment[], b: PhaseSegment[]): PhaseSegment[] {
+  if (a.length === 0) return b
+  if (b.length === 0) return a
+  const bounds = Array.from(new Set([...a, ...b].flatMap((s) => [s.startMs, s.endMs]))).sort(
+    (p, q) => p - q
+  )
+
+  const out: PhaseSegment[] = []
+  for (let i = 0; i < bounds.length - 1; i++) {
+    const startMs = bounds[i]
+    const endMs = bounds[i + 1]
+    if (endMs <= startMs) continue
+    const mid = (startMs + endMs) / 2
+    const pa = phaseAt(a, mid)
+    const pb = phaseAt(b, mid)
+    const phase = pa == null ? (pb ?? 'idle') : pb == null ? pa : pa === pb ? pa : 'idle'
+    const last = out[out.length - 1]
+    if (last && last.phase === phase && last.endMs === startMs) last.endMs = endMs
+    else out.push({ phase, startMs, endMs })
+  }
+  return out
+}
+
+/** Last sample time across a curve set, 0 when there is nothing to draw. */
+function lastTMs(curves: RepVelocityCurve[]): number {
+  return Math.max(0, ...curves.map((c) => c.samples[c.samples.length - 1]?.tMs ?? 0))
+}
+
+export function DualGhostSpark({
+  left,
+  right,
+  width,
+  height = 232,
+  leftLabel = 'LEFT',
+  rightLabel = 'RIGHT',
+  showDeviceLabels = true,
+  targetTempoSeconds = null,
+}: DualGhostSparkProps) {
+  const w = width
+  const h = height
+  const padL = 14
+  const padR = 14
+  const padTop = 22
+  const padBot = 22
+
+  if (left.length === 0 && right.length === 0) {
+    return <View testID="dual-ghost-spark" style={{ width: w, height: h }} />
+  }
+
+  // The band sits on the vertical midline; each bloom's baseline is offset off a band edge
+  // by BAND_GAP so a zero-velocity moment still sits clear of the band.
+  const mid = padTop + (h - padTop - padBot) / 2
+  const bandTop = mid - BAND_H / 2
+  const baseUp = bandTop - BAND_GAP
+  const baseDown = mid + BAND_H / 2 + BAND_GAP
+  // ONE wing height for both sides — the second half of the shared magnitude scale.
+  const wingH = Math.max(1, Math.min(baseUp - padTop, h - padBot - baseDown))
+
+  const allSamples = [...left, ...right].flatMap((c) => c.samples)
+  const vmax = Math.max(0.01, ...allSamples.map((s) => s.velocityMps)) * 1.06
+  const axisMaxT = Math.max(1, lastTMs(left), lastTMs(right)) * 1.04
+  const x = (ms: number) => padL + (ms / axisMaxT) * (w - padL - padR)
+  const mag = (v: number) => clamp01(v / vmax) * wingH
+
+  const toPts = (c: RepVelocityCurve): Pt[] => c.samples.map((s) => [x(s.tMs), mag(s.velocityMps)])
+  const wing = (curves: RepVelocityCurve[]) => {
+    const cur = curves[curves.length - 1]
+    return {
+      cur,
+      current: cur ? toPts(cur) : [],
+      ghosts: curves.slice(0, -1).map(toPts),
+      tint: cur ? ghostLineColor(cur.tempoDeviation, cur.grindSignature) : t['text-tertiary'],
+    }
+  }
+  const up = wing(left)
+  const down = wing(right)
+  const segments = mergePhaseSegments(up.cur?.phaseSegments ?? [], down.cur?.phaseSegments ?? [])
+
+  return (
+    <View testID="dual-ghost-spark" style={{ paddingHorizontal: 4 }}>
+      <svg width={w} height={h}>
+        {/* Same bloom, one prop flipped: LEFT grows UP, RIGHT grows DOWN. */}
+        {up.current.length > 0 && (
+          <g data-testid="dual-ghost-bloom-left">
+            <GhostBloom
+              current={up.current}
+              ghosts={up.ghosts}
+              tint={up.tint}
+              baseline={baseUp}
+              orientation="up"
+            />
+          </g>
+        )}
+        {down.current.length > 0 && (
+          <g data-testid="dual-ghost-bloom-right">
+            <GhostBloom
+              current={down.current}
+              ghosts={down.ghosts}
+              tint={down.tint}
+              baseline={baseDown}
+              orientation="down"
+            />
+          </g>
+        )}
+
+        {/* the ONE shared phase-coloured band, on top — ECC / CON labelled inside. */}
+        <GhostBand
+          segments={segments}
+          x={x}
+          top={bandTop}
+          showLabels
+          labelColor={alpha(t['text-primary'], 0.92)}
+          targetTempoSeconds={targetTempoSeconds}
+        />
+        {showDeviceLabels && (
+          <>
+            <text
+              x={padL}
+              y={padTop - 9}
+              fontSize={9}
+              fontWeight={800}
+              letterSpacing={1}
+              fontFamily={FONT_UI}
+              fill={t['text-tertiary']}
+            >
+              {leftLabel}
+            </text>
+            <text
+              x={padL}
+              y={h - padBot + 15}
+              fontSize={9}
+              fontWeight={800}
+              letterSpacing={1}
+              fontFamily={FONT_UI}
+              fill={t['text-tertiary']}
+            >
+              {rightLabel}
+            </text>
+          </>
+        )}
+      </svg>
+    </View>
+  )
+}

package/src/components/custom/Fatigue/FatigueLights.stories.tsx

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View, Text } from 'react-native'
+import { FatigueLights } from './FatigueLights'
+import { greyRamp } from '../../../theme/tokens/primitives'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { FATIGUE_STATES } from './fatigue-mock'
+
+const PAGE_BG = greyRamp[975]
+const t = getSemanticColors('dark')
+
+const meta: Meta<typeof FatigueLights> = {
+  title: 'Workout/Fatigue/Fatigue Lights',
+  component: FatigueLights,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'The three VEL/ROM/TEMPO "why" dots behind the verdict. Composes the shared `StatusDot` ' +
+          '(glow) inside a `Tooltip` that reveals the dimension detail on hover. `dimensions === null` ' +
+          '⇒ three neutral dots (warming up).',
+      },
+    },
+  },
+  argTypes: { spread: { control: 'boolean' } },
+}
+export default meta
+type Story = StoryObj<typeof FatigueLights>
+
+export const AcrossStates: Story = {
+  render: () => (
+    <View style={{ backgroundColor: PAGE_BG, padding: 28, gap: 18 }}>
+      {FATIGUE_STATES.map((s) => (
+        <View key={s.name} style={{ gap: 6 }}>
+          <Text
+            style={{
+              fontSize: 9,
+              letterSpacing: 1,
+              fontFamily: 'monospace',
+              color: t['text-tertiary'],
+            }}
+          >
+            {s.name}
+          </Text>
+          <FatigueLights dimensions={s.model.verdict?.dimensions ?? null} />
+        </View>
+      ))}
+      <View style={{ gap: 6 }}>
+        <Text
+          style={{
+            fontSize: 9,
+            letterSpacing: 1,
+            fontFamily: 'monospace',
+            color: t['text-tertiary'],
+          }}
+        >
+          WARMING UP
+        </Text>
+        <FatigueLights dimensions={null} />
+      </View>
+    </View>
+  ),
+}
+
+/** Spread evenly across a fixed width (the in-card layout). */
+export const Spread: Story = {
+  render: () => (
+    <View style={{ backgroundColor: PAGE_BG, padding: 28 }}>
+      <View style={{ width: 280 }}>
+        <FatigueLights dimensions={FATIGUE_STATES[3].model.verdict?.dimensions ?? null} spread />
+      </View>
+    </View>
+  ),
+}