@titan-design/react-ui 0.9.3 → 0.11.0

package/src/components/custom/Fatigue/fatigue-mock.ts

@@ -0,0 +1,268 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+/**
+ * Realistic mock {@link LiveFatigueModel}s for the Fatigue family stories + tests — a
+ * fatiguing 8-rep cable chest press taken deep (velocity decays, ROM shrinks, tempo
+ * degrades; reps 4 & 7 are cheats). Ported from the design-lab specimen so the
+ * hardened components render against the same shape the wall will feed them. NOT
+ * shipped in app bundles — story/test fixture only.
+ */
+import type {
+  FatigueVerdict,
+  LiveFatigueModel,
+  PhaseSegment,
+  RepVelocityCurve,
+  SamplePhase,
+  VelocitySample,
+} from './fatigue-model'
+
+interface RepSpec {
+  romMm: number
+  eccMs: number
+  pBMs: number
+  conMs: number
+  pTMs: number
+  eccControl: number
+  conPower: number
+}
+
+const SPECS: RepSpec[] = [
+  { romMm: 900, eccMs: 2600, pBMs: 420, conMs: 950, pTMs: 300, eccControl: 0.95, conPower: 0.9 },
+  { romMm: 895, eccMs: 2650, pBMs: 380, conMs: 1000, pTMs: 250, eccControl: 0.94, conPower: 0.86 },
+  { romMm: 880, eccMs: 2500, pBMs: 340, conMs: 1100, pTMs: 160, eccControl: 0.9, conPower: 0.78 },
+  { romMm: 715, eccMs: 1300, pBMs: 120, conMs: 900, pTMs: 90, eccControl: 0.34, conPower: 0.82 },
+  { romMm: 840, eccMs: 2300, pBMs: 300, conMs: 1500, pTMs: 90, eccControl: 0.85, conPower: 0.44 },
+  { romMm: 800, eccMs: 2000, pBMs: 240, conMs: 1750, pTMs: 80, eccControl: 0.68, conPower: 0.34 },
+  { romMm: 645, eccMs: 1200, pBMs: 100, conMs: 1650, pTMs: 70, eccControl: 0.3, conPower: 0.4 },
+  { romMm: 600, eccMs: 1250, pBMs: 70, conMs: 2300, pTMs: 60, eccControl: 0.34, conPower: 0.24 },
+]
+
+/** Prescribed tempo (ms per phase). */
+const TARGET = { ecc: 2600, pauseBottom: 400, con: 950, pauseTop: 280 }
+export const TARGET_TEMPO_SECONDS: [number, number, number, number] = [
+  TARGET.ecc / 1000,
+  TARGET.pauseBottom / 1000,
+  TARGET.con / 1000,
+  TARGET.pauseTop / 1000,
+]
+
+type LabPhase = 'ecc' | 'pauseBottom' | 'con' | 'pauseTop'
+// Both prescribed pauses are HOLDS (deliberate, under load), not idle dead time — the
+// lab's tempo prescribes them, so the band names them.
+const LAB_TO_MODEL: Record<LabPhase, SamplePhase> = {
+  ecc: 'eccentric',
+  pauseBottom: 'hold',
+  con: 'concentric',
+  pauseTop: 'hold',
+}
+
+function clamp(v: number, lo: number, hi: number): number {
+  return Math.min(hi, Math.max(lo, v))
+}
+function hashNoise(i: number): number {
+  const x = Math.sin(i * 127.1 + 11.7) * 43758.5453
+  return x - Math.floor(x)
+}
+function eccVelMm(u: number, s: RepSpec): number {
+  const mean = s.romMm / (s.eccMs / 1000)
+  const peak = mean * (Math.PI / 2)
+  const skew = 0.5 - (1 - s.eccControl) * 0.22
+  const sharp = 1 + (1 - s.eccControl) * 1.3
+  const hump = Math.pow(Math.sin(Math.PI * Math.pow(u, skew)), sharp)
+  return peak * hump * (1 + (1 - s.eccControl) * 0.7)
+}
+function conVelMm(u: number, s: RepSpec): number {
+  const mean = s.romMm / (s.conMs / 1000)
+  const peak = mean * (Math.PI / 2)
+  const skew = 0.5 - s.conPower * 0.18
+  const stick = (1 - s.conPower) * 0.32 * Math.exp(-Math.pow((u - 0.46) / 0.16, 2))
+  const shape = Math.max(0.02, Math.sin(Math.PI * Math.pow(u, skew)) - stick)
+  return peak * shape * (0.72 + s.conPower * 0.5)
+}
+
+function genRep(spec: RepSpec, repNumber: number): RepVelocityCurve {
+  const segs: Array<{ phase: LabPhase; dur: number }> = [
+    { phase: 'ecc', dur: spec.eccMs },
+    { phase: 'pauseBottom', dur: spec.pBMs },
+    { phase: 'con', dur: spec.conMs },
+    { phase: 'pauseTop', dur: spec.pTMs },
+  ]
+  const total = spec.eccMs + spec.pBMs + spec.conMs + spec.pTMs
+  const dt = 1000 / 11
+  const samples: VelocitySample[] = []
+  const segments: PhaseSegment[] = []
+  let n = 0
+  for (let time = 0; time <= total + 1; time += dt) {
+    let acc = 0
+    let phase: LabPhase = 'pauseTop'
+    let u = 0
+    for (let k = 0; k < segs.length; k++) {
+      if (time < acc + segs[k].dur || k === segs.length - 1) {
+        phase = segs[k].phase
+        u = Math.min(1, Math.max(0, (time - acc) / Math.max(segs[k].dur, 1)))
+        break
+      }
+      acc += segs[k].dur
+    }
+    let velMm = 0
+    if (phase === 'ecc') velMm = eccVelMm(u, spec)
+    else if (phase === 'con') velMm = conVelMm(u, spec)
+    velMm *= 1 + (hashNoise(n) - 0.5) * 0.05
+    n += 1
+    samples.push({
+      tMs: Math.round(time),
+      velocityMps: Math.abs(velMm) / 1000,
+      phase: LAB_TO_MODEL[phase],
+    })
+  }
+  // Contiguous phase runs (bridge the seam so segments abut).
+  samples.forEach((s) => {
+    const last = segments[segments.length - 1]
+    if (!last || last.phase !== s.phase)
+      segments.push({ phase: s.phase, startMs: s.tMs, endMs: s.tMs })
+    else last.endMs = s.tMs
+  })
+  // tempoDeviation — normalized concentric-duration deviation from prescribed con.
+  const tempoDeviation = clamp(Math.abs(spec.conMs - TARGET.con) / TARGET.con, 0, 1)
+  // grindSignature — mid-concentric collapse; low conPower = grinding (cheats stay low, they're fast).
+  const grindSignature = clamp((1 - spec.conPower) * 1.1, 0, 1)
+  return { repNumber, samples, phaseSegments: segments, tempoDeviation, grindSignature }
+}
+
+const CURVES: RepVelocityCurve[] = SPECS.map((s, i) => genRep(s, i + 1))
+
+/** Per-rep RPE estimate through the fatiguing set (the cheat rep 4 dips). */
+const RPE: Array<number | null> = [null, 6.5, 7.5, 7, 8.5, 9, 9.5, 10]
+
+/** Working ROM standard (metres): trimmed peak — drop rep 1 + the current rep. `null` under 3 reps. */
+function workingStandard(current: number): number | null {
+  const trimmed = SPECS.slice(1, current).map((s) => s.romMm / 1000)
+  if (trimmed.length === 0) return null
+  return Math.max(...trimmed)
+}
+
+/**
+ * Build a mock model for the set truncated at `current` (0-based rep index). Pass a
+ * `verdict` / `rpe` to override the plausible derived read (used by the state showcase).
+ */
+export function buildMockModel(
+  current: number,
+  overrides?: {
+    rpe?: number | null
+    verdict?: FatigueVerdict | null
+    /** Override the plan. Pass `undefined` explicitly for the no-plan-attached case. */
+    plannedReps?: number
+  }
+): LiveFatigueModel {
+  const spec = SPECS[current]
+  const working = workingStandard(current)
+  const rpe = overrides && 'rpe' in overrides ? (overrides.rpe ?? null) : (RPE[current] ?? null)
+  const verdict = overrides && 'verdict' in overrides ? (overrides.verdict ?? null) : null
+  const plannedReps =
+    overrides && 'plannedReps' in overrides ? overrides.plannedReps : MOCK_PLANNED_REPS
+  return {
+    rpe,
+    repsInReserve: rpe == null ? null : Math.max(0, Math.round(10 - rpe)),
+    verdict,
+    romProgression: SPECS.slice(0, current + 1).map((s, i) => ({
+      repNumber: i + 1,
+      romM: s.romMm / 1000,
+    })),
+    plannedReps,
+    romWorkingStandardM: working,
+    romShortThresholdM: working != null ? working * 0.75 : null,
+    velocityCurves: CURVES.slice(0, current + 1),
+    tempoSeconds: [spec.eccMs / 1000, spec.pBMs / 1000, spec.conMs / 1000, spec.pTMs / 1000],
+    targetTempoSeconds: TARGET_TEMPO_SECONDS,
+  }
+}
+
+/**
+ * The WHOLE panel's input for a set truncated at `current` — model, velocity and header
+ * from one rep count and one truncation point.
+ *
+ * The panel feeds two components that each draw their own upcoming-rep remainder, so
+ * assembling their props separately is how the two halves drift apart. Build both here
+ * or they will disagree again.
+ */
+export function buildMockPanelState(
+  current: number,
+  overrides?: { rpe?: number | null; verdict?: FatigueVerdict | null }
+): {
+  model: LiveFatigueModel
+  velocity: { velocities: number[]; targetReps: number; liveRepIndex: number }
+  header: typeof MOCK_HEADER
+} {
+  const model = buildMockModel(current, overrides)
+  return {
+    model,
+    velocity: {
+      // Same truncation as the model's romProgression / velocityCurves.
+      velocities: MOCK_MEAN_VELOCITIES.slice(0, current + 1),
+      targetReps: MOCK_PLANNED_REPS,
+      liveRepIndex: current,
+    },
+    header: { ...MOCK_HEADER, meta: `SET 3 · REP ${current + 1} / ${MOCK_PLANNED_REPS}` },
+  }
+}
+
+/** Per-rep MEAN concentric velocity (m/s) for the velocity hero (mm/ms == m/s). */
+export const MOCK_MEAN_VELOCITIES: number[] = SPECS.map((s) => s.romMm / s.conMs)
+
+/**
+ * The prescribed rep count for the mock set — ONE number for the whole family.
+ *
+ * The fatigue card's ROM chart and the velocity hero beside it both draw an
+ * upcoming-rep remainder, from `plannedReps` and `targetReps` respectively. Those
+ * are separate props on separate components, so a story that hardcodes one and
+ * leaves the other unset puts two different rep counts side by side on one panel.
+ * Derive both from here.
+ */
+export const MOCK_PLANNED_REPS = SPECS.length
+
+const V = (
+  state: FatigueVerdict['state'],
+  tone: FatigueVerdict['tone'],
+  vel: FatigueVerdict['dimensions']['velocityLoss'],
+  rom: FatigueVerdict['dimensions']['rom'],
+  tempo: FatigueVerdict['dimensions']['tempo']
+): FatigueVerdict => ({
+  state,
+  tone,
+  dimensions: { velocityLoss: vel, rom, tempo },
+})
+
+/** The four verdict states, each a full plausible model — the "Live states" showcase. */
+export const FATIGUE_STATES: Array<{ name: string; current: number; model: LiveFatigueModel }> = [
+  {
+    name: 'GOOD · early set',
+    current: 1,
+    model: buildMockModel(1, { rpe: 6, verdict: V('good', 'ok', 'ok', 'ok', 'ok') }),
+  },
+  {
+    name: 'SLOWING · bar speed dropping',
+    current: 2,
+    model: buildMockModel(2, { rpe: 7.5, verdict: V('slowing', 'warn', 'warn', 'ok', 'ok') }),
+  },
+  {
+    name: 'GRINDING · deep loss, clean form',
+    current: 5,
+    model: buildMockModel(5, { rpe: 9, verdict: V('grinding', 'warn', 'alarm', 'ok', 'ok') }),
+  },
+  {
+    name: 'FORM BREAKING DOWN · cheat rep',
+    current: 7,
+    model: buildMockModel(7, {
+      rpe: 10,
+      verdict: V('form-breakdown', 'alarm', 'alarm', 'alarm', 'alarm'),
+    }),
+  },
+]
+
+/** A warming-up (cold-start, < 2 reps) model — null verdict / RPE. */
+export const WARMING_UP_MODEL: LiveFatigueModel = buildMockModel(0, { rpe: null, verdict: null })
+
+export const MOCK_HEADER = {
+  title: 'Cable Chest Press',
+  subtitle: `Push A · Hypertrophy · 62 lb × ${MOCK_PLANNED_REPS} · tempo 2.6·0.4·0.95·0.28`,
+  meta: `SET 3 · REP ${MOCK_PLANNED_REPS} / ${MOCK_PLANNED_REPS}`,
+}

