@titan-design/react-ui 0.10.0 → 0.12.0

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

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { FatigueLights } from './FatigueLights'
+import type { FatigueVerdict } from './fatigue-model'
+
+const dims: FatigueVerdict['dimensions'] = { velocityLoss: 'alarm', rom: 'warn', tempo: 'ok' }
+
+describe('FatigueLights', () => {
+  it('renders the three VEL/ROM/TEMPO labels', () => {
+    render(<FatigueLights dimensions={dims} />)
+    expect(screen.getByText('VEL')).toBeInTheDocument()
+    expect(screen.getByText('ROM')).toBeInTheDocument()
+    expect(screen.getByText('TEMPO')).toBeInTheDocument()
+  })
+
+  it('composes three StatusDot primitives', () => {
+    render(<FatigueLights dimensions={dims} />)
+    expect(screen.getAllByTestId('status-dot')).toHaveLength(3)
+  })
+
+  it('labels each dimension with its detail + status word', () => {
+    render(<FatigueLights dimensions={dims} />)
+    expect(screen.getByLabelText('Velocity loss, alarm')).toBeInTheDocument()
+    expect(screen.getByLabelText('ROM depth, watch')).toBeInTheDocument()
+    expect(screen.getByLabelText('Tempo, ok')).toBeInTheDocument()
+  })
+
+  it('renders neutral "warming up" lights when dimensions are null', () => {
+    render(<FatigueLights dimensions={null} />)
+    expect(screen.getByLabelText('Velocity loss, warming up')).toBeInTheDocument()
+    expect(screen.getAllByTestId('status-dot')).toHaveLength(3)
+  })
+})

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

@@ -0,0 +1,83 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+/**
+ * FatigueLights — the three "why" status dots (VEL · ROM · TEMPO) that stand behind
+ * the verdict word: the supporting reason the verdict reads the way it does. Each dot
+ * COMPOSES the shared {@link StatusDot} primitive (glow) wrapped in a {@link Tooltip}
+ * that reveals the dimension detail on hover.
+ *
+ * Warming up (`dimensions === null`) shows three neutral dots.
+ */
+import { View, Text } from 'react-native'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { StatusDot, type StatusDotVariant } from '../Workout/StatusDot'
+import { Tooltip } from '../../ui/tooltip/Tooltip'
+import { FONT_MONO } from './fatigue-tokens'
+import type { DimensionTone, FatigueVerdict } from './fatigue-model'
+
+const t = getSemanticColors('dark')
+
+/** Tone → the StatusDot variant (ok=success, warn=warning, alarm=error). */
+const TONE_VARIANT: Record<DimensionTone, StatusDotVariant> = {
+  ok: 'success',
+  warn: 'warning',
+  alarm: 'error',
+}
+const TONE_WORD: Record<DimensionTone, string> = { ok: 'ok', warn: 'watch', alarm: 'alarm' }
+
+export interface FatigueLightsProps {
+  /** The three per-dimension tones. `null` = warming up (all neutral). */
+  dimensions: FatigueVerdict['dimensions'] | null
+  /** Distribute the three lights evenly across the full width (space-between). Default false (left-grouped). */
+  spread?: boolean
+}
+
+function Light({
+  label,
+  tone,
+  detail,
+}: {
+  label: string
+  tone: DimensionTone | null
+  detail: string
+}) {
+  const variant: StatusDotVariant = tone ? TONE_VARIANT[tone] : 'neutral'
+  const word = tone ? TONE_WORD[tone] : 'warming up'
+  return (
+    <Tooltip label={`${detail} · ${word}`} placement="bottom">
+      <View
+        accessibilityLabel={`${detail}, ${word}`}
+        style={{ flexDirection: 'row', alignItems: 'center', gap: 5 }}
+      >
+        <StatusDot variant={variant} size="sm" glow />
+        <Text
+          style={{
+            fontSize: 9,
+            letterSpacing: 0.6,
+            fontFamily: FONT_MONO,
+            color: t['text-secondary'],
+          }}
+        >
+          {label}
+        </Text>
+      </View>
+    </Tooltip>
+  )
+}
+
+export function FatigueLights({ dimensions, spread = false }: FatigueLightsProps) {
+  return (
+    <View
+      testID="fatigue-lights"
+      style={{
+        flexDirection: 'row',
+        gap: spread ? 0 : 16,
+        alignItems: 'center',
+        justifyContent: spread ? 'space-between' : 'flex-start',
+      }}
+    >
+      <Light label="VEL" tone={dimensions?.velocityLoss ?? null} detail="Velocity loss" />
+      <Light label="ROM" tone={dimensions?.rom ?? null} detail="ROM depth" />
+      <Light label="TEMPO" tone={dimensions?.tempo ?? null} detail="Tempo" />
+    </View>
+  )
+}

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

