@titan-design/react-ui 0.6.0 → 0.8.0

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

@@ -0,0 +1,405 @@
+/**
+ * Row Inventory — a READ-ONLY survey of every existing way the Workout library renders
+ * "an exercise / set / workout / week / mesocycle" as a row / list-entry / card.
+ *
+ * Built from the 2026-07-08 duplication audit (S3 SessionRail reuse question). This pane only
+ * NAMES and DISPLAYS what exists — no extraction, no changes to the components. It's here so we
+ * can eyeball the overlapping row representations together before deciding a reuse strategy.
+ */
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Component, type ReactNode } from 'react'
+import { View, Text } from 'react-native'
+import { ExerciseCard } from './ExerciseCard'
+import { SetRow } from './SetRow'
+import { WorkoutCard } from './WorkoutCard'
+import { WorkoutPill } from './WorkoutPill'
+import { WeekRow } from './WeekRow'
+import { MesoCard } from './MesoCard'
+import { MesoProgressBar } from './MesoProgressBar'
+import { MuscleGroupChip } from './MuscleGroupChip'
+import { StatusDot } from './StatusDot'
+import { WeightBadge } from './WeightBadge'
+import { PrBadge } from './PrBadge'
+import { PlaceholderStrip } from './PlaceholderStrip'
+import { SupersetWrapper } from './SupersetWrapper'
+
+// ----------------------------------------------------------------------------- gallery scaffold
+class Boundary extends Component<{ children: ReactNode }, { err: string | null }> {
+  state = { err: null as string | null }
+  static getDerivedStateFromError(e: Error) {
+    return { err: e.message }
+  }
+  render() {
+    if (this.state.err)
+      return (
+        <div style={{ color: '#ff6b6b', fontFamily: 'monospace', fontSize: 11, padding: 8 }}>
+          render error: {this.state.err}
+        </div>
+      )
+    return this.props.children
+  }
+}
+
+function Cell({
+  name,
+  entity,
+  expand,
+  width = 340,
+  children,
+}: {
+  name: string
+  entity: string
+  expand: string
+  width?: number
+  children: ReactNode
+}) {
+  return (
+    <div
+      style={{
+        width,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 8,
+        padding: 14,
+        borderRadius: 12,
+        border: '1px solid #24262d',
+        background: '#131418',
+      }}
+    >
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+        <span style={{ fontSize: 13, fontWeight: 800, color: '#E8EAED' }}>{name}</span>
+        <span
+          style={{ fontFamily: 'monospace', fontSize: 10, color: '#5b616d', letterSpacing: 0.3 }}
+        >
+          {entity} · {expand}
+        </span>
+      </div>
+      <div style={{ marginTop: 2 }}>
+        <Boundary>{children}</Boundary>
+      </div>
+    </div>
+  )
+}
+
+function Section({ title, note, children }: { title: string; note?: string; children: ReactNode }) {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+      <div style={{ display: 'flex', alignItems: 'baseline', gap: 10 }}>
+        <span
+          style={{
+            fontSize: 11,
+            fontWeight: 800,
+            letterSpacing: 1.2,
+            textTransform: 'uppercase',
+            color: '#FF7900',
+          }}
+        >
+          {title}
+        </span>
+        {note && <span style={{ fontSize: 11, color: '#8D95A3' }}>{note}</span>}
+      </div>
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 14, alignItems: 'flex-start' }}>
+        {children}
+      </div>
+    </div>
+  )
+}
+
+// ----------------------------------------------------------------------------- sample data
+const setVel = [
+  [0.6, 0.58, 0.55, 0.52],
+  [0.58, 0.55, 0.53, 0.5],
+  [0.55, 0.52, 0.5, 0.47],
+]
+const exSets = [1, 2, 3, 4].map((n) => ({
+  state: 'done' as const,
+  setNumber: n,
+  reps: 8,
+  weight: 145,
+  rpe: 6.5 + n * 0.5,
+  unit: 'lbs' as const,
+  velocities: setVel[(n - 1) % 3],
+}))
+const weeks = [
+  {
+    weekNumber: 1,
+    workouts: [
+      { name: 'Upper', status: 'completed' as const },
+      { name: 'Lower', status: 'completed' as const },
+    ],
+  },
+  {
+    weekNumber: 2,
+    workouts: [
+      { name: 'Upper', status: 'current' as const },
+      { name: 'Lower', status: 'upcoming' as const },
+    ],
+  },
+  {
+    weekNumber: 3,
+    workouts: [
+      { name: 'Upper', status: 'upcoming' as const },
+      { name: 'Lower', status: 'upcoming' as const },
+    ],
+  },
+]
+const mesos = [
+  { id: 'm1', name: 'Accumulation', weekCount: 4, status: 'completed' as const },
+  { id: 'm2', name: 'Intensification', weekCount: 3, status: 'current' as const, currentWeek: 2 },
+  { id: 'm3', name: 'Peak', weekCount: 2, status: 'upcoming' as const },
+]
+
+// ----------------------------------------------------------------------------- the pane
+const meta: Meta = {
+  title: 'Lab/Audits/Row Inventory',
+  parameters: { layout: 'fullscreen' },
+}
+export default meta
+type Story = StoryObj
+
+export const AllRows: Story = {
+  name: 'All row representations',
+  render: () => (
+    <div
+      style={{
+        minHeight: '100vh',
+        background: '#0c0d0f',
+        padding: 28,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 34,
+        fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+      }}
+    >
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+        <span style={{ fontSize: 20, fontWeight: 800, color: '#E8EAED' }}>
+          Workout library · row representations
+        </span>
+        <span style={{ fontSize: 12, color: '#8D95A3', maxWidth: 720 }}>
+          Every existing component that draws an exercise / set / workout / week / meso as a list
+          entry. Read-only survey for the S3 reuse decision — names + entity + expand behavior, no
+          code changes.
+        </span>
+      </div>
+
+      <Section
+        title="Exercise"
+        note="3 representations of the one ExerciseCard: collapsed glance, expanded body, upcoming"
+      >
+        <Cell name="ExerciseCard" entity="exercise" expand="collapsed · expandable">
+          <ExerciseCard
+            name="Seated Cable Row"
+            summary={{ sets: 4, reps: 8, weight: 145, unit: 'lbs' }}
+            isPR
+            totalPlannedSets={5}
+            setVelocities={setVel}
+          />
+        </Cell>
+        <Cell name="ExerciseCard" entity="exercise" expand="expanded → reveals SetRows">
+          <ExerciseCard
+            name="Seated Cable Row"
+            defaultExpanded
+            summary={{ sets: 4, reps: 8, weight: 145, unit: 'lbs' }}
+            tempo={[3, 1, 2, 0]}
+            sets={exSets}
+          />
+        </Cell>
+        <Cell name="ExerciseCard" entity="exercise" expand="upcoming (static)">
+          <ExerciseCard
+            name="Face Pull"
+            upcoming
+            prescription="3 × 12-15 @ RPE 7"
+            previousBest="15 × 35 lb"
+          />
+        </Cell>
+      </Section>
+
+      <Section
+        title="Set"
+        note="SetRow is the primitive — one row per set lifecycle state (done / live / todo)"
+      >
+        <Cell name="SetRow" entity="set · done" expand="no · flat mini strip" width={360}>
+          <SetRow
+            state="done"
+            setNumber={1}
+            reps={8}
+            weight={145}
+            rpe={8}
+            unit="lbs"
+            velocities={[0.6, 0.58, 0.55, 0.52]}
+          />
+        </Cell>
+        <Cell name="SetRow" entity="set · live" expand="no · compact spotlight" width={360}>
+          <SetRow
+            state="live"
+            setNumber={2}
+            unit="lbs"
+            target={{ reps: 8, weight: 145 }}
+            reps={8}
+            weight={145}
+            velocities={[0.58, 0.55, 0.53, 0.5]}
+          />
+        </Cell>
+        <Cell name="SetRow" entity="set · todo" expand="no · grey stub strip" width={360}>
+          <SetRow state="todo" setNumber={4} unit="lbs" target={{ reps: 8, weight: 145 }} />
+        </Cell>
+      </Section>
+
+      <Section
+        title="Workout"
+        note="WorkoutCard (full) and WorkoutPill (chip) = two legit densities; ExerciseDetailPage overloads ExerciseCard as a 3rd"
+      >
+        <Cell
+          name="WorkoutCard"
+          entity="workout"
+          expand="expandable · expanded+onToggle → ExerciseCards"
+          width={380}
+        >
+          <WorkoutCard
+            name="Push Day A"
+            date="Mon · Jul 6"
+            duration="52 min"
+            status="today"
+            muscleGroups={[
+              { group: 'chest', label: 'Chest', volumeStatus: 'productive' },
+              { group: 'delts', label: 'Delts', volumeStatus: 'maintenance' },
+              { group: 'triceps', label: 'Triceps', volumeStatus: 'under' },
+            ]}
+            totalSets={18}
+            totalVolume={7340}
+            unit="lbs"
+            onToggle={() => {}}
+          />
+        </Cell>
+        <Cell name="WorkoutPill" entity="workout · chip" expand="no">
+          <View style={{ flexDirection: 'row', gap: 8, flexWrap: 'wrap' }}>
+            <WorkoutPill name="Push" status="completed" />
+            <WorkoutPill name="Pull" status="current" />
+            <WorkoutPill name="Legs" status="upcoming" />
+            <WorkoutPill name="Deload" status="deload" />
+          </View>
+        </Cell>
+      </Section>
+
+      <Section
+        title="Week"
+        note="WeekRow is the primitive; ExerciseDetailPage overloads ExerciseCard as a competing week row"
+      >
+        <Cell
+          name="WeekRow"
+          entity="week"
+          expand="no · row of WorkoutPills + intensity bar"
+          width={380}
+        >
+          <WeekRow
+            weekNumber={3}
+            totalWeeks={4}
+            isCurrent
+            intensityLevel={0.55}
+            intensityThreshold={0.8}
+            workouts={weeks[1].workouts}
+          />
+        </Cell>
+      </Section>
+
+      <Section
+        title="Mesocycle"
+        note="3 views for different jobs (list card / timeline / detail) — each with its own status enum"
+      >
+        <Cell
+          name="MesoCard"
+          entity="meso"
+          expand="expandable · expanded+onToggle → WeekRows"
+          width={380}
+        >
+          <MesoCard
+            name="Accumulation"
+            goal="Hypertrophy"
+            split="Upper/Lower"
+            weekRange="Weeks 1-4"
+            currentWeek={2}
+            totalWeeks={4}
+            weeks={weeks}
+            volumeHeatmap={[
+              { group: 'chest', percentage: 80 },
+              { group: 'back', percentage: 70 },
+              { group: 'legs', percentage: 90 },
+            ]}
+          />
+        </Cell>
+        <Cell name="MesoProgressBar" entity="meso · timeline" expand="no · segments" width={380}>
+          <MesoProgressBar mesos={mesos} />
+        </Cell>
+      </Section>
+
+      <Section
+        title="Shared sub-parts"
+        note="appear inside the rows above — not entity rows themselves"
+      >
+        <Cell name="MuscleGroupChip" entity="muscle-group" expand="no">
+          <View style={{ flexDirection: 'row', gap: 8, flexWrap: 'wrap' }}>
+            <MuscleGroupChip name="Chest" volumeStatus="ontrack" />
+            <MuscleGroupChip name="Quads" volumeStatus="behind" />
+            <MuscleGroupChip name="Lats" volumeStatus="over" />
+          </View>
+        </Cell>
+        <Cell name="StatusDot" entity="status glyph" expand="no">
+          <StatusDot variant="success" label="On track" />
+        </Cell>
+        <Cell name="WeightBadge" entity="badge" expand="no">
+          <View style={{ flexDirection: 'row', gap: 8 }}>
+            <WeightBadge value={205} unit="lbs" />
+            <WeightBadge value={217} unit="lbs" isPr />
+          </View>
+        </Cell>
+        <Cell name="PrBadge" entity="badge" expand="no">
+          <PrBadge type="e1rm" animate={false} />
+        </Cell>
+        <Cell name="PlaceholderStrip" entity="pending-set strip" expand="no">
+          <View style={{ flexDirection: 'row', gap: 4 }}>
+            <PlaceholderStrip />
+            <PlaceholderStrip />
+            <PlaceholderStrip />
+          </View>
+        </Cell>
+        <Cell name="SupersetWrapper" entity="grouping bracket" expand="no">
+          <SupersetWrapper label="SS1" color="#FF7900">
+            <View style={{ padding: 10, backgroundColor: '#1C1C1C', borderRadius: 8 }}>
+              <Text style={{ color: '#F3F4F6' }}>Exercise A</Text>
+            </View>
+            <View style={{ padding: 10, backgroundColor: '#1C1C1C', borderRadius: 8 }}>
+              <Text style={{ color: '#F3F4F6' }}>Exercise B</Text>
+            </View>
+          </SupersetWrapper>
+        </Cell>
+      </Section>
+
+      <Section
+        title="Page-level organisms"
+        note="composition roots (390px+), not rows — listed for reference, see their own stories"
+      >
+        {[
+          ['ActiveWorkoutPage', 'renders ExerciseCards + SupersetWrapper + InputBar/RestTimer'],
+          ['ProgramPlanningPage', 'MesoProgressBar + MesoCard → WeekRow → WorkoutCard drill-down'],
+          ['ExerciseDetailPage', 'EntryList overloads ExerciseCard as week AND session rows'],
+          ['MesoStatusCard', 'per-exercise meso detail card (StatusDot + metric grid + gauges)'],
+          ['ReadinessCheck', 'pre-workout factor rows + score gauge'],
+        ].map(([n, d]) => (
+          <div
+            key={n}
+            style={{
+              width: 340,
+              padding: 14,
+              borderRadius: 12,
+              border: '1px dashed #31343d',
+              background: '#0f1012',
+            }}
+          >
+            <div style={{ fontSize: 13, fontWeight: 800, color: '#E8EAED' }}>{n}</div>
+            <div style={{ fontSize: 11, color: '#8D95A3', marginTop: 4 }}>{d}</div>
+          </div>
+        ))}
+      </Section>
+    </div>
+  ),
+}

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