package/src/components/custom/Fatigue/fatigue-model.ts

@@ -0,0 +1,129 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+/**
+ * The live-fatigue data contract — a titan-local mirror of voltras-mcp's
+ * `LiveFatigueModel` (`src/dashboard/spa/live-page/fatigue-model.ts`). The card
+ * family consumes ONE typed `LiveFatigueModel` prop; the diverging/velocity hero
+ * beside it takes its own per-rep velocity array (that data is NOT on this model —
+ * it comes from the live-view velocity path).
+ *
+ * Units: every velocity is m/s and every distance is metres (converted from WA's
+ * native mm/s & mm at the mapper boundary). Tone/state vocabularies mirror WA's
+ * `DimensionTone` / `FatigueVerdictState` one-for-one so the real WA verdict drops
+ * straight in.
+ */
+
+/** Per-dimension status light. Mirrors WA's `DimensionTone`. */
+export type DimensionTone = 'ok' | 'warn' | 'alarm'
+
+/** Aggregated verdict state (drives the hero word). Mirrors WA's `FatigueVerdictState`. */
+export type FatigueVerdictState = 'good' | 'slowing' | 'grinding' | 'form-breakdown'
+
+/**
+ * Movement phase of one per-sample point — colours the ghost-spark zero-axis.
+ *
+ * `hold` is a DELIBERATE pause under load (WA's `MovementPhase.HOLD`) — the bottom/top
+ * holds a tempo prescription asks for. `idle` is undirected dead time. They were folded
+ * together until the band needed to name a hold; keep them apart, because "the lifter held
+ * the bottom for 400 ms" and "nothing happened" are different facts.
+ */
+export type SamplePhase = 'concentric' | 'eccentric' | 'hold' | 'idle'
+
+/** One per-sample point of a rep's velocity-time curve. */
+export interface VelocitySample {
+  /** Milliseconds since this rep's first sample. */
+  tMs: number
+  /** Instantaneous velocity MAGNITUDE, m/s (the ghost-spark signs it by `phase`). */
+  velocityMps: number
+  /** Movement phase at this sample — drives the phase-coloured zero-axis segment. */
+  phase: SamplePhase
+}
+
+/** A contiguous same-phase run within a rep's sample stream — one zero-axis segment. */
+export interface PhaseSegment {
+  phase: SamplePhase
+  /** Start offset, ms since the rep's first sample. */
+  startMs: number
+  /** End offset, ms since the rep's first sample. */
+  endMs: number
+}
+
+/**
+ * One rep's velocity-time curve for the ghost-spark (current rep solid, priors faded).
+ *
+ * The line tint is driven by TWO normalized per-rep signals (the "green-intensity
+ * control-aware" rule; the mapping lives in {@link ghostLineColor}):
+ * `grindSignature < 0.35` → stay green, intensity by `tempoDeviation` (brightest at
+ * 0 → deepest green at 1, hue held); otherwise → warm hue amber (at 0.35) → red (at
+ * 1.0) by `grindSignature`. A slow-but-smooth rep stays green (just deeper); only a
+ * stalling/collapsing rep warms.
+ */
+export interface RepVelocityCurve {
+  /** 1-based rep number. */
+  repNumber: number
+  /** Per-sample velocity-time points, in stream order. */
+  samples: VelocitySample[]
+  /** Contiguous phase runs, for the phase-coloured zero-axis. */
+  phaseSegments: PhaseSegment[]
+  /**
+   * Normalized concentric-duration deviation from the prescribed tempo, 0..1 (0 =
+   * on-tempo, 1 = well off). Drives GREEN INTENSITY when the rep is controlled.
+   * `null` when there is no prescribed tempo to compare against.
+   */
+  tempoDeviation: number | null
+  /**
+   * Normalized velocity COLLAPSE within the concentric, 0..1 (0 = smooth, 1 = full
+   * collapse). Warms the line hue amber→red past the control threshold. Always
+   * computed per rep; a rep with too few concentric samples reads `0`.
+   */
+  grindSignature: number
+}
+
+/** One per-rep point of the ROM-progression mini-chart. */
+export interface RepRomPoint {
+  /** 1-based rep number. */
+  repNumber: number
+  /** Concentric range of motion, metres. */
+  romM: number
+}
+
+/** The aggregated verdict + the three per-dimension lights (WA `getSetFatigueVerdict`). */
+export interface FatigueVerdict {
+  state: FatigueVerdictState
+  tone: DimensionTone
+  dimensions: {
+    velocityLoss: DimensionTone
+    rom: DimensionTone
+    tempo: DimensionTone
+  }
+}
+
+/**
+ * The always-on live fatigue card model for the current set. A `null` `verdict`
+ * means the set is warming up (cold start, < 2 reps) — the card renders neutral.
+ */
+export interface LiveFatigueModel {
+  /** Estimated RPE (exact, unrounded — the card rounds to 0.5). `null` under 2 reps. */
+  rpe: number | null
+  /** Reps in reserve = 10 − RPE. `null` when `rpe` is `null`. Carried for the contract; the card is RPE-led and does not render a reps-in-reserve line. */
+  repsInReserve: number | null
+  /** The verdict + three dimension lights. `null` = warming up. */
+  verdict: FatigueVerdict | null
+  /** ROM progression: per-rep ROM points (metres), ordered by rep. */
+  romProgression: RepRomPoint[]
+  /**
+   * Planned rep count from the prescription — the ROM chart draws the remainder as dashed
+   * to-do placeholders (the "N of M done" read). Absent/`undefined` when no plan is attached:
+   * there is genuinely no target then, and the gap must read as a gap — never defaulted.
+   */
+  plannedReps?: number
+  /** Working-range standard the ROM chart draws its reference line at (metres). `null` until ≥ 3 reps. */
+  romWorkingStandardM: number | null
+  /** Short-threshold line (metres) = 0.75 × working standard. `null` until the standard exists. */
+  romShortThresholdM: number | null
+  /** Ghost-spark: per-rep velocity-time curves, oldest first (last = current rep). */
+  velocityCurves: RepVelocityCurve[]
+  /** Current-rep tempo tuple `[ecc, pauseBottom, con, pauseTop]` seconds. `null` when no rep carries timing. */
+  tempoSeconds: [number, number, number, number] | null
+  /** Target tempo tuple, same ordering, from the prescription. `null` when none prescribed. */
+  targetTempoSeconds: [number, number, number, number] | null
+}