@@ -0,0 +1,235 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { GhostBand, BAND_H, type GhostBandProps } from './GhostBand'
+import { PHASE_AXIS_COLOR, PHASE_AXIS_BASE_COLOR, PACING_TONE } from './fatigue-tokens'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+import type { PhaseSegment } from './fatigue-model'
+
+const t = getSemanticColors('dark')
+
+/** Phase runs with SEAMS between them — the shape the sample-derived model actually produces. */
+const segments: PhaseSegment[] = [
+  { phase: 'eccentric', startMs: 0, endMs: 1182 },
+  { phase: 'idle', startMs: 1273, endMs: 1600 },
+  { phase: 'concentric', startMs: 1691, endMs: 3545 },
+]
+
+const x = (ms: number) => 12 + (ms / 4000) * 300
+
+const band = (segs: PhaseSegment[] = segments, props: Partial<GhostBandProps> = {}) =>
+  render(
+    <svg>
+      <GhostBand segments={segs} x={x} top={0} height={BAND_H} {...props} />
+    </svg>
+  ).container
+
+const geom = (r: Element) => ({
+  x: Number(r.getAttribute('x')),
+  width: Number(r.getAttribute('width')),
+  fill: r.getAttribute('fill'),
+})
+
+/** The strip floor — the one rect sitting directly in the clipped group. */
+const floorOf = (c: HTMLElement) => geom(c.querySelector('g[clip-path] > rect')!)
+/** Per-run BASE rects — these carry the run's true geometry (full width). */
+const basesOf = (c: HTMLElement) =>
+  Array.from(c.querySelectorAll('[data-testid="ghost-band-base"]')).map(geom)
+/** Per-run FILL rects — width is the share of the run earned against target. */
+const fillsOf = (c: HTMLElement) =>
+  Array.from(c.querySelectorAll('[data-testid="ghost-band-fill"]')).map(geom)
+const labelsOf = (c: HTMLElement) =>
+  Array.from(c.querySelectorAll('text')).map((n) => ({
+    text: n.textContent,
+    fill: n.getAttribute('fill'),
+  }))
+
+/** A rep whose phases each run EXACTLY their prescribed duration. */
+const onPace: PhaseSegment[] = [
+  { phase: 'eccentric', startMs: 0, endMs: 2600 },
+  { phase: 'hold', startMs: 2600, endMs: 3000 },
+  { phase: 'concentric', startMs: 3000, endMs: 3950 },
+]
+const TEMPO: [number, number, number, number] = [2.6, 0.4, 0.95, 0.28]
+
+describe('GhostBand', () => {
+  it('draws a contiguous strip — each run butts against the next with no gap', () => {
+    const runs = basesOf(band())
+    runs.forEach((r, i) => {
+      const next = runs[i + 1]
+      if (next) expect(r.x + r.width).toBeCloseTo(next.x, 5)
+    })
+  })
+
+  it('floors the whole rep with the idle tone so a pause reads as band, not a hole', () => {
+    const floor = floorOf(band())
+    expect(floor.fill).toBe(PHASE_AXIS_COLOR.idle)
+    expect(floor.x).toBeCloseTo(x(0), 5)
+    expect(floor.x + floor.width).toBeCloseTo(x(3545), 5)
+  })
+
+  it('paints the pause run in the idle tone', () => {
+    expect(fillsOf(band()).map((r) => r.fill)).toEqual([
+      PHASE_AXIS_COLOR.eccentric,
+      PHASE_AXIS_COLOR.idle,
+      PHASE_AXIS_COLOR.concentric,
+    ])
+  })
+
+  it('renders nothing when every run is zero-width', () => {
+    const c = band([{ phase: 'idle', startMs: 500, endMs: 500 }])
+    expect(c.querySelectorAll('rect')).toHaveLength(0)
+  })
+
+  it('separates a hold from idle by VALUE, so a narrow hold still reads as a hold', () => {
+    const runs = fillsOf(
+      band([
+        { phase: 'eccentric', startMs: 0, endMs: 1000 },
+        { phase: 'hold', startMs: 1000, endMs: 1500 },
+        { phase: 'concentric', startMs: 1500, endMs: 3000 },
+      ])
+    )
+    expect(runs[1].fill).toBe(PHASE_AXIS_COLOR.hold)
+    expect(runs[1].fill).not.toBe(PHASE_AXIS_COLOR.idle)
+    // A filled hold sits BRIGHTER than idle, an unfilled one darker — never the same.
+    expect(PHASE_AXIS_COLOR.hold).not.toBe(PHASE_AXIS_BASE_COLOR.hold)
+    expect(PHASE_AXIS_BASE_COLOR.hold).not.toBe(PHASE_AXIS_COLOR.idle)
+  })
+
+  it('labels ONLY the movement phases — hold and idle stay unnamed', () => {
+    // The pacing-tone contrast floor is measured against ECC/CON backgrounds only, so this
+    // exclusion is what keeps that narrower set honest. Widening it here needs the tones
+    // re-measured against whatever new background can sit behind a label.
+    const c = band(
+      [
+        { phase: 'eccentric', startMs: 0, endMs: 1000 },
+        { phase: 'hold', startMs: 1000, endMs: 1500 },
+        { phase: 'concentric', startMs: 1500, endMs: 3000 },
+        { phase: 'idle', startMs: 3000, endMs: 4000 },
+      ],
+      { showLabels: true }
+    )
+    expect(labelsOf(c).map((l) => l.text)).toEqual(['ECC', 'CON'])
+  })
+
+  it('DROPS a label that will not fit rather than clipping it', () => {
+    // A 300 ms concentric is ~22 px here — over the old flat 20 px floor, which rendered a
+    // word that ran past its own run and clipped.
+    const c = band(
+      [
+        { phase: 'eccentric', startMs: 0, endMs: 1000 },
+        { phase: 'concentric', startMs: 1000, endMs: 1300 },
+      ],
+      { showLabels: true }
+    )
+    expect(labelsOf(c).map((l) => l.text)).toEqual(['ECC'])
+  })
+
+  it('rounds the band once, as a clip — never per run', () => {
+    const c = band()
+    expect(c.querySelector('clipPath rect')?.getAttribute('rx')).toBe('2')
+    const runRects = Array.from(c.querySelectorAll('g[clip-path] > g > rect'))
+    expect(runRects.every((r) => r.getAttribute('rx') == null)).toBe(true)
+  })
+
+  // --- pacing -----------------------------------------------------------------
+
+  it('fills every run completely when no tempo is prescribed', () => {
+    const bases = basesOf(band())
+    fillsOf(band()).forEach((f, i) => expect(f.width).toBeCloseTo(bases[i].width, 5))
+  })
+
+  it('leaves the geometry alone when pacing turns on — only the FILL changes', () => {
+    const flat = basesOf(band(onPace))
+    const paced = basesOf(band(onPace, { targetTempoSeconds: TEMPO }))
+    expect(paced).toEqual(flat)
+  })
+
+  it('fills a run that hit its target to the brim', () => {
+    const c = band(onPace, { targetTempoSeconds: TEMPO })
+    const bases = basesOf(c)
+    fillsOf(c).forEach((f, i) => expect(f.width).toBeCloseTo(bases[i].width, 5))
+  })
+
+  it('leaves a FAST phase partly unfilled — the base shows through', () => {
+    // A 1.3 s eccentric against a 2.6 s target is exactly half paced.
+    const fast: PhaseSegment[] = [{ phase: 'eccentric', startMs: 0, endMs: 1300 }]
+    const c = band(fast, { targetTempoSeconds: TEMPO })
+    expect(fillsOf(c)[0].width).toBeCloseTo(basesOf(c)[0].width * 0.5, 5)
+  })
+
+  it('CAPS a slow phase at its own run width rather than overflowing', () => {
+    const slow: PhaseSegment[] = [{ phase: 'eccentric', startMs: 0, endMs: 9000 }]
+    const c = band(slow, { targetTempoSeconds: TEMPO })
+    expect(fillsOf(c)[0].width).toBeCloseTo(basesOf(c)[0].width, 5)
+  })
+
+  it('paints the muted base UNDER the fill so an unfilled remainder is still band', () => {
+    const fast: PhaseSegment[] = [{ phase: 'eccentric', startMs: 0, endMs: 1300 }]
+    const c = band(fast, { targetTempoSeconds: TEMPO })
+    expect(basesOf(c)[0].fill).toBe(PHASE_AXIS_BASE_COLOR.eccentric)
+    expect(fillsOf(c)[0].fill).toBe(PHASE_AXIS_COLOR.eccentric)
+  })
+
+  it('tones each label by its OWN pacing, independently', () => {
+    const mixed: PhaseSegment[] = [
+      { phase: 'eccentric', startMs: 0, endMs: 1000 }, // 1.0s vs 2.6s → ahead
+      { phase: 'concentric', startMs: 1000, endMs: 4000 }, // 3.0s vs 0.95s → over
+    ]
+    const c = band(mixed, { targetTempoSeconds: TEMPO, showLabels: true })
+    expect(labelsOf(c)).toEqual([
+      { text: 'ECC', fill: PACING_TONE.ahead },
+      { text: 'CON', fill: PACING_TONE.over },
+    ])
+  })
+
+  it('tones a label ON PACE when the phase hits its target', () => {
+    const c = band(onPace, { targetTempoSeconds: TEMPO, showLabels: true })
+    expect(labelsOf(c).map((l) => l.fill)).toEqual([PACING_TONE.onPace, PACING_TONE.onPace])
+  })
+
+  it('keeps labels plain when nothing is prescribed to pace against', () => {
+    const c = band(onPace, { showLabels: true })
+    expect(labelsOf(c).every((l) => l.fill === t['text-primary'])).toBe(true)
+  })
+
+  // --- prescribed (nothing performed yet) --------------------------------------
+
+  it('paints a PRESCRIBED rep entirely unfilled — nothing has been performed', () => {
+    const c = band(onPace, { targetTempoSeconds: TEMPO, prescribed: true })
+    fillsOf(c).forEach((f) => expect(f.width).toBe(0))
+  })
+
+  it('still draws the prescribed runs at full width, so the shape reads', () => {
+    const plain = basesOf(band(onPace, { targetTempoSeconds: TEMPO }))
+    const pre = basesOf(band(onPace, { targetTempoSeconds: TEMPO, prescribed: true }))
+    expect(pre).toEqual(plain)
+  })
+
+  it('keeps prescribed labels PLAIN — an unstarted rep is neither ahead nor behind', () => {
+    const c = band(onPace, { targetTempoSeconds: TEMPO, prescribed: true, showLabels: true })
+    expect(labelsOf(c).every((l) => l.fill === t['text-primary'])).toBe(true)
+  })
+
+  // --- the well ---------------------------------------------------------------
+
+  it('recesses every run, so an unearned remainder reads as empty channel', () => {
+    const c = band(onPace, { targetTempoSeconds: TEMPO })
+    expect(c.querySelectorAll('[data-testid="ghost-band-well"]')).toHaveLength(onPace.length)
+  })
+
+  it('sits the well UNDER the fill — a filled run hides its own recess', () => {
+    const c = band(onPace, { targetTempoSeconds: TEMPO })
+    const order = Array.from(c.querySelectorAll('g[clip-path] > g > rect')).map((r) =>
+      r.getAttribute('data-testid')
+    )
+    expect(order.slice(0, 3)).toEqual(['ghost-band-base', 'ghost-band-well', 'ghost-band-fill'])
+  })
+
+  it('spans the well across the whole run, not just the unfilled part', () => {
+    // Recessing only the exposed remainder would step in tone at the fill's edge.
+    const fast: PhaseSegment[] = [{ phase: 'eccentric', startMs: 0, endMs: 1300 }]
+    const c = band(fast, { targetTempoSeconds: TEMPO })
+    const well = geom(c.querySelector('[data-testid="ghost-band-well"]')!)
+    expect(well.width).toBeCloseTo(basesOf(c)[0].width, 5)
+  })
+})

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