@@ -0,0 +1,34 @@
+/**
+ * SHEET · Finalization — the full session rail next to the left nav (neumorphic).
+ * Open item: depth tuning · 4-vs-8px strip height · indicator taxonomy. See DECISIONS-ExerciseRow doc.
+ */
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { NavStub, Rail, Page, T_TERTIARY } from './setHeadingKit'
+
+type Args = { stripHeight: number }
+const meta: Meta<Args> = {
+  title: 'Lab/Explorations/Full Rail',
+  parameters: { layout: 'fullscreen' },
+  argTypes: { stripHeight: { control: { type: 'range', min: 3, max: 14, step: 1 } } },
+  args: { stripHeight: 8 },
+}
+export default meta
+type Story = StoryObj<Args>
+
+export const NextToNav: Story = {
+  name: 'Full look · next to left nav',
+  render: (args) => (
+    <Page
+      title="Session rail — full look next to left nav"
+      note="Neumorphic: flat raised nav + heading plane (#1F1F1F); sunk inset exercise list (#131313), depth from the list's inset shadows only. Per-set segmented strip · active pulse · tempo language · no e1RM. Drag stripHeight. OPEN: 4 vs 8px · depth tuning · left-inset strength · indicator taxonomy."
+    >
+      <div style={{ display: 'flex', alignItems: 'stretch', width: 'fit-content' }}>
+        <NavStub />
+        <Rail stripH={args.stripHeight} />
+        <div style={{ width: 140, background: '#161616', alignSelf: 'stretch', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+          <span style={{ fontSize: 10, color: T_TERTIARY, fontFamily: 'monospace' }}>stage</span>
+        </div>
+      </div>
+    </Page>
+  ),
+}

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

@@ -0,0 +1,95 @@
+/**
+ * SHEET · Session Pace — the rail-footer pace tile (NAV-D05: VMCP-primary, plan-aware trim/add).
+ * PRESENTATIONAL only; the derivation (session time-model + trim/add heuristic) is a separate VMCP/WA
+ * ticket (no WA support today). OPEN: which metrics earn the row · behind/ahead visual · idle treatment ·
+ * whether it restores a CapacityBandChart. See DECISIONS-ExerciseRow doc.
+ */
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import type { ReactNode } from 'react'
+import { AMBER, GREEN, INSET, RAISED, T_PRIMARY, T_SECONDARY, T_TERTIARY, ORANGE, Page, monoTag } from './setHeadingKit'
+
+type PaceState = 'behind' | 'ahead' | 'idle'
+
+function Metric({ k, v, color }: { k: string; v: string; color?: string }) {
+  return (
+    <div style={{ flex: 1, textAlign: 'center', background: RAISED, borderRadius: 7, padding: '6px 3px' }}>
+      <div style={{ fontSize: 8, textTransform: 'uppercase', letterSpacing: 0.4, color: T_TERTIARY, fontWeight: 800 }}>{k}</div>
+      <div style={{ fontFamily: 'monospace', fontSize: 13, fontWeight: 800, marginTop: 2, color: color ?? T_PRIMARY }}>{v}</div>
+    </div>
+  )
+}
+function Suggest({ tone, children }: { tone: 'behind' | 'ahead'; children: ReactNode }) {
+  const color = tone === 'behind' ? AMBER : GREEN
+  return (
+    <div style={{ fontSize: 10.5, lineHeight: 1.4, borderRadius: 8, padding: '8px 9px', display: 'flex', gap: 7, alignItems: 'flex-start', color, background: tone === 'behind' ? 'rgba(249,180,21,0.10)' : 'rgba(46,213,115,0.10)', border: `1px solid ${tone === 'behind' ? 'rgba(249,180,21,0.30)' : 'rgba(46,213,115,0.28)'}` }}>
+      <span style={{ flex: '0 0 auto', fontSize: 12 }}>{tone === 'behind' ? '▲' : '＋'}</span>
+      <div>{children}</div>
+    </div>
+  )
+}
+const b = (t: string) => <b style={{ color: T_PRIMARY }}>{t}</b>
+
+// The pace tile — lives pinned in the rail footer (inset surface).
+function SessionPaceTile({ state }: { state: PaceState }) {
+  if (state === 'idle') {
+    return (
+      <div style={{ width: 246, background: INSET, borderTop: `1px solid #1C1C1C`, padding: '11px 12px', display: 'flex', flexDirection: 'column', gap: 8 }}>
+        <div style={{ fontSize: 10, fontWeight: 800, letterSpacing: 0.6, textTransform: 'uppercase', color: ORANGE }}>Next session budget</div>
+        <div style={{ display: 'flex', alignItems: 'baseline', gap: 6, fontFamily: 'monospace' }}>
+          <span style={{ fontSize: 20, fontWeight: 800, color: T_PRIMARY }}>~52:00</span>
+          <span style={{ fontSize: 11, color: T_SECONDARY }}>planned · Lower B</span>
+        </div>
+        <Suggest tone="ahead">6 exercises · ~20 sets. Wall wakes to Live when the first set streams.</Suggest>
+      </div>
+    )
+  }
+  const behind = state === 'behind'
+  return (
+    <div style={{ width: 246, background: INSET, borderTop: `1px solid #1C1C1C`, padding: '11px 12px', display: 'flex', flexDirection: 'column', gap: 8 }}>
+      <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+        <span style={{ fontSize: 10, fontWeight: 800, letterSpacing: 0.6, textTransform: 'uppercase', color: ORANGE }}>Session Pace</span>
+        <span style={{ fontSize: 8, fontFamily: 'monospace', color: T_TERTIARY, border: `1px solid #2C2C2C`, borderRadius: 5, padding: '2px 5px' }}>{behind ? 'show ahead ▸' : 'show behind ▸'}</span>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'baseline', gap: 6, fontFamily: 'monospace' }}>
+        <span style={{ fontSize: 20, fontWeight: 800, color: T_PRIMARY }}>42:18</span>
+        <span style={{ fontSize: 11, color: T_SECONDARY }}>of 60:00 budget</span>
+      </div>
+      <div style={{ height: 6, borderRadius: 3, background: '#22252c', position: 'relative', overflow: 'hidden' }}>
+        <div style={{ position: 'absolute', left: 0, top: 0, bottom: 0, width: '70%', borderRadius: 3, background: behind ? AMBER : GREEN }} />
+      </div>
+      <div style={{ display: 'flex', gap: 4 }}>
+        <Metric k="Volume" v="76%" />
+        <Metric k="Load" v="7.3k" />
+        <Metric k="Fatigue" v="MOD" color={AMBER} />
+      </div>
+      {behind ? (
+        <Suggest tone="behind">{b('Behind pace')} — ~9 min over budget at this rate. Drop {b('Face Pull')} to 2 sets to finish on time.</Suggest>
+      ) : (
+        <Suggest tone="ahead">{b('Ahead of pace')} — ~7 min of headroom. Room to add a {b('Cable Fly')} drop-set or a back-off set on Row.</Suggest>
+      )}
+    </div>
+  )
+}
+
+const meta: Meta = { title: 'Lab/Explorations/Session Pace', parameters: { layout: 'fullscreen' } }
+export default meta
+type Story = StoryObj
+
+export const States: Story = {
+  name: 'Pace tile · behind / ahead / idle',
+  render: () => (
+    <Page
+      title="Session Pace — rail footer tile"
+      note="VMCP-primary (NAV-D05): behind → what to trim · ahead → what to add · idle → next-session budget. Presentational; derivation is a separate VMCP/WA ticket (no WA session time-model today). Surfaces on real tokens."
+    >
+      <div style={{ display: 'flex', gap: 32, flexWrap: 'wrap' }}>
+        {(['behind', 'ahead', 'idle'] as PaceState[]).map((s) => (
+          <div key={s} style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+            <span style={monoTag}>{s}</span>
+            <SessionPaceTile state={s} />
+          </div>
+        ))}
+      </div>
+    </Page>
+  ),
+}

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