package/src/components/custom/Fatigue/fatigue-tokens.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest'
+import {
+  ghostLineColor,
+  auraForVerdict,
+  mixHex,
+  clamp01,
+  GRIND_THRESHOLD,
+  SILVER,
+  RED_LIGHT,
+  RED_MID,
+  RED_DEEP,
+} from './fatigue-tokens'
+
+describe('clamp01', () => {
+  it('clamps to [0,1]', () => {
+    expect(clamp01(-1)).toBe(0)
+    expect(clamp01(2)).toBe(1)
+    expect(clamp01(0.4)).toBe(0.4)
+  })
+})
+
+describe('mixHex', () => {
+  it('returns the endpoints at 0 and 1', () => {
+    expect(mixHex('#000000', '#ffffff', 0)).toBe('#000000')
+    expect(mixHex('#000000', '#ffffff', 1)).toBe('#ffffff')
+  })
+  it('mixes at the midpoint', () => {
+    expect(mixHex('#000000', '#ffffff', 0.5)).toBe('#808080')
+  })
+  it('expands 3-digit hex', () => {
+    expect(mixHex('#000', '#fff', 1)).toBe('#ffffff')
+  })
+})
+
+describe('ghostLineColor (control-aware silver/red)', () => {
+  const reds = [RED_LIGHT, RED_MID, RED_DEEP].map((c) => c.toLowerCase())
+
+  it('a controlled, on-tempo rep is silver', () => {
+    expect(ghostLineColor(0, 0.1).toLowerCase()).toBe(SILVER.toLowerCase())
+  })
+  it('a controlled but drifting rep dims toward grey — never a red', () => {
+    const drift = ghostLineColor(1, 0.1).toLowerCase()
+    expect(drift).not.toBe(SILVER.toLowerCase())
+    expect(reds).not.toContain(drift)
+  })
+  it('null tempo deviation is treated as on-tempo (silver)', () => {
+    expect(ghostLineColor(null, 0.1).toLowerCase()).toBe(SILVER.toLowerCase())
+  })
+  it('at the grind threshold it is light red', () => {
+    expect(ghostLineColor(0, GRIND_THRESHOLD).toLowerCase()).toBe(RED_LIGHT.toLowerCase())
+  })
+  it('the mid-severity collapse is mid red', () => {
+    // severity 0.5 ⇒ grind = threshold + 0.5·(1−threshold)
+    const grind = GRIND_THRESHOLD + 0.5 * (1 - GRIND_THRESHOLD)
+    expect(ghostLineColor(0, grind).toLowerCase()).toBe(RED_MID.toLowerCase())
+  })
+  it('a full collapse is deep red', () => {
+    expect(ghostLineColor(0, 1).toLowerCase()).toBe(RED_DEEP.toLowerCase())
+  })
+})
+
+describe('auraForVerdict', () => {
+  it('maps good/null → productive, form-breakdown → stop, else threshold', () => {
+    expect(auraForVerdict(null)).toBe('productive')
+    expect(auraForVerdict('good')).toBe('productive')
+    expect(auraForVerdict('slowing')).toBe('threshold')
+    expect(auraForVerdict('grinding')).toBe('threshold')
+    expect(auraForVerdict('form-breakdown')).toBe('stop')
+  })
+})

