@titan-design/react-ui 0.6.0 → 0.7.0

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

@@ -0,0 +1,105 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+import { View, StyleSheet, Platform, type ViewProps, type ViewStyle } from 'react-native'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { alpha } from '../../../utils/colors'
+
+const t = getSemanticColors('dark')
+
+/**
+ * Coaching-category flood level for the live surface. Mirrors {@link StatusPill}:
+ * - `productive` — quiet, no flood
+ * - `threshold`  — amber wash at VL20
+ * - `stop`       — red wash at VL28+ (optionally pulsing)
+ */
+export type LiveAuraCategory = 'productive' | 'threshold' | 'stop'
+
+export interface LiveAuraFrameProps extends ViewProps {
+  category: LiveAuraCategory
+  /**
+   * Pulse the flood on `stop`. Uses the nativewind `animate-pulse` utility so
+   * it stays static-friendly under test (className→style, no live clock).
+   * Defaults to true.
+   */
+  pulse?: boolean
+  className?: string
+  children?: React.ReactNode
+}
+
+const categoryToken: Record<LiveAuraCategory, 'status-warning' | 'status-error' | null> = {
+  productive: null,
+  threshold: 'status-warning',
+  stop: 'status-error',
+}
+
+const floodOpacity: Record<LiveAuraCategory, number> = {
+  productive: 0,
+  threshold: 0.12,
+  stop: 0.18,
+}
+
+/** Resolved flood color for a category, or `null` when there is no flood. */
+export function liveAuraColor(category: LiveAuraCategory): string | null {
+  const token = categoryToken[category]
+  return token ? t[token] : null
+}
+
+/**
+ * Full-surface color-flood frame tied to a coaching category. Wraps `children`
+ * on a charcoal base and layers a radial wash (amber at threshold, red at stop)
+ * as a decorative, pointer-transparent overlay. The wash uses a solid
+ * `backgroundColor` fallback (native) plus a web-only `backgroundImage` radial
+ * gradient; both derive from the same semantic token via `alpha()`.
+ */
+export function LiveAuraFrame({
+  category,
+  pulse = true,
+  className,
+  children,
+  style,
+  ...props
+}: LiveAuraFrameProps) {
+  const color = liveAuraColor(category)
+  const tint = color ? alpha(color, floodOpacity[category]) : 'transparent'
+
+  // Match R2's canonical aura: a top-down radial wash that FADES TO TRANSPARENT
+  // by ~62%, so the charcoal base shows through the lower panel — NOT a flat
+  // full-surface tint. On web (the target: MCP dashboard + Storybook) render the
+  // gradient only; native has no gradient support, so fall back to a solid tint.
+  const floodStyle = {
+    ...StyleSheet.absoluteFillObject,
+    ...(Platform.OS === 'web'
+      ? // backgroundImage is a runtime RNW style, not in RN ViewStyle types.
+        { backgroundImage: `radial-gradient(130% 95% at 50% 0%, ${tint}, transparent 62%)` }
+      : { backgroundColor: tint }),
+  } as ViewStyle
+
+  return (
+    <View
+      testID="live-aura-frame"
+      className={className}
+      style={[
+        {
+          position: 'relative',
+          overflow: 'hidden',
+          borderRadius: 10,
+          backgroundColor: t['background-base'],
+          borderWidth: 1,
+          borderColor: t['border-default'],
+        },
+        style,
+      ]}
+      {...props}
+    >
+      {color && (
+        <View
+          testID="live-aura-flood"
+          accessibilityElementsHidden
+          pointerEvents="none"
+          className={category === 'stop' && pulse ? 'animate-pulse' : undefined}
+          style={floodStyle}
+        />
+      )}
+      {children}
+    </View>
+  )
+}

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