@@ -0,0 +1,246 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+/**
+ * GhostBand — the wide phase-coloured AXIS BAND that carries movement phase for the
+ * ghost family (eccentric magenta / concentric cyan / hold and idle grey), with the
+ * ECC / HOLD / CON labels rendered INSIDE it. Extracted from GhostSpark so the single
+ * sparkline and a future top/bottom dual compose the SAME band instead of re-rolling it.
+ *
+ * It is a pure SVG group: the caller owns the x-scale (`x`) and the band's vertical
+ * placement (`top`), so the same band serves a bottom-pinned single or a centred dual.
+ *
+ * ## Pacing
+ *
+ * Given a target tempo, each run paints a MUTED base with a brighter fill growing
+ * left-to-right across `elapsed / target` of its own width (capped at full), and its label
+ * takes the pacing tone — ahead / on pace / over. The band's GEOMETRY is untouched by this:
+ * runs keep their actual-time positions and widths so the internal boundaries still land
+ * under the sparkline's phase transitions. Pacing is a fill INSIDE the existing bars, never
+ * a re-layout of them.
+ *
+ * The two encodings read together: a slow phase is a WIDE run filled to the brim with an
+ * error-toned label; a fast phase is a NARROW run only partly filled, warning-toned.
+ *
+ * Every run is recessed into a WELL, so the part not yet earned reads as empty channel
+ * rather than as a darker shade of the phase. The well needs no flag: where nothing is
+ * prescribed the fill covers the whole run and the recess is hidden behind it.
+ */
+import { useId } from 'react'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { primitiveColors } from '../../../theme/tokens/primitives'
+import { FONT_UI, PHASE_AXIS_COLOR, PHASE_AXIS_BASE_COLOR } from './fatigue-tokens'
+import { phaseFillFraction, pacingTone, phaseTargetsMs, type TempoTuple } from './tempo-pacing'
+import type { PhaseSegment } from './fatigue-model'
+
+const t = getSemanticColors('dark')
+
+/** Band height in px. */
+export const BAND_H = 16
+/** Gap between the band's near edge and a bloom's baseline. */
+export const BAND_GAP = 4
+
+/**
+ * Phase → the word rendered inside its run.
+ *
+ * Only the two MOVEMENT phases are named. `idle` never was — dead time has no name — and
+ * `hold` is deliberately unlabelled too: holds are the narrowest runs on the band, so the
+ * word was dropping out at exactly the sizes it mattered, and the runs it did fit were
+ * spending their whole width on it. A hold is legible without the word, from its tone,
+ * its position between the movement phases, and the fact that it fills.
+ */
+const PHASE_LABEL: Partial<Record<PhaseSegment['phase'], string>> = {
+  eccentric: 'ECC',
+  concentric: 'CON',
+}
+
+/** Label glyph advance at fontSize 8 + letterSpacing 1, plus a little side padding. */
+const LABEL_CH_PX = 7
+const LABEL_PAD_PX = 6
+
+/** The well shades toward black so it recesses every phase tone identically. */
+const WELL_SHADE = primitiveColors.black
+/** The faint light line on the well's floor — the far lip catching light. */
+const WELL_FLOOR_LIGHT = primitiveColors.white
+
+/**
+ * Does `label` fit inside a run `segW` px wide? Sized per WORD, not a flat floor — a flat
+ * 20 px clipped 'HOLD' to 'HOL' on exactly the short top-hold runs the label exists for.
+ */
+function labelFits(label: string, segW: number): boolean {
+  return segW >= label.length * LABEL_CH_PX + LABEL_PAD_PX
+}
+
+export interface GhostBandProps {
+  /** The current rep's phase runs, in stream order. */
+  segments: PhaseSegment[]
+  /** Time (ms) → px mapper, owned by the caller. */
+  x: (ms: number) => number
+  /** The band's top edge, px. */
+  top: number
+  /** Band height, px. Default {@link BAND_H}. */
+  height?: number
+  /** Reveal the ECC / HOLD / CON labels inside the band. */
+  showLabels?: boolean
+  /**
+   * Label colour when there is no pacing tone to apply. Default the primary text token.
+   * Ignored for a run that paces — that label takes {@link pacingTone}.
+   */
+  labelColor?: string
+  /**
+   * Prescribed tempo `[ecc, pauseBottom, con, pauseTop]` in seconds. Supplying it turns on
+   * PACING: runs paint muted-base + fill, and labels take the ahead/on-pace/over tone.
+   *
+   * Omit it and the band paints flat at full tone with plain labels — the pre-pacing look,
+   * which is also the honest one when nothing was prescribed to pace against.
+   */
+  targetTempoSeconds?: TempoTuple | null
+  /**
+   * These runs are PRESCRIBED, not performed — the set has not started. Every run paints
+   * unfilled at its base tone with a plain label, because nothing has been paced yet.
+   *
+   * Used by the empty state, where the band shows the SHAPE of the rep that was asked for
+   * (from the target tempo) rather than an axis with nothing on it.
+   */
+  prescribed?: boolean
+}
+
+/**
+ * The phase-coloured axis band — ONE contiguous strip whose internal boundaries land
+ * exactly on the sparkline's phase transitions.
+ *
+ * Contiguity is structural, not incidental: the band is a single rounded silhouette
+ * (clipped), floored with the idle tone across its whole time extent, and each phase run
+ * paints SQUARE inside that clip, extended to the next run's start. No per-segment inset
+ * and no per-segment rounding — those read as gaps between sections.
+ */
+export function GhostBand({
+  segments,
+  x,
+  top,
+  height = BAND_H,
+  showLabels = false,
+  labelColor = t['text-primary'],
+  targetTempoSeconds = null,
+  prescribed = false,
+}: GhostBandProps) {
+  const rawId = useId()
+  const safeId = rawId.replace(/[^a-zA-Z0-9]/g, '')
+  const clipId = `ghost-band-${safeId}`
+  const wellId = `ghost-band-well-${safeId}`
+
+  const drawn = segments.filter((seg) => x(seg.endMs) - x(seg.startMs) > 0)
+  if (drawn.length === 0) return null
+
+  const bandLeft = x(drawn[0].startMs)
+  const bandRight = x(drawn[drawn.length - 1].endMs)
+  const bandW = bandRight - bandLeft
+  if (bandW <= 0) return null
+
+  const pacing = targetTempoSeconds != null && !prescribed
+  // Each run's elapsed time IS its own duration — the in-flight run's `endMs` is already
+  // "now" — so pacing needs no clock of its own.
+  const targetsMs = phaseTargetsMs(
+    drawn.map((seg) => seg.phase),
+    targetTempoSeconds
+  )
+
+  // Butt each run against the NEXT run's start (not its own end) so rounding between the
+  // two can never open a seam; the last run runs to the band edge.
+  const runs = drawn.map((seg, i) => {
+    const left = x(seg.startMs)
+    const right = i === drawn.length - 1 ? bandRight : x(drawn[i + 1].startMs)
+    const width = Math.max(0, right - left)
+    const targetMs = targetsMs[i]
+    const elapsedMs = seg.endMs - seg.startMs
+    return {
+      phase: seg.phase,
+      left,
+      width,
+      // Prescribed → nothing performed, so nothing filled. No target at all → the run reads
+      // complete rather than perpetually empty.
+      fillWidth: prescribed ? 0 : pacing ? width * phaseFillFraction(elapsedMs, targetMs) : width,
+      labelTone: pacing ? pacingTone(elapsedMs, targetMs) : labelColor,
+    }
+  })
+
+  return (
+    <g>
+      <defs>
+        <clipPath id={clipId}>
+          <rect x={bandLeft} y={top} width={bandW} height={height} rx={2} />
+        </clipPath>
+        {/* The WELL — dark under the top lip, falling off fast, with a faint light line on
+            the floor. SVG has no `inset` box-shadow, so a recess is a gradient. */}
+        <linearGradient id={wellId} x1="0" y1="0" x2="0" y2="1">
+          <stop offset="0%" stopColor={WELL_SHADE} stopOpacity={0.6} />
+          <stop offset="42%" stopColor={WELL_SHADE} stopOpacity={0.12} />
+          <stop offset="88%" stopColor={WELL_SHADE} stopOpacity={0.02} />
+          <stop offset="100%" stopColor={WELL_FLOOR_LIGHT} stopOpacity={0.07} />
+        </linearGradient>
+      </defs>
+      <g clipPath={`url(#${clipId})`}>
+        {/* the strip floor — the idle tone spans the rep so a pause is band, not a hole. */}
+        <rect
+          x={bandLeft}
+          y={top}
+          width={bandW}
+          height={height}
+          fill={PHASE_AXIS_COLOR.idle}
+          data-testid="ghost-band-floor"
+        />
+        {/* Each run: the muted base at FULL run width, then the pacing fill over the part
+            of it that has been earned. Both square inside the one clip — the fill is a
+            fill, never an inset, so no boundary can open a seam. */}
+        {runs.map((run, i) => (
+          <g key={i}>
+            <rect
+              x={run.left}
+              y={top}
+              width={run.width}
+              height={height}
+              fill={PHASE_AXIS_BASE_COLOR[run.phase]}
+              data-testid="ghost-band-base"
+            />
+            <rect
+              x={run.left}
+              y={top}
+              width={run.width}
+              height={height}
+              fill={`url(#${wellId})`}
+              data-testid="ghost-band-well"
+            />
+            <rect
+              x={run.left}
+              y={top}
+              width={run.fillWidth}
+              height={height}
+              fill={PHASE_AXIS_COLOR[run.phase]}
+              data-testid="ghost-band-fill"
+            />
+          </g>
+        ))}
+        {/* Labels last so a fill sweeping past never paints over the word. */}
+        {showLabels &&
+          runs.map((run, i) => {
+            const label = PHASE_LABEL[run.phase]
+            if (!label || !labelFits(label, run.width)) return null
+            return (
+              <text
+                key={i}
+                x={run.left + run.width / 2}
+                y={top + height / 2}
+                textAnchor="middle"
+                dominantBaseline="central"
+                fill={run.labelTone}
+                fontSize={8}
+                fontWeight={800}
+                letterSpacing={1}
+                fontFamily={FONT_UI}
+              >
+                {label}
+              </text>
+            )
+          })}
+      </g>
+    </g>
+  )
+}