package/src/components/custom/Fatigue/fatigue-tokens.ts

@@ -0,0 +1,180 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+/**
+ * Shared tokens + pure colour helpers for the live-fatigue family. Everything here
+ * is token-sourced (semantic tokens / primitive ramps) — no literal surface hex — so
+ * the family inherits the surface-ramp refresh when it lands.
+ */
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { primitiveColors, primitiveRamps } from '../../../theme/tokens/primitives'
+import type { DimensionTone, FatigueVerdictState, SamplePhase } from './fatigue-model'
+
+const t = getSemanticColors('dark')
+
+export const FONT_HEAD = '"Space Grotesk", sans-serif'
+export const FONT_UI = '"Nunito Sans", sans-serif'
+export const FONT_MONO = 'monospace'
+
+/** Per-dimension tone → semantic status colour (the one language the dots + hero share). */
+export const TONE_COLOR: Record<DimensionTone, string> = {
+  ok: t['status-success'],
+  warn: t['status-warning'],
+  alarm: t['status-error'],
+}
+
+/** Verdict state → the hero word. */
+export const STATE_LABEL: Record<FatigueVerdictState, string> = {
+  good: 'Good',
+  slowing: 'Slowing',
+  grinding: 'Grinding',
+  'form-breakdown': 'Form breaking down',
+}
+
+/**
+ * The phase-identity colours for the ghost-spark phase BAND — the TempoDisplay
+ * language: eccentric magenta, concentric cyan, hold and idle in the grey family.
+ *
+ * The idle grey has to read as BAND MATERIAL (a pause the lifter held), not as a
+ * hole in the strip: at charcoal[300] it sat inside the surface-ramp's own value
+ * range (`surface-raised` #31302F) so a short pause between ECC and CON read as a
+ * gap. charcoal[200] clears every content plane while staying quieter than the two
+ * saturated phase tones, so the band reads contiguous and the phases still lead.
+ *
+ * `hold` stays GREY rather than taking a hue of its own. It was briefly amber, which
+ * was wrong for a reason worth recording: the phase-pacing tone (`pacingTone`) uses
+ * warning-amber for "ahead of target", so an amber phase hue collides with the semantic
+ * signal painted on top of it. Phase hues are deliberately non-semantic precisely so
+ * pacing can own success/warning/error. Grey also reads more like a hold — a held
+ * position is an absence of movement, not an event.
+ *
+ * Hold and idle are separated by VALUE rather than hue, plus the `HOLD` label and the
+ * fact that a hold PACES (it has a prescribed duration) while idle never fills:
+ *   unfilled hold  charcoal[300]  — darker than idle
+ *   idle           charcoal[200]
+ *   filled hold    charcoal[100]  — brighter than idle
+ * so a hold reads apart from dead time at any fill level, including the narrow runs
+ * where the label drops out.
+ */
+export const PHASE_AXIS_COLOR: Record<SamplePhase, string> = {
+  eccentric: primitiveRamps.magenta[800],
+  concentric: primitiveRamps.cyan[800],
+  hold: primitiveColors.charcoal[100],
+  idle: primitiveColors.charcoal[200],
+}
+
+/**
+ * The UNFILLED base a phase sits at before its pacing fill covers it — the same hue,
+ * pulled back. {@link PHASE_AXIS_COLOR} is the FILL, so a phase that runs its full
+ * prescribed duration ends up looking exactly as the band did before pacing existed;
+ * muting is only ever visible where the lifter is UNDER target.
+ *
+ * `idle` has no prescribed duration, never fills, and so its base is its colour.
+ */
+export const PHASE_AXIS_BASE_COLOR: Record<SamplePhase, string> = {
+  eccentric: primitiveRamps.magenta[950],
+  concentric: primitiveRamps.cyan[950],
+  hold: primitiveColors.charcoal[300],
+  idle: primitiveColors.charcoal[200],
+}
+
+/**
+ * Pacing tones for a label sitting INSIDE the band — ahead / on pace / over.
+ *
+ * Only ECC and CON carry labels, so the backgrounds these must survive are the eccentric
+ * and concentric fills and their muted bases. The binding one is the CONCENTRIC FILL
+ * (cyan[800]) — a mid-dark blue, so a legible tone on it has to stay fairly light.
+ *
+ * Ramp step **300** is the DEEPEST step at which all three clear 4.5:1:
+ *
+ *   worst-case contrast over {ecc, con} × {fill, base}   (worst is always conFill)
+ *     red[300]    4.91      red[400] = 3.59 — fails
+ *     amber[300]  5.48      amber[400] = 3.76 — fails
+ *     green[300]  5.16      green[400] = 4.15 — fails
+ *
+ * `over` cannot go deeper than this without losing legibility, which is a property of
+ * small light-on-dark text rather than a choice: the 3:1 large-text allowance needs ~18.7px
+ * bold and these labels are 8px. `status-error` (red[600]) measures 2.18:1 here.
+ *
+ * `ahead` and `onPace` land back on exactly the `status-warning` / `status-success` values;
+ * only `over` has to deviate from the semantic token.
+ *
+ * `PACING_TONE_MIN_CONTRAST` is asserted in `tempo-pacing.test.ts`, so a future ramp edit
+ * cannot quietly regress this.
+ */
+export const PACING_TONE = {
+  ahead: primitiveRamps.amber[300],
+  onPace: primitiveRamps.green[300],
+  over: primitiveRamps.red[300],
+} as const
+
+/** The floor every {@link PACING_TONE} must clear against any band background. */
+export const PACING_TONE_MIN_CONTRAST = 4.5
+
+// --- shared silver/red scheme (ROM chart + ghost-spark line) --------------------
+// One source of truth for the two quality readouts: SILVER when the rep is right,
+// SHADES OF RED when there's an issue. No greens, no ambers — those languages belong
+// to the verdict tones / velocity-loss bands, not here.
+/** On-track / at-or-above-working. */
+export const SILVER = primitiveColors.neutral[300]
+export const RED_LIGHT = primitiveRamps.red[400]
+export const RED_MID = primitiveRamps.red[600]
+export const RED_DEEP = primitiveRamps.red[800]
+
+/** Below this grind signature the rep is "controlled" → silver; at/above it goes red. */
+export const GRIND_THRESHOLD = 0.35
+/** A quiet grey the controlled line dims toward as it drifts (never a colour): a dimmed
+ *  cool grey in the SAME neutral family as SILVER, so a fully-drifted line reads dim-silver
+ *  rather than sinking toward black. Shared with the ROM chart. */
+export const DRIFT_GREY = primitiveColors.neutral[600]
+
+export function clamp01(v: number): number {
+  return Math.min(1, Math.max(0, v))
+}
+
+function hexToRgb(hex: string): [number, number, number] {
+  const h = hex.replace('#', '')
+  const f =
+    h.length === 3
+      ? h
+          .split('')
+          .map((c) => c + c)
+          .join('')
+      : h
+  return [parseInt(f.slice(0, 2), 16), parseInt(f.slice(2, 4), 16), parseInt(f.slice(4, 6), 16)]
+}
+
+/** Linear mix of two hex colours (`t` 0..1). Both inputs are token-sourced hex. */
+export function mixHex(a: string, b: string, ratio: number): string {
+  const [ar, ag, ab] = hexToRgb(a)
+  const [br, bg, bb] = hexToRgb(b)
+  const m = (x: number, y: number) => Math.round(x + (y - x) * clamp01(ratio))
+  return `#${[m(ar, br), m(ag, bg), m(ab, bb)]
+    .map((v) => v.toString(16).padStart(2, '0'))
+    .join('')}`
+}
+
+/**
+ * The ghost-spark current-line tint from the two control-aware signals — silver/red.
+ *
+ * A CONTROLLED rep (`grindSignature < GRIND_THRESHOLD`) stays SILVER, dimming a touch
+ * toward a quiet grey by `tempoDeviation` — a "drifting but not failing" cue that never
+ * becomes a colour. A COLLAPSING rep (at/above the threshold) goes through SHADES OF RED
+ * by severity: light → mid → deep as the collapse deepens.
+ */
+export function ghostLineColor(tempoDeviation: number | null, grindSignature: number): string {
+  if (grindSignature >= GRIND_THRESHOLD) {
+    const severity = clamp01((grindSignature - GRIND_THRESHOLD) / (1 - GRIND_THRESHOLD))
+    return severity < 0.5
+      ? mixHex(RED_LIGHT, RED_MID, severity * 2)
+      : mixHex(RED_MID, RED_DEEP, (severity - 0.5) * 2)
+  }
+  return mixHex(SILVER, DRIFT_GREY, (tempoDeviation ?? 0) * 0.55)
+}
+
+/** Verdict state → the {@link LiveAuraFrame} coaching-flood category. */
+export function auraForVerdict(
+  state: FatigueVerdictState | null
+): 'productive' | 'threshold' | 'stop' {
+  if (state == null || state === 'good') return 'productive'
+  if (state === 'form-breakdown') return 'stop'
+  return 'threshold'
+}