@@ -0,0 +1,61 @@
+/**
+ * SHEET · Session Rail Heading — the always-shown exercise heading unit, in isolation.
+ * Locked: name row + indicator · tight sets/reps/load (tempo language) + tempo · per-set segmented strip
+ * (completed colored · active pulse + grey remainder · upcoming grey). OPEN: strip height · indicator taxonomy
+ * · rep-range treatment · set-types (drop/myo). See DECISIONS-ExerciseRow doc.
+ */
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Heading, INSET, INSET_SHADOW, Page, monoTag, reps, type Exercise } from './setHeadingKit'
+
+const DONE: Exercise = { name: 'Seated Cable Row', sets: 5, reps: 8, load: 145, tempo: [3, 1, 2, 0], indicator: 'pr', setStates: [1.0, 0.9, 0.8, 0.7, 0.6].map((s) => ({ status: 'done', reps: reps(8, s) })) }
+const ACTIVE: Exercise = { name: 'Cable Chest Press', sets: 3, reps: 10, load: 90, tempo: [2, 1, 2, 0], indicator: 'info', setStates: [{ status: 'done', reps: reps(10, 0.72) }, { status: 'active', reps: reps(5, 0.62), planned: 10 }, { status: 'todo', planned: 10 }] }
+const UPCOMING: Exercise = { name: 'Standing Calf Raise', sets: 5, reps: 20, load: 25, tempo: [2, 1, 2, 0], upcoming: true, setStates: [1, 2, 3, 4, 5].map(() => ({ status: 'todo', planned: 20 })) }
+const RANGE: Exercise = { name: 'Face Pull', sets: 3, reps: '15-20', load: 40, tempo: [2, 1, 2, 0], setStates: [1, 2, 3].map(() => ({ status: 'todo', planned: 18 })) }
+
+// a heading on the sunk inset surface, at the real rail width
+function Row({ ex, h }: { ex: Exercise; h: number }) {
+  return (
+    <div style={{ width: 246, background: INSET, boxShadow: INSET_SHADOW }}>
+      <Heading ex={ex} stripH={h} />
+    </div>
+  )
+}
+
+type Args = { stripHeight: number }
+const meta: Meta<Args> = {
+  title: 'Lab/Explorations/Session Rail Heading',
+  parameters: { layout: 'fullscreen' },
+  argTypes: { stripHeight: { control: { type: 'range', min: 3, max: 14, step: 1 } } },
+  args: { stripHeight: 8 },
+}
+export default meta
+type Story = StoryObj<Args>
+
+export const States: Story = {
+  name: 'Heading · states + heights',
+  render: (args) => (
+    <Page
+      title="Session rail heading — the exercise unit"
+      note="The always-shown heading: name + indicator · tight sets/reps/load (tempo language) + tempo · per-set strip. Left column = the three states at the current height; right = the completed heading across 4 / 6 / 8 / 10px."
+    >
+      <div style={{ display: 'flex', gap: 48, flexWrap: 'wrap' }}>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 14 }}>
+          {([['completed', DONE], ['active (pulsing)', ACTIVE], ['upcoming', UPCOMING], ['rep range', RANGE]] as [string, Exercise][]).map(([lbl, ex]) => (
+            <div key={lbl} style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+              <span style={monoTag}>{lbl}</span>
+              <Row ex={ex} h={args.stripHeight} />
+            </div>
+          ))}
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 14 }}>
+          {[4, 6, 8, 10].map((h) => (
+            <div key={h} style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+              <span style={monoTag}>strip {h}px</span>
+              <Row ex={DONE} h={h} />
+            </div>
+          ))}
+        </div>
+      </div>
+    </Page>
+  ),
+}