@titan-design/react-ui 0.4.0 → 0.6.0

package/src/components/custom/Workout/PrBadge.tsx

@@ -1,8 +1,11 @@
 // Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
 import { useEffect, useState } from 'react'
 import { View, Text, Animated, Easing, type ViewProps } from 'react-native'
-import { Star } from 'lucide-react'
+import { StarIcon } from './icons'
 import { BaseBadge } from './BaseBadge'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+
+const BRAND_PRIMARY = getSemanticColors('dark')['brand-primary']
 
 export type PRType = 'e1rm' | 'weight' | 'reps' | 'volume' | 'velocity'
 
@@ -66,7 +69,7 @@ export function PrBadge({
       testID="pr-badge-star"
       {...props}
     >
-      <Star size={14} color="#FF7900" fill="#FF7900" strokeWidth={2} />
+      <StarIcon size={14} color={BRAND_PRIMARY} fill={BRAND_PRIMARY} strokeWidth={2} />
     </View>
   ) : (
     <BaseBadge
@@ -77,8 +80,8 @@ export function PrBadge({
     >
       <Text
         style={{
-          fontSize: 10,
-          color: '#FF7900',
+          fontSize: 12,
+          color: BRAND_PRIMARY,
           fontWeight: '700',
           fontFamily: 'Inter, sans-serif',
         }}

package/src/components/custom/Workout/PrHistoryModal.tsx

@@ -1,12 +1,13 @@
 // Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
 import { View, Text, Pressable, type ViewProps } from 'react-native'
-import { Star } from 'lucide-react'
+import { StarIcon } from './icons'
 import { Drawer, DrawerBody } from '../../ui/drawer'
 import { resolveColor } from '../../../theme/resolve-color'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
 
-const BRAND_PRIMARY = '#FF7900'
-const RECENT_BORDER = 'rgba(255,176,32,0.3)'
-const RECENT_GLOW = '0 0 12px rgba(255,176,32,0.06)'
+const BRAND_PRIMARY = getSemanticColors('dark')['brand-primary']
+const RECENT_BORDER = 'rgba(249,180,21,0.3)'
+const RECENT_GLOW = '0 0 12px rgba(249,180,21,0.06)'
 // Native-safe fallback for the conditional row border (recent uses a computed
 // rgba, so className can't express both branches).
 const BORDER_DEFAULT = resolveColor('border-default')
@@ -84,7 +85,7 @@ function PrRecordRow({ record, index }: { record: PrRecord; index: number }) {
       }}
       testID={`pr-history-modal-record-${index}`}
     >
-      <Star size={16} color={BRAND_PRIMARY} fill={BRAND_PRIMARY} strokeWidth={2} />
+      <StarIcon size={16} color={BRAND_PRIMARY} fill={BRAND_PRIMARY} strokeWidth={2} />
       <Text
         className="text-text-secondary"
         style={{

package/src/components/custom/Workout/ProgramPlanningPage.tsx

@@ -8,8 +8,9 @@ import { WorkoutCard, type WorkoutStatus, type WorkoutMuscleGroup } from './Work
 import { type WorkoutPillStatus } from './WorkoutPill'
 import { type ExerciseCardProps } from './ExerciseCard'
 import { cn } from '../../../utils/cn'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
 
-const BRAND_PRIMARY = '#FF7900'
+const BRAND_PRIMARY = getSemanticColors('dark')['brand-primary']
 
 /** A single workout within a planned week, plus its exercise breakdown. */
 export interface PlanWorkout {

package/src/components/custom/Workout/README.md

@@ -0,0 +1,50 @@
+# Workout component family
+
+Training-specific components (badges, bars, timers, cards, charts, and page-level
+screens) built on titan's atoms. They live flat on disk — the tiering below is a
+documentation contract, not a directory layout, so promoting or composing a
+component is pure import churn with no file moves.
+
+## Tier map
+
+**Atoms** — single-purpose, no cross-component state:
+BaseBadge · WeightBadge · PrBadge · StatusDot · PlaceholderStrip · TempoBar ·
+DeviationBar · IntensityBar · WorkoutPill · MuscleGroupChip · Sparkline ·
+SupersetWrapper · InputBar
+
+**Molecules** — compose atoms, own a little local state:
+VelocityStrip · SetRow · TempoDisplay · RestTimer · MesoProgressBar · WeekRow ·
+WorkoutCard
+
+**Organisms** — full features, often with their own data contract:
+ExerciseCard · MesoCard · MesoStatusCard · PrHistoryModal · ReadinessCheck ·
+StrengthTrendChart · CapacityBandChart · BodyMap · BodyMapDetailPanel
+
+**Pages** — phone-shaped reference screens (whole-screen compositions):
+ActiveWorkoutPage · ExerciseDetailPage · ProgramPlanningPage · TrainingStatusPage
+
+## Subpaths
+
+Two families are kept off the root barrel so `@titan-design/react-ui` stays free
+of their heavy runtime dependencies. In both cases the value exports move to the
+subpath while type-only re-exports remain on the root, so consumers can still
+type props without pulling the dependency.
+
+- **`@titan-design/react-ui/bodymap`** — isolates
+  `react-native-body-highlighter` (a native SVG dep). BodyMap, BodyMapDetailPanel,
+  TrainingStatusPage, and the muscle taxonomy live here.
+- **`@titan-design/react-ui/pages`** — isolates the page-level organisms
+  (ActiveWorkoutPage, ExerciseDetailPage, ProgramPlanningPage). They are full app
+  screens orphaned by both consumers, kept as reference implementations while their
+  successors (the responsive level views) are built. TrainingStatusPage is the
+  exception — it stays under `/bodymap` because of the body-highlighter dep.
+
+## Notes
+
+- **BaseBadge is an internal composition primitive** — the shared shell that
+  WeightBadge and PrBadge build on. It is exempt from orphan accounting; it is not
+  meant to be consumed directly even though it is exported for composition.
+- Badge icons (WeightBadge's dumbbell, PrBadge / PrHistoryModal's star) are inline
+  SVGs (`./icons.tsx`), not `lucide-react` — that dependency was dropped in 0.5.0
+  to keep the root barrel light. The SVG paths mirror lucide's glyphs so rendering
+  is unchanged.

package/src/components/custom/Workout/ReadinessCheck.tsx

@@ -2,12 +2,15 @@
 import { View, Text, Pressable } from 'react-native'
 import { Card } from '../../ui/card'
 import { Badge, type BadgeColor } from '../../ui/badge'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
 
-const BRAND_PRIMARY = '#FF7900'
+const t = getSemanticColors('dark')
+
+const BRAND_PRIMARY = t['brand-primary']
 const BRAND_PRIMARY_SUBTLE = 'rgba(255,121,0,0.12)'
-const STATUS_SUCCESS = '#14B8A6'
-const STATUS_WARNING = '#FFB020'
-const STATUS_ERROR = '#D14343'
+const STATUS_SUCCESS = t['status-success']
+const STATUS_WARNING = t['status-warning']
+const STATUS_ERROR = t['status-error']
 
 /** Emoji option sets per known factor, keyed by lowercase id/label. */
 const EMOJI_SETS: Record<string, readonly string[]> = {

package/src/components/custom/Workout/RestTimer.test.tsx

@@ -75,16 +75,51 @@ describe('RestTimer', () => {
     })
   })
 
-  describe('next set info', () => {
-    it('displays nextSetInfo when provided', () => {
+  describe('display-only mode', () => {
+    it('renders the Skip and +30s actions by default', () => {
+      render(<RestTimer {...defaultProps} />)
+      expect(screen.getByTestId('rest-timer-skip')).toBeInTheDocument()
+      expect(screen.getByTestId('rest-timer-add-time')).toBeInTheDocument()
+    })
+
+    it('hides the Skip and +30s actions when displayOnly', () => {
+      render(<RestTimer {...defaultProps} displayOnly />)
+      expect(screen.queryByTestId('rest-timer-skip')).not.toBeInTheDocument()
+      expect(screen.queryByTestId('rest-timer-add-time')).not.toBeInTheDocument()
+    })
+
+    it('keeps the countdown, progress bar, and next-set line when displayOnly', () => {
       render(
         <RestTimer
           {...defaultProps}
+          elapsedMs={30000}
+          displayOnly
           nextSetInfo="Bench Press — Set 3 of 4"
-        />,
+        />
+      )
+      expect(screen.getByTestId('rest-timer-time')).toHaveTextContent('2:00')
+      expect(screen.getByTestId('rest-timer-progress-fill')).toBeInTheDocument()
+      expect(screen.getByTestId('rest-timer-next-set')).toHaveTextContent(
+        'Bench Press — Set 3 of 4'
       )
+    })
+
+    it('does not fire callbacks in display-only mode (controls absent)', () => {
+      const onSkip = vi.fn()
+      const onAddTime = vi.fn()
+      render(<RestTimer {...defaultProps} onSkip={onSkip} onAddTime={onAddTime} displayOnly />)
+      expect(screen.queryByLabelText('Skip rest')).not.toBeInTheDocument()
+      expect(screen.queryByLabelText('Add 30 seconds')).not.toBeInTheDocument()
+      expect(onSkip).not.toHaveBeenCalled()
+      expect(onAddTime).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('next set info', () => {
+    it('displays nextSetInfo when provided', () => {
+      render(<RestTimer {...defaultProps} nextSetInfo="Bench Press — Set 3 of 4" />)
       expect(screen.getByTestId('rest-timer-next-set')).toHaveTextContent(
-        'Bench Press — Set 3 of 4',
+        'Bench Press — Set 3 of 4'
       )
     })
 
@@ -127,9 +162,7 @@ describe('RestTimer', () => {
 
     it('has timer role with remaining seconds in label', () => {
       render(<RestTimer {...defaultProps} totalSeconds={90} elapsedMs={30000} />)
-      expect(
-        screen.getByLabelText('Rest timer, 60 seconds remaining'),
-      ).toBeInTheDocument()
+      expect(screen.getByLabelText('Rest timer, 60 seconds remaining')).toBeInTheDocument()
     })
 
     it('skip button has accessible label', () => {
@@ -146,9 +179,7 @@ describe('RestTimer', () => {
 
 describe('RestTimer zero-duration timer (NaN guard)', () => {
   it('emits a valid 100% width (not NaN) when totalSeconds is 0', () => {
-    const { container } = render(
-      <RestTimer {...defaultProps} totalSeconds={0} elapsedMs={0} />,
-    )
+    const { container } = render(<RestTimer {...defaultProps} totalSeconds={0} elapsedMs={0} />)
     expect(screen.getByTestId('rest-timer-progress-fill')).toHaveStyle({ width: '100%' })
     expect(container.innerHTML).not.toContain('NaN')
   })

package/src/components/custom/Workout/RestTimer.tsx

@@ -1,8 +1,9 @@
 // Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
 import { View, Text, Pressable } from 'react-native'
 import { resolveColor } from '../../../theme/resolve-color'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
 
-const BRAND_PRIMARY = '#FF7900'
+const BRAND_PRIMARY = getSemanticColors('dark')['brand-primary']
 
 export interface RestTimerProps {
   totalSeconds: number
@@ -11,6 +12,8 @@ export interface RestTimerProps {
   onAddTime: () => void
   nextSetInfo?: string
   visible: boolean
+  /** Passive/poll-only mode: hides the Skip and +30s controls, keeps the countdown, progress bar, and next-set line. */
+  displayOnly?: boolean
 }
 
 export function RestTimer({
@@ -20,6 +23,7 @@ export function RestTimer({
   onAddTime,
   nextSetInfo,
   visible,
+  displayOnly = false,
 }: RestTimerProps) {
   if (!visible) return null
 
@@ -123,55 +127,57 @@ export function RestTimer({
         />
       </View>
 
-      {/* Actions row */}
-      <View style={{ flexDirection: 'row', gap: 8 }}>
-        <Pressable
-          onPress={onAddTime}
-          style={{
-            backgroundColor: 'rgba(255,255,255,0.06)',
-            paddingVertical: 8,
-            paddingHorizontal: 20,
-            borderRadius: 8,
-          }}
-          accessibilityRole="button"
-          accessibilityLabel="Add 30 seconds"
-          testID="rest-timer-add-time"
-        >
-          <Text
-            className="text-text-secondary"
+      {/* Actions row — hidden in display-only (poll-only) mode */}
+      {!displayOnly && (
+        <View style={{ flexDirection: 'row', gap: 8 }}>
+          <Pressable
+            onPress={onAddTime}
             style={{
-              fontSize: 11,
-              fontFamily: 'Inter, sans-serif',
-              fontWeight: '600',
+              backgroundColor: 'rgba(255,255,255,0.06)',
+              paddingVertical: 8,
+              paddingHorizontal: 20,
+              borderRadius: 8,
             }}
+            accessibilityRole="button"
+            accessibilityLabel="Add 30 seconds"
+            testID="rest-timer-add-time"
           >
-            +30s
-          </Text>
-        </Pressable>
-        <Pressable
-          onPress={onSkip}
-          style={{
-            backgroundColor: 'rgba(255,121,0,0.12)',
-            paddingVertical: 8,
-            paddingHorizontal: 20,
-            borderRadius: 8,
-          }}
-          accessibilityRole="button"
-          accessibilityLabel="Skip rest"
-          testID="rest-timer-skip"
-        >
-          <Text
+            <Text
+              className="text-text-secondary"
+              style={{
+                fontSize: 11,
+                fontFamily: 'Inter, sans-serif',
+                fontWeight: '600',
+              }}
+            >
+              +30s
+            </Text>
+          </Pressable>
+          <Pressable
+            onPress={onSkip}
             style={{
-              fontSize: 11,
-              fontFamily: 'Inter, sans-serif',
-              fontWeight: '600',
-              color: BRAND_PRIMARY,
+              backgroundColor: 'rgba(255,121,0,0.12)',
+              paddingVertical: 8,
+              paddingHorizontal: 20,
+              borderRadius: 8,
             }}
+            accessibilityRole="button"
+            accessibilityLabel="Skip rest"
+            testID="rest-timer-skip"
           >
-            Skip
-          </Text>
-        </Pressable>
-      </View>
+            <Text
+              style={{
+                fontSize: 11,
+                fontFamily: 'Inter, sans-serif',
+                fontWeight: '600',
+                color: BRAND_PRIMARY,
+              }}
+            >
+              Skip
+            </Text>
+          </Pressable>
+        </View>
+      )}
     </View>
   )
 }

package/src/components/custom/Workout/SetRow.tsx

@@ -1,8 +1,9 @@
 // Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
 import { View, Text } from 'react-native'
-import { VelocityStrip } from './VelocityStrip'
+import { VelocityStrip, type VelocityZoneBandProp } from './VelocityStrip'
 import { PrBadge, type PRType } from './PrBadge'
 import { roundRpe, rpeColor, roundWeight } from '../../../utils/workout-format'
+import { WORKOUT_TOKENS } from '../../../theme/workout-tokens'
 
 export type SetRowMode = 'active' | 'completed' | 'history'
 
@@ -14,7 +15,12 @@ export interface SetRowProps {
   weight: number | null
   rpe?: number | null
   unit: 'lbs' | 'kg'
+  /** Per-rep MEAN concentric velocities (m/s). */
   velocities?: number[]
+  /** Optional velocity-zone bands (WA `VelocityZones.bands`); default scale when absent. */
+  velocityZones?: readonly VelocityZoneBandProp[]
+  /** Live mode: index of the newest rep bar to animate (pop / new-peak bounce). */
+  velocityLiveRepIndex?: number
   velocityExpanded?: boolean
   onVelocityToggle?: () => void
   setType?: string
@@ -43,6 +49,8 @@ export function SetRow({
   rpe,
   unit,
   velocities,
+  velocityZones,
+  velocityLiveRepIndex,
   velocityExpanded,
   onVelocityToggle,
   setType,
@@ -93,7 +101,7 @@ export function SetRow({
               fontSize: 10,
               fontWeight: '700',
               fontFamily: 'Inter, sans-serif',
-              color: '#ffa502',
+              color: WORKOUT_TOKENS.scale.orange,
               backgroundColor: 'rgba(255,165,2,0.12)',
               paddingVertical: 1,
               paddingHorizontal: 5,
@@ -239,6 +247,8 @@ export function SetRow({
         >
           <VelocityStrip
             velocities={velocities}
+            zones={velocityZones}
+            liveRepIndex={velocityLiveRepIndex}
             expanded={velocityExpanded}
             onToggle={onVelocityToggle}
             variant={onVelocityToggle ? 'full' : 'mini'}

package/src/components/custom/Workout/Sparkline.tsx

@@ -2,8 +2,9 @@
 import React from 'react'
 import { View, Text, type ViewProps } from 'react-native'
 import { cn } from '../../../utils/cn'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
 
-const BRAND_PRIMARY = '#FF7900'
+const BRAND_PRIMARY = getSemanticColors('dark')['brand-primary']
 
 export interface SparklineProps extends ViewProps {
   data: number[]

package/src/components/custom/Workout/StatusDot.test.tsx

@@ -103,13 +103,13 @@ describe('StatusDot', () => {
     it('applies a box-shadow when glow is set on a solid variant', () => {
       render(<StatusDot variant="success" glow />)
       const dot = screen.getByTestId('status-dot')
-      expect(dot.style.boxShadow).toContain('rgba(20,184,166,0.4)')
+      expect(dot.style.boxShadow).toContain('rgba(46,213,115,0.4)')
     })
 
     it('applies a box-shadow when glow is set on a ring variant', () => {
       render(<StatusDot variant="on-track" glow />)
       const dot = screen.getByTestId('status-dot')
-      expect(dot.style.boxShadow).toContain('rgba(20,184,166,0.4)')
+      expect(dot.style.boxShadow).toContain('rgba(46,213,115,0.4)')
     })
 
     it('applies a gray box-shadow when glow is set on the future variant', () => {

package/src/components/custom/Workout/StatusDot.tsx

@@ -1,5 +1,8 @@
 // Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
 import { View, Text, type ViewProps } from 'react-native'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+
+const t = getSemanticColors('dark')
 
 export type StatusDotVariant =
   | 'success'
@@ -22,17 +25,17 @@ export interface StatusDotProps extends ViewProps {
 }
 
 const solidVariantColors: Record<string, string> = {
-  success: '#14B8A6',
-  warning: '#FFB020',
-  error: '#D14343',
+  success: t['status-success'],
+  warning: t['status-warning'],
+  error: t['status-error'],
   neutral: '#6B7280',
 }
 
 const ringVariantStyles: Record<string, Record<string, unknown>> = {
   'on-track': {
-    backgroundColor: 'rgba(20,184,166,0.15)',
+    backgroundColor: 'rgba(46,213,115,0.15)',
     borderWidth: 1,
-    borderColor: 'rgba(20,184,166,0.3)',
+    borderColor: 'rgba(46,213,115,0.3)',
   },
   deviation: {
     backgroundColor: 'rgba(245,158,11,0.15)',
@@ -48,11 +51,11 @@ const ringVariantStyles: Record<string, Record<string, unknown>> = {
 }
 
 const glowStyles: Record<StatusDotVariant, Record<string, unknown>> = {
-  success: { boxShadow: '0 0 4px rgba(20,184,166,0.4)' },
+  success: { boxShadow: '0 0 4px rgba(46,213,115,0.4)' },
   warning: { boxShadow: '0 0 4px rgba(245,158,11,0.4)' },
   error: { boxShadow: '0 0 4px rgba(239,68,68,0.4)' },
   neutral: { boxShadow: '0 0 4px rgba(107,114,128,0.4)' },
-  'on-track': { boxShadow: '0 0 4px rgba(20,184,166,0.4)' },
+  'on-track': { boxShadow: '0 0 4px rgba(46,213,115,0.4)' },
   deviation: { boxShadow: '0 0 4px rgba(245,158,11,0.4)' },
   future: { boxShadow: '0 0 4px rgba(107,114,128,0.4)' },
 }
@@ -69,8 +72,8 @@ const iconColors: Record<StatusDotVariant, string> = {
   warning: '#6B4000',
   error: '#5C1A1A',
   neutral: '#D1D5DB',
-  'on-track': '#14B8A6',
-  deviation: '#FFB020',
+  'on-track': t['status-success'],
+  deviation: t['status-warning'],
   future: '#6B7280',
 }
 

package/src/components/custom/Workout/StrengthTrendChart.tsx

@@ -3,17 +3,20 @@ import { useEffect, useMemo, useState } from 'react'
 import { View, Text, Pressable, Animated, Easing, type ViewProps } from 'react-native'
 import { cn } from '../../../utils/cn'
 import { resolveColor } from '../../../theme/resolve-color'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
 
-const BRAND_PRIMARY = '#FF7900'
+const sem = getSemanticColors('dark')
+
+const BRAND_PRIMARY = sem['brand-primary']
 // Line/border color for the dashed projection, used where a className cannot
 // apply (passed as a prop into an inline style, and a per-edge borderTopColor).
 const PROJECTION_LINE_COLOR = resolveColor('text-tertiary')
-const STATUS_SUCCESS = '#14B8A6'
-const STATUS_ERROR = '#D14343'
-const STATUS_WARNING = '#FFB020'
+const STATUS_SUCCESS = sem['status-success']
+const STATUS_ERROR = sem['status-error']
+const STATUS_WARNING = sem['status-warning']
 const GRID_LINE = 'rgba(255,255,255,0.06)'
-const SUCCESS_PILL_BG = 'rgba(20,184,166,0.10)'
-const SUCCESS_PILL_BORDER = 'rgba(20,184,166,0.20)'
+const SUCCESS_PILL_BG = 'rgba(46,213,115,0.10)'
+const SUCCESS_PILL_BORDER = 'rgba(46,213,115,0.20)'
 const ERROR_PILL_BG = 'rgba(209,67,67,0.10)'
 const ERROR_PILL_BORDER = 'rgba(209,67,67,0.20)'
 

package/src/components/custom/Workout/SupersetWrapper.tsx

@@ -1,6 +1,7 @@
 // Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
 import React from 'react'
 import { View, Text } from 'react-native'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
 
 export interface SupersetWrapperProps {
   label?: string
@@ -10,7 +11,7 @@ export interface SupersetWrapperProps {
 
 const DEFAULTS = {
   label: 'SS',
-  color: '#FF7900',
+  color: getSemanticColors('dark')['brand-primary'],
   bgBase: '#101010',
 } as const
 

package/src/components/custom/Workout/TempoDisplay.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useEffect, useState } from 'react'
 import { View } from 'react-native'
-import { TempoDisplay } from './TempoDisplay'
+import { TempoDisplay, type TempoLivePhase, type TempoLiveState } from './TempoDisplay'
 
 // tempo = [eccentric, pauseBottom, concentric, pauseTop]
 const meta: Meta<typeof TempoDisplay> = {
@@ -8,10 +9,17 @@ const meta: Meta<typeof TempoDisplay> = {
   component: TempoDisplay,
   tags: ['autodocs'],
   argTypes: {
-    tempo: { control: 'object', description: 'Tempo values [eccentric, pauseBottom, concentric, pauseTop] in seconds' },
+    tempo: {
+      control: 'object',
+      description: 'Tempo values [eccentric, pauseBottom, concentric, pauseTop] in seconds',
+    },
     size: { control: 'select', options: ['sm', 'md'], description: 'Size variant' },
     colored: { control: 'boolean', description: 'Colored vs mono display' },
     showInfo: { control: 'boolean', description: 'Show info tooltip on press' },
+    live: {
+      control: 'object',
+      description: 'Live phase-fill state (opt-in); omit for static prescription',
+    },
   },
 }
 
@@ -64,3 +72,62 @@ export const AllVariants: Story = {
     </View>
   ),
 }
+
+// --- Live phase-fill (opt-in) ----------------------------------------------
+
+// Deterministic mid-rep frames — the active phase digit fills against its target.
+export const LiveEccentricInProgress: Story = {
+  args: { tempo: [3, 1, 1, 0], live: { activePhase: 'eccentric', phaseElapsedMs: 1500 } },
+}
+
+// Concentric target is 1s; 1.6s elapsed is behind pace, so the digit turns red.
+export const LiveBehindPace: Story = {
+  args: { tempo: [3, 1, 1, 0], live: { activePhase: 'concentric', phaseElapsedMs: 1600 } },
+}
+
+const LIVE_CYCLE: { phase: TempoLivePhase; ms: number }[] = [
+  { phase: 'eccentric', ms: 3000 },
+  { phase: 'pauseBottom', ms: 1000 },
+  { phase: 'concentric', ms: 1000 },
+]
+
+function LiveTempoDemo() {
+  const [live, setLive] = useState<TempoLiveState>({ activePhase: 'eccentric', phaseElapsedMs: 0 })
+  useEffect(() => {
+    let idx = 0
+    let start = Date.now()
+    const id = setInterval(() => {
+      const step = LIVE_CYCLE[idx]
+      const elapsed = Date.now() - start
+      if (elapsed >= step.ms + 400) {
+        idx = (idx + 1) % LIVE_CYCLE.length
+        start = Date.now()
+      }
+      setLive({
+        activePhase: LIVE_CYCLE[idx].phase,
+        phaseElapsedMs: Math.min(elapsed, step.ms + 400),
+      })
+    }, 50)
+    return () => clearInterval(id)
+  }, [])
+  return <TempoDisplay tempo={[3, 1, 1, 0]} live={live} />
+}
+
+// Self-driving demo cycling Ecc → Pause → Con to show the fill animating.
+export const LiveAnimated: Story = {
+  render: () => <LiveTempoDemo />,
+}
+
+// Static and live side by side — the same prescription, two modes.
+export const StaticVsLive: Story = {
+  render: () => (
+    <View style={{ gap: 12 }}>
+      <TempoDisplay tempo={[3, 1, 1, 0]} />
+      <TempoDisplay
+        tempo={[3, 1, 1, 0]}
+        live={{ activePhase: 'eccentric', phaseElapsedMs: 1500 }}
+      />
+      <LiveTempoDemo />
+    </View>
+  ),
+}

package/src/components/custom/Workout/TempoDisplay.test.tsx

@@ -80,6 +80,41 @@ describe('TempoDisplay', () => {
     })
   })
 
+  describe('live phase-fill', () => {
+    it('is inert by default (no active fill) for backward-compatible static use', () => {
+      render(<TempoDisplay tempo={[3, 1, 1, 0]} />)
+      expect(screen.queryByTestId('tempo-live-active')).not.toBeInTheDocument()
+    })
+
+    it('renders an active fill overlay for the in-progress phase when live', () => {
+      render(
+        <TempoDisplay
+          tempo={[3, 1, 1, 0]}
+          live={{ activePhase: 'eccentric', phaseElapsedMs: 1500 }}
+        />
+      )
+      expect(screen.getByTestId('tempo-live-active')).toBeInTheDocument()
+      expect(screen.getByText('3')).toBeInTheDocument()
+    })
+
+    it('marks no phase active when idle (activePhase null)', () => {
+      render(<TempoDisplay tempo={[3, 1, 1, 0]} live={{ activePhase: null, phaseElapsedMs: 0 }} />)
+      expect(screen.queryByTestId('tempo-live-active')).not.toBeInTheDocument()
+    })
+
+    it('still renders all four phase digits in live mode', () => {
+      render(
+        <TempoDisplay
+          tempo={[4, 3, 2, 1]}
+          live={{ activePhase: 'concentric', phaseElapsedMs: 500 }}
+        />
+      )
+      for (const digit of ['4', '3', '2', '1']) {
+        expect(screen.getByText(digit)).toBeInTheDocument()
+      }
+    })
+  })
+
   describe('accessibility', () => {
     it('has no accessibility violations', async () => {
       const { container } = render(<TempoDisplay tempo={[3, 1, 1, 0]} />)