package/src/components/custom/Fatigue/index.ts

@@ -0,0 +1,41 @@
+// Live-fatigue component family — the aligned "Live panel v2" hardened into titan
+// components. See ./README.md for the composition tree + reuse audit.
+export { LiveFatiguePanel } from './LiveFatiguePanel'
+export type {
+  LiveFatiguePanelProps,
+  LiveFatiguePanelHeader,
+  LiveFatiguePanelVelocity,
+} from './LiveFatiguePanel'
+export { LiveFatigueCard, type LiveFatigueCardProps } from './LiveFatigueCard'
+export { VerdictHero, type VerdictHeroProps } from './VerdictHero'
+export { FatigueLights, type FatigueLightsProps } from './FatigueLights'
+export { RomProgressionChart, type RomProgressionChartProps } from './RomProgressionChart'
+export { GhostSpark, type GhostSparkProps } from './GhostSpark'
+export { DualGhostSpark, type DualGhostSparkProps, mergePhaseSegments } from './DualGhostSpark'
+export { GhostBand, type GhostBandProps, BAND_H, BAND_GAP } from './GhostBand'
+export { GhostBloom, type GhostBloomProps, type Pt, smoothPath } from './GhostBloom'
+export { VelocityHero, type VelocityHeroProps } from './VelocityHero'
+export {
+  ghostLineColor,
+  auraForVerdict,
+  TONE_COLOR,
+  STATE_LABEL,
+  GRIND_THRESHOLD,
+  SILVER,
+  DRIFT_GREY,
+  RED_LIGHT,
+  RED_MID,
+  RED_DEEP,
+  PHASE_AXIS_COLOR,
+} from './fatigue-tokens'
+export type {
+  LiveFatigueModel,
+  FatigueVerdict,
+  FatigueVerdictState,
+  DimensionTone,
+  SamplePhase,
+  VelocitySample,
+  PhaseSegment,
+  RepVelocityCurve,
+  RepRomPoint,
+} from './fatigue-model'