@@ -48,7 +48,7 @@ const weeks: WeekRowProps[] = [
 ]
 
 const meta: Meta<typeof MesoCard> = {
-  title: 'Custom/Workout/MesoCard',
+  title: 'Workout/MesoCard',
   component: MesoCard,
   tags: ['autodocs'],
   argTypes: {

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

@@ -4,7 +4,7 @@ import { View } from 'react-native'
 import { MesoProgressBar, type Meso } from './MesoProgressBar'
 
 const meta: Meta<typeof MesoProgressBar> = {
-  title: 'Custom/Workout/MesoProgressBar',
+  title: 'Workout/MesoProgressBar',
   component: MesoProgressBar,
   tags: ['autodocs'],
   argTypes: {

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

@@ -3,7 +3,7 @@ import { View } from 'react-native'
 import { MesoStatusCard } from './MesoStatusCard'
 
 const meta: Meta<typeof MesoStatusCard> = {
-  title: 'Custom/Workout/MesoStatusCard',
+  title: 'Workout/MesoStatusCard',
   component: MesoStatusCard,
   tags: ['autodocs'],
   argTypes: {

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

@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View } from 'react-native'
+import { MetricTiles } from './MetricTiles'
+import { getSemanticColors } from '../../../theme'
+
+const AMBER = getSemanticColors('dark')['status-warning']
+
+const meta: Meta<typeof MetricTiles> = {
+  title: 'Workout/MetricTiles',
+  component: MetricTiles,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Molecule.** An HStack of [Tile](?path=/docs/components-atoms-tile--docs). Used-by ↑ SessionHeader.',
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <View style={{ width: 246 }}>
+        <Story />
+      </View>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof MetricTiles>
+
+export const SessionStats: Story = {
+  args: {
+    metrics: [
+      { label: 'Volume', value: '76%' },
+      { label: 'Load', value: '7.3k' },
+      { label: 'Fatigue', value: 'MOD', valueColor: AMBER },
+    ],
+  },
+}
+
+export const TwoTiles: Story = {
+  args: {
+    metrics: [
+      { label: 'Time', value: '6:30 PM' },
+      { label: 'Until', value: '5h', valueColor: AMBER },
+    ],
+  },
+}
+
+export const FourTiles: Story = {
+  args: {
+    metrics: [
+      { label: 'Sets', value: '7/12' },
+      { label: 'Volume', value: '76%' },
+      { label: 'Load', value: '7.3k' },
+      { label: 'Fatigue', value: 'MOD', valueColor: AMBER },
+    ],
+  },
+}

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

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { MetricTiles } from './MetricTiles'
+
+const STATS = [
+  { label: 'Volume', value: '76%' },
+  { label: 'Load', value: '7.3k' },
+  { label: 'Fatigue', value: 'MOD', valueColor: '#F5A623' },
+]
+
+describe('MetricTiles', () => {
+  it('renders a tile per metric', () => {
+    render(<MetricTiles metrics={STATS} />)
+    expect(screen.getByText('Volume')).toBeInTheDocument()
+    expect(screen.getByText('76%')).toBeInTheDocument()
+    expect(screen.getByText('Load')).toBeInTheDocument()
+    expect(screen.getByText('7.3k')).toBeInTheDocument()
+    expect(screen.getByText('Fatigue')).toBeInTheDocument()
+    expect(screen.getByText('MOD')).toBeInTheDocument()
+  })
+
+  it('passes valueColor through to the tile value', () => {
+    render(<MetricTiles metrics={STATS} />)
+    expect(screen.getByText('MOD')).toHaveStyle({ color: '#F5A623' })
+  })
+
+  it('does not tint values without a valueColor', () => {
+    render(<MetricTiles metrics={STATS} />)
+    expect(screen.getByText('76%').style.color).toBe('')
+  })
+
+  it('reflows an arbitrary count of metrics', () => {
+    render(
+      <MetricTiles
+        metrics={[
+          { label: 'Time', value: '6:30 PM' },
+          { label: 'Until', value: '5h' },
+        ]}
+      />
+    )
+    expect(screen.getByText('6:30 PM')).toBeInTheDocument()
+    expect(screen.getByText('5h')).toBeInTheDocument()
+  })
+
+  it('passes additional props through', () => {
+    render(<MetricTiles metrics={STATS} testID="metric-tiles" />)
+    expect(screen.getByText('Volume')).toBeInTheDocument()
+  })
+
+  describe('accessibility', () => {
+    it('has no accessibility violations', async () => {
+      const { container } = render(<MetricTiles metrics={STATS} />)
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+  })
+})

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

@@ -0,0 +1,48 @@
+import { type ViewProps } from 'react-native'
+import { HStack } from '../../ui/stack'
+import { Tile } from '../../ui/tile'
+
+export interface MetricTileData {
+  /** Uppercase micro-label shown above the value */
+  label: string
+  /** Primary value */
+  value: string
+  /** Tints the value (status/accent hex); defaults to primary text */
+  valueColor?: string
+}
+
+export interface MetricTilesProps extends ViewProps {
+  /** Stat cells rendered left-to-right; typically three */
+  metrics: MetricTileData[]
+  /** Space between tiles (Stack gap scale, default 1 ≈ 4px) */
+  gap?: 0 | 1 | 2 | 3 | 4
+}
+
+/**
+ * MetricTiles — a row of equal-width stat tiles.
+ *
+ * A thin, presentational HStack of {@link Tile}. Each tile flexes to fill its
+ * share so the row reflows gracefully in a responsive rail. Used by SessionHeader
+ * for Volume / Load / Fatigue (and Date / Time / Until when upcoming).
+ *
+ * @example
+ * <MetricTiles metrics={[
+ *   { label: 'Volume', value: '76%' },
+ *   { label: 'Load', value: '7.3k' },
+ *   { label: 'Fatigue', value: 'MOD', valueColor: amber },
+ * ]} />
+ */
+export function MetricTiles({ metrics, gap = 1, ...props }: MetricTilesProps) {
+  return (
+    <HStack gap={gap} align="stretch" {...props}>
+      {metrics.map((metric) => (
+        <Tile
+          key={metric.label}
+          label={metric.label}
+          value={metric.value}
+          valueColor={metric.valueColor}
+        />
+      ))}
+    </HStack>
+  )
+}

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

@@ -3,7 +3,7 @@ import { View } from 'react-native'
 import { MuscleGroupChip, type VolumeStatus } from './MuscleGroupChip'
 
 const meta: Meta<typeof MuscleGroupChip> = {
-  title: 'Custom/Workout/MuscleGroupChip',
+  title: 'Components/Atoms/MuscleGroupChip',
   component: MuscleGroupChip,
   tags: ['autodocs'],
   argTypes: {

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

@@ -3,7 +3,7 @@ import { View } from 'react-native'
 import { PlaceholderStrip } from './PlaceholderStrip'
 
 const meta: Meta<typeof PlaceholderStrip> = {
-  title: 'Custom/Workout/PlaceholderStrip',
+  title: 'Workout/PlaceholderStrip',
   component: PlaceholderStrip,
   tags: ['autodocs'],
   argTypes: {

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

@@ -3,7 +3,7 @@ import { View } from 'react-native'
 import { PrBadge } from './PrBadge'
 
 const meta: Meta<typeof PrBadge> = {
-  title: 'Custom/Workout/PrBadge',
+  title: 'Components/Atoms/PrBadge',
   component: PrBadge,
   tags: ['autodocs'],
   argTypes: {

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

@@ -12,7 +12,7 @@ const records: PrRecord[] = [
 ]
 
 const meta: Meta<typeof PrHistoryModal> = {
-  title: 'Custom/Workout/PrHistoryModal',
+  title: 'Workout/PrHistoryModal',
   component: PrHistoryModal,
   tags: ['autodocs'],
   argTypes: {

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

@@ -18,10 +18,7 @@ const lowerMuscles: WorkoutMuscleGroup[] = [
 const upperExercises: ExerciseCardProps[] = [
   {
     name: 'Barbell Bench Press',
-    state: 'collapsed',
-    onToggle: () => {},
     summary: { sets: 4, reps: 8, weight: 185, unit: 'lbs' },
-    e1rm: { value: 235, unit: 'lbs' },
     isPR: true,
     setVelocities: [
       [1.05, 0.94, 0.82, 0.74],
@@ -31,16 +28,12 @@ const upperExercises: ExerciseCardProps[] = [
   },
   {
     name: 'Incline Dumbbell Press',
-    state: 'collapsed',
-    onToggle: () => {},
     summary: { sets: 3, reps: 10, weight: 70, unit: 'lbs' },
-    e1rm: { value: 92, unit: 'lbs' },
     totalPlannedSets: 3,
   },
   {
     name: 'Cable Triceps Pushdown',
-    state: 'upcoming',
-    onToggle: () => {},
+    upcoming: true,
     prescription: '3×12-15 @ RPE 8',
     previousBest: '50 lbs × 14',
   },
@@ -49,23 +42,18 @@ const upperExercises: ExerciseCardProps[] = [
 const lowerExercises: ExerciseCardProps[] = [
   {
     name: 'Back Squat',
-    state: 'collapsed',
-    onToggle: () => {},
     summary: { sets: 5, reps: 5, weight: 275, unit: 'lbs' },
-    e1rm: { value: 335, unit: 'lbs' },
     totalPlannedSets: 5,
   },
   {
     name: 'Romanian Deadlift',
-    state: 'upcoming',
-    onToggle: () => {},
+    upcoming: true,
     prescription: '3×8-10 @ RPE 8',
     previousBest: '225 lbs × 9',
   },
   {
     name: 'Leg Press',
-    state: 'upcoming',
-    onToggle: () => {},
+    upcoming: true,
     prescription: '3×12 @ RPE 9',
     previousBest: '450 lbs × 12',
   },
@@ -240,7 +228,7 @@ const accumulationDone: PlanMeso = {
 const mesos: PlanMeso[] = [accumulationDone, accumulation, intensification, peak]
 
 const meta: Meta<typeof ProgramPlanningPage> = {
-  title: 'Custom/Workout/ProgramPlanningPage',
+  title: 'Pages/Program Planning',
   component: ProgramPlanningPage,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],

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

@@ -154,7 +154,11 @@ function Breadcrumbs({ crumbs, onNavigate }: BreadcrumbsProps) {
         const isLast = index === crumbs.length - 1
         return (
           <View key={crumb.key} className="flex-row items-center" style={{ gap: 4 }}>
-            {index > 0 && <Text className="text-text-tertiary" style={{ fontSize: 12 }}>{'›'}</Text>}
+            {index > 0 && (
+              <Text className="text-text-tertiary" style={{ fontSize: 12 }}>
+                {'›'}
+              </Text>
+            )}
             <Pressable
               onPress={() => onNavigate(crumb.level)}
               disabled={isLast}
@@ -270,13 +274,11 @@ interface WorkoutLevelProps {
 }
 
 function WorkoutLevel({ workout, expandedExercise, onToggleExercise }: WorkoutLevelProps) {
+  // `upcoming` cards ignore `expanded`, so it's safe to wire the toggle uniformly.
   const exercises = workout.exercises.map((exercise, index) => ({
     ...exercise,
-    state:
-      exercise.state === 'upcoming'
-        ? exercise.state
-        : ((index === expandedExercise ? 'expanded' : 'collapsed') as ExerciseCardProps['state']),
-    onToggle: () => onToggleExercise(index),
+    expanded: index === expandedExercise,
+    onExpandedChange: () => onToggleExercise(index),
   }))
   return (
     <View testID="program-planning-page-workout-level">

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

@@ -10,15 +10,15 @@ component is pure import churn with no file moves.
 **Atoms** — single-purpose, no cross-component state:
 BaseBadge · WeightBadge · PrBadge · StatusDot · PlaceholderStrip · TempoBar ·
 DeviationBar · IntensityBar · WorkoutPill · MuscleGroupChip · Sparkline ·
-SupersetWrapper · InputBar
+SupersetWrapper · InputBar · MetricCell · SetsRepsLoad · ExerciseIndicator · SetBar
 
 **Molecules** — compose atoms, own a little local state:
 VelocityStrip · SetRow · TempoDisplay · RestTimer · MesoProgressBar · WeekRow ·
-WorkoutCard
+WorkoutCard · SetStrip · ExerciseHeading · ExerciseCardHeading
 
 **Organisms** — full features, often with their own data contract:
-ExerciseCard · MesoCard · MesoStatusCard · PrHistoryModal · ReadinessCheck ·
-StrengthTrendChart · CapacityBandChart · BodyMap · BodyMapDetailPanel
+ExerciseCard · SessionRail · MesoCard · MesoStatusCard · PrHistoryModal ·
+ReadinessCheck · StrengthTrendChart · CapacityBandChart · BodyMap · BodyMapDetailPanel
 
 **Pages** — phone-shaped reference screens (whole-screen compositions):
 ActiveWorkoutPage · ExerciseDetailPage · ProgramPlanningPage · TrainingStatusPage
@@ -44,7 +44,149 @@ type props without pulling the dependency.
 - **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.
+- **MetricCell is an internal composition primitive** — the shared Inter · 600 ·
+  letter-spacing-1 value/separator cell. `TempoDisplay` (tempo digits) and
+  `SetsRepsLoad` (sets × reps @ load) both compose it so the two read as one
+  visual language. Exported for composition, not for direct app use.
+- **S3 session-rail family** — `SessionRail` (organism) composes the standalone
+  `ExerciseCardHeading` molecule per exercise, which composes an `ExerciseHeading`
+  info block + a `SetStrip`:
+
+  ```
+  SessionRail
+  └─ ExerciseCardHeading            (complete standalone heading)
+     ├─ ExerciseHeading             (name/indicator + metrics, no strip)
+     │  ├─ ExerciseIndicator
+     │  ├─ SetsRepsLoad → MetricCell
+     │  └─ TempoDisplay  (showLabel={false}) → MetricCell
+     └─ SetStrip
+        └─ SetBar × N               (one set's per-rep colour bar)
+
+  ExerciseCard state="rail"  ──delegates to──▶  ExerciseCardHeading
+  ```
+
+  `ExerciseCard`'s `rail` state is now a thin adapter that delegates to
+  `ExerciseCardHeading` (so the heading is reusable without the card). `SetBar`
+  owns the per-set colour/pulse logic; `SetStrip` lays several side by side.
+  Beyond the flat `done`/`active`/`todo` sets, `SetStripSet` models set-type
+  prescriptions: `range` (variable rep-range — range-max segments, committed-todo grey
+  vs. variable-todo cyan), `drop` (one set, sub-loads split by 2px notches), `myo`
+  (done rest-pause — activation + clusters split by 3px cluster gaps), and
+  `myo-upcoming` (planned myo, length unknown — grey activation + a fading, right-open
+  cyan "clusters-to-failure" trail). The chunk-size *pattern* carries set-type identity:
+  **butted reps (0) < notch (2px) < cluster gap (3px) < set gap (5px)**. `cyan-900`
+  (`SET_STRIP_VARIABLE_COLOR`) is the shared "variable / unknown / opportunity" pin.
+  `SegmentedBar` carries these via additive `leadingGap` (per-segment left margin) and
+  static `opacity` props — the flat sets stay byte-identical.
+  `SetStrip`/`SetBar` colors are the real titan ramp pins (`primitiveRamps` red-600 /
+  orange-400 / amber-300 / green-300); the rail surfaces bind to the charcoal ramp +
+  a subtle neumorphic inset (`neumorphicShadows.charcoal.pressed.subtle`). The heading
+  design is locked in `coordination/.../S3-sessionrail/DECISIONS-ExerciseRow.md`; the
+  exploration specimens live under `Custom/Workout/Explorations/*` (do not repoint yet).
+  In Storybook the family nests by composition under **`Shell/SessionRail/…`**
+  (organism → `ExerciseCardHeading` → `ExerciseHeading` → its atoms/molecules →
+  `MetricCell`, and `SetStrip` → `SetBar`; `ExerciseCard` sits as a leaf whose
+  Composes link points at `ExerciseCardHeading`), each node's autodocs carrying a
+  **Composes** link down the tree — matching the S1/S2 shell families. (The component
+  files stay flat on disk in `custom/Workout/`; only the story `title`s build the tree.)
+
+- **VelocityStrip set-type modes (`set` prop)** — beyond the flat `velocities`
+  array (unchanged, still the source of truth for `SetRow` / `ExerciseCard`), the
+  strip accepts an optional structured `VelocitySet` descriptor and renders the
+  strength set-type vocabulary as a typed slot list. Slots are
+  `rep` (velocity-coloured) · `todo` (charcoal-300 grey) · `variable` /
+  `continue` (`SET_STRIP_VARIABLE_COLOR` cyan-900; `continue` adds a cyan-800
+  outline to read as "keep going"). Types: `straight` (done + grey todo to
+  `planned`), `range` (committed grey + a cyan variable window `floor..max`),
+  `amrap` (reps + a trailing cyan continue), `drop` (sub-loads split by a wide
+  notch), `myo` (activation + clusters split by wide gaps, `open` adds a continue),
+  `cluster` (fixed count grouped by wide intra-rest gaps). The gap hierarchy is
+  **butted reps (`REP_GAP` 2px) < chunk boundary (`WIDE_GAP` 7px)**, applied as
+  per-slot `marginLeft` (the mini container drops its uniform `gap` so wide gaps
+  render; a no-`set` strip is `[0, 2, 2, …]`, i.e. byte-identical to before). The
+  done-velocity array (`velocities`, or subloads/activation+clusters flattened) is
+  derived from the `set` and drives the mean · loss · zone summary either way. The
+  `mini` variant is the primary set-type surface; `expanded` gives `straight` the
+  active-set spotlight (velocity-height done reps + short grey stubs) and renders
+  the advanced types as a short mini-style encoding. Every modality is documented
+  with a copy-paste `set` config in **`Workout/DataViz/VelocityStrip/Set
+  Modalities`** (each card carries a `Collapse` accordion; promoted from the
+  now-deleted `S3SetModalities` Lab specimen).
 - 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.
+- **`ExerciseIndicator` taxonomy (LOCKED, TD-03.51)** — one precedence-ranked slot
+  per exercise, six distinct kinds over four tier colors (bound to titan status
+  tokens, read as literal hex via `getSemanticColors('dark')` — the TempoBar
+  pattern). Glyph = the specific signal; color = the severity tier. Chips are
+  outlined (border + glyph, no fill) so they never collide with the *filled*
+  velocity strip, and static (no pulse — they are chrome). Precedence, high → low:
+
+  | # | kind | tier | glyph (mirrors lucide) |
+  |---|------|------|------------------------|
+  | 1 | `imbalance` | danger (`status-error`) | `Scale` |
+  | 2 | `overshoot` | danger (`status-error`) | `AlertTriangle` |
+  | 3 | `velocity-loss` | warning (`status-warning`) | `TrendingDown` |
+  | 4 | `missed-reps` | warning (`status-warning`) | `CircleSlash` |
+  | 5 | `pr` | success (`status-success`) | `Award` |
+  | 6 | `info` | info (`status-info`) | `Info` |
+
+  `resolveIndicator(candidates)` collapses the active signals to the single
+  highest-precedence kind to show (`undefined` when none). Alerts outrank `pr`. The
+  glyphs are new inline SVGs in the shared `components/icons` set (not the local
+  `./icons.tsx` badge glyphs). The old generic `issue` kind is superseded by the
+  specific danger/warning kinds and was removed.
+
+## Shell/SessionRail feature area
+
+The live-workout rail is a **feature assembly**: the genuinely rail-specific parts
+(header / pace / expand drawer / set-table header) nest under `Shell/SessionRail/*`,
+while reused leaves stay in their `Workout/*` tier and are **referenced via Composes
+links, not re-homed** (`SetRow`, `ExerciseCardHeading`). This is the one deliberate
+exception to the flat `Shell` taxonomy — the NEW components below are the only
+ones that nest.
+
+```
+Shell/SessionRail                       (organism — SessionRail.tsx)
+├─ SessionHeader                        (NEW · real — title, stat tiles, chunked pace bar, ⏱ readout)
+└─ ExerciseCardHeading × N              (Workout/ · linked, NOT re-homed)
+
+Shell/SessionRail/ExpandedDrawer        (NEW · 🚧 WIP — opens when an exercise expands)
+├─ TableHeader                          (NEW · 🚧 WIP — exported as `SetTableHeader`; the generic
+│                                         `TableHeader` name is owned by the DataViz `Table`)
+└─ SetRow × N                           (Workout/ · linked, NOT re-homed)
+```
+
+- `SessionHeader` is the rail's session glance: the title over a stat row (Volume/Load/
+  Fatigue live, Date/Time/Until upcoming) and a per-exercise chunked pace bar with a
+  mono sets label + ⏱ readout. It composes the merged primitives (`MetricTiles` /
+  `ScheduleTiles` + `SegmentedProgressBar` + `TimerReadout`); the old footer pace tile is
+  gone — the header carries the glance. It is the REAL (non-WIP) new component.
+- `SetTableHeader` (story leaf `.../ExpandedDrawer/TableHeader`) is the expanded-set
+  column-header row extracted from `ExerciseCard`'s `expanded` state; `ExerciseCard`
+  now consumes it too (backward-compatible — it passes its own
+  `testID="exercise-card-column-headers"`).
+- Each new node's autodocs carry a `**Tier.** Composes […] / Used-by ↑ […]` line; the
+  WIP two (`ExpandedDrawer`, `TableHeader`) are prefixed `**🚧 WIP / placeholder.**`.
+
+## Dead candidates (do NOT remove yet — pending TD-03.56 responsive unification)
+
+Superseded by the target Shell/SessionRail scaffold; flagged now, removed only when the
+responsive level views land (removal is out of scope for this scaffold ticket):
+
+- **`setHeadingKit.tsx`** — the throwaway CSS R&D kit (raw HTML `<div>`s at the rail
+  width). Its own header says it moves into real components "when these decisions
+  harden" — which has now happened (`SessionRail` / `SessionHeader` /
+  `ExerciseCardHeading` / `ExerciseHeading` / `SetStrip` / `SetBar` /
+  `SetTableHeader`).
+- **The five `Lab/Explorations` specimens that import it** — `S3FullRail`
+  (Full Rail), `S3SessionRailHeading` (Session Rail Heading), `S3WorkoutExpansion`
+  (Workout Expansion), `S3SetTypes` (Set Types), `S3SessionPace` (Session Pace).
+  Each is superseded by a real Shell/SessionRail component + its Storybook stories;
+  `S3SessionPace` in particular is superseded by the `SessionHeader` pace glance.
+- **`ExerciseCard`'s `collapsed` / `upcoming` state representations** — the rail now
+  owns the live-list heading (`rail` state → `ExerciseCardHeading`) and the expanded
+  view is moving to `ExpandedDrawer`. Once the responsive unification (TD-03.56)
+  lands a single responsive card, the `collapsed`/`upcoming` branches of
+  `ExerciseCard` are the superseded representations to retire.

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

@@ -16,7 +16,7 @@ const staticFactors: ReadinessFactor[] = FACTOR_SEED.map((f) => ({
 }))
 
 const meta: Meta<typeof ReadinessCheck> = {
-  title: 'Custom/Workout/ReadinessCheck',
+  title: 'Workout/ReadinessCheck',
   component: ReadinessCheck,
   tags: ['autodocs'],
   argTypes: {

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

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react-vite'
 import { RestTimer } from './RestTimer'
 
 const meta: Meta<typeof RestTimer> = {
-  title: 'Custom/Workout/RestTimer',
+  title: 'Workout/RestTimer',
   component: RestTimer,
   tags: ['autodocs'],
   argTypes: {

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

@@ -2,6 +2,7 @@
 import { View, Text, Pressable } from 'react-native'
 import { resolveColor } from '../../../theme/resolve-color'
 import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { useTimer } from '../../../hooks/useTimer'
 
 const BRAND_PRIMARY = getSemanticColors('dark')['brand-primary']
 
@@ -25,17 +26,21 @@ export function RestTimer({
   visible,
   displayOnly = false,
 }: RestTimerProps) {
-  if (!visible) return null
-
-  const remainingMs = Math.max(0, totalSeconds * 1000 - elapsedMs)
+  // useTimer owns the countdown math (remaining/progress/mm:ss); a zero-duration
+  // timer is complete, which keeps the width out of the 0/0 === NaN case.
+  const {
+    remainingMs,
+    progress,
+    label: timeDisplay,
+  } = useTimer({
+    mode: 'down',
+    durationMs: totalSeconds * 1000,
+    elapsedMs,
+  })
   const remainingSec = Math.ceil(remainingMs / 1000)
-  const minutes = Math.floor(remainingSec / 60)
-  const seconds = remainingSec % 60
-  const timeDisplay = `${minutes}:${String(seconds).padStart(2, '0')}`
-  // A zero-duration timer is already complete; guard the 0 / 0 === NaN case
-  // that would otherwise emit width:'NaN%'.
-  const totalMs = totalSeconds * 1000
-  const progressPct = totalMs > 0 ? Math.min(100, (elapsedMs / totalMs) * 100) : 100
+  const progressPct = progress * 100
+
+  if (!visible) return null
 
   return (
     <View