@titan-design/react-ui 0.12.1 → 0.13.0

package/src/components/shell/SideNav.tsx

@@ -1,7 +1,6 @@
 import type { ReactNode } from 'react'
 import { View } from 'react-native'
 import { cn } from '../../utils/cn'
-import { ActivityIcon, HistoryIcon, LayersIcon, PersonStandingIcon } from '../icons'
 import { NavItem } from './NavItem'
 
 export interface SideNavItem {
@@ -14,8 +13,8 @@ export interface SideNavItem {
 }
 
 export interface SideNavProps {
-  /** Category items, top → bottom. Defaults to the four dashboard categories. */
-  items?: SideNavItem[]
+  /** Category items, top → bottom. The app owns its own categories. */
+  items: SideNavItem[]
   /** Key of the active category. */
   activeKey: string
   /** Called with the tapped item's key. */
@@ -25,30 +24,29 @@ export interface SideNavProps {
    * running off its view) → a quiet green cue on that item's label.
    */
   liveKey?: string | null
+  /** Semantic `text-*` token for the active item. Defaults to the Voltras brand. */
+  accentClassName?: string
+  /** Semantic `bg-*` token for the active bar. Pair it with `accentClassName`. */
+  accentBarClassName?: string
   className?: string
 }
 
-/** The four dashboard categories with their locked S2 glyphs (activity · history · layers · figure). */
-export const defaultNavItems: SideNavItem[] = [
-  { key: 'live', label: 'Live', icon: <ActivityIcon size={20} color="currentColor" /> },
-  { key: 'review', label: 'Review', icon: <HistoryIcon size={20} color="currentColor" /> },
-  { key: 'program', label: 'Plan', icon: <LayersIcon size={20} color="currentColor" /> },
-  { key: 'body', label: 'Body', icon: <PersonStandingIcon size={20} color="currentColor" /> },
-]
-
 /**
  * Shell S2 · SideNav — the persistent 60px left rail that switches the main
- * viewport between categories (Live · Review · Program · Body). Presentational:
- * it renders `items` and reports taps via `onNavigate`; the app owns routing and
- * which key is `live`. Active item shows a left accent bar; `liveKey` (when not
- * the active view) tints that item's label a muted green. Fixed 60px at every
- * width — labels sit under the glyph, so they never change the rail width.
+ * viewport between an app's categories. Presentational: it renders `items` and
+ * reports taps via `onNavigate`; the app owns its categories, routing, and which
+ * key is `live`. Active item shows a left accent bar in the app's brand accent;
+ * `liveKey` (when not the active view) tints that item's label a muted green.
+ * Fixed 60px at every width — labels sit under the glyph, so they never change
+ * the rail width.
  */
 export function SideNav({
-  items = defaultNavItems,
+  items,
   activeKey,
   onNavigate,
   liveKey = null,
+  accentClassName,
+  accentBarClassName,
   className,
 }: SideNavProps) {
   return (
@@ -66,6 +64,8 @@ export function SideNav({
           label={item.label}
           active={item.key === activeKey}
           live={item.key === liveKey && item.key !== activeKey}
+          accentClassName={accentClassName}
+          accentBarClassName={accentBarClassName}
           onPress={() => onNavigate?.(item.key)}
         />
       ))}

package/src/components/shell/TopBar.stories.tsx

@@ -1,44 +1,41 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Pill } from '../ui/pill'
 import { TopBar } from './TopBar'
-import { type Device } from './DeviceRow'
-
-const DEVICES: Device[] = [
-  { id: 'Voltra-A3F2', nickname: 'Left Cable', slot: 'L', state: 'connected' },
-  { id: 'Voltra-9B1C', nickname: 'Right Cable', slot: 'R', state: 'connected' },
-  { id: 'Voltra-77E0', nickname: 'Spare', slot: null, state: 'available' },
-]
+import { brandKeys } from './brands'
 
 const meta: Meta<typeof TopBar> = {
   title: 'Shell/TopBar',
   component: TopBar,
-  tags: ['autodocs'],
-  args: { state: 'live', devices: DEVICES },
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  args: { brand: 'voltras' },
   argTypes: {
-    state: { control: 'select', options: ['live', 'rest', 'idle'] },
-    devices: { control: 'object' },
+    brand: { control: 'select', options: brandKeys },
     subtitle: { control: 'text' },
     showSubtitle: { control: 'boolean' },
     showClock: { control: 'boolean' },
     time: { control: false },
-    onSelectDevice: { control: false },
+    leading: { control: false },
+    trailing: { control: false },
   },
   parameters: {
     layout: 'fullscreen',
     docs: {
       description: {
         component:
-          '**Organism** — the persistent shell chrome band, and the root of the top-bar family ' +
+          '**Organism** — the persistent shell chrome band, generic over the app ' +
           '(see `shell/README.md` for the full dependency map). Composes ' +
           '[BrandLockup](?path=/docs/shell-brandlockup--docs) + ' +
-          '[SessionStatePill](?path=/docs/shell-sessionstatepill--docs) + ' +
           '[Divider](?path=/docs/components-atoms-divider--docs) (`bg-border-prominent`) + ' +
-          '[DeviceMenu](?path=/docs/shell-devicemenu--docs) + ' +
           '[DateTime](?path=/docs/components-molecules-datetime--docs) (`variant="mono"` live clock). ' +
           'Background = the shared `surfaceGradient.chrome` primitive.\n\n' +
-          '**Try it:** use the **Controls** to change `state`, edit `devices` (set one to `lost` to see the ' +
-          'fault), or toggle `showSubtitle` / `showClock`. **Resize the canvas** to watch the ' +
-          'container-responsive collapse (SIZE-D01) — subtitle drops < 1024px, clock < 720px. ' +
-          'Click the device glyph to open the menu.',
+          '**Composition (AW-132).** The bar owns the band, the brand region, the divider ' +
+          'rhythm and the edge-pinned clock. An app supplies its own chrome through ' +
+          '`trailing` — pass an array and the bar puts its dividers between the items. ' +
+          "`leading` replaces the brand region outright. The workout app's cluster lives in " +
+          '[WorkoutTopBar](?path=/docs/shell-workout-workouttopbar--docs).\n\n' +
+          '**Try it:** switch `brand` in the **Controls**, or toggle `showSubtitle` / ' +
+          '`showClock`. **Resize the canvas** to watch the container-responsive collapse ' +
+          '(SIZE-D01) — subtitle drops < 1024px, clock < 720px.',
       },
     },
   },
@@ -46,4 +43,32 @@ const meta: Meta<typeof TopBar> = {
 export default meta
 type Story = StoryObj<typeof TopBar>
 
+/** Brand + clock only. No app has supplied any chrome. */
 export const Default: Story = {}
+
+/** Two app-supplied items in `trailing` — the bar adds the dividers and the clock. */
+export const WithAppChrome: Story = {
+  args: {
+    brand: 'brain',
+    trailing: [
+      <Pill key="index" tone="success" leading="dot" size="xs">
+        indexed
+      </Pill>,
+      <Pill key="scope" tone="neutral" size="xs">
+        4 vaults
+      </Pill>,
+    ],
+  },
+}
+
+/** One item, no array — a single node is a valid `trailing` too. */
+export const SingleTrailingItem: Story = {
+  args: {
+    brand: 'audiobook',
+    trailing: (
+      <Pill tone="brand-secondary" size="xs">
+        3 downloading
+      </Pill>
+    ),
+  },
+}

package/src/components/shell/TopBar.test.tsx

@@ -1,36 +1,58 @@
 import { describe, it, expect } from 'vitest'
 import { render, screen } from '@testing-library/react'
+import { Text } from 'react-native'
 import { axe } from 'jest-axe'
 import { TopBar } from './TopBar'
-import { type Device } from './DeviceRow'
-
-const devices: Device[] = [
-  { id: 'Voltra-A3F2', nickname: 'Left Cable', slot: 'L', state: 'connected' },
-  { id: 'Voltra-9B1C', nickname: 'Right Cable', slot: 'R', state: 'connected' },
-]
 
 const AT_1612 = new Date(2024, 0, 1, 16, 12) // local 16:12
 
 describe('TopBar', () => {
-  it('renders brand, state and a 24h clock', () => {
-    render(<TopBar state="live" devices={devices} time={AT_1612} showClock />)
+  it('renders the brand and a 24h clock', () => {
+    render(<TopBar time={AT_1612} showClock />)
     expect(screen.getByText('VOLTRAS')).toBeInTheDocument()
-    expect(screen.getByText('LIVE')).toBeInTheDocument()
     expect(screen.getByText('16:12')).toBeInTheDocument()
   })
 
+  it('renders another app brand without knowing anything about it', () => {
+    render(<TopBar brand="brain" showClock={false} />)
+    expect(screen.getByText('BRAIN')).toBeInTheDocument()
+    expect(screen.getByText('/ knowledge')).toBeInTheDocument()
+  })
+
+  it('mounts app chrome from the trailing slot', () => {
+    render(
+      <TopBar
+        showClock={false}
+        trailing={[<Text key="a">alpha</Text>, <Text key="b">beta</Text>]}
+      />
+    )
+    expect(screen.getByText('alpha')).toBeInTheDocument()
+    expect(screen.getByText('beta')).toBeInTheDocument()
+  })
+
+  it('accepts a single trailing node as well as an array', () => {
+    render(<TopBar showClock={false} trailing={<Text>solo</Text>} />)
+    expect(screen.getByText('solo')).toBeInTheDocument()
+  })
+
+  it('replaces the brand region when a leading node is given', () => {
+    render(<TopBar leading={<Text>my own lockup</Text>} showClock={false} />)
+    expect(screen.getByText('my own lockup')).toBeInTheDocument()
+    expect(screen.queryByText('VOLTRAS')).not.toBeInTheDocument()
+  })
+
   it('hides the clock when showClock is false', () => {
-    render(<TopBar state="live" devices={devices} time={AT_1612} showClock={false} />)
+    render(<TopBar time={AT_1612} showClock={false} />)
     expect(screen.queryByText('16:12')).not.toBeInTheDocument()
   })
 
   it('hides the subtitle when showSubtitle is false', () => {
-    render(<TopBar state="rest" devices={devices} showSubtitle={false} />)
+    render(<TopBar showSubtitle={false} />)
     expect(screen.queryByText('/ wall dashboard')).not.toBeInTheDocument()
   })
 
   it('has no accessibility violations', async () => {
-    const { container } = render(<TopBar state="live" devices={devices} time={AT_1612} showClock />)
+    const { container } = render(<TopBar time={AT_1612} showClock trailing={<Text>chrome</Text>} />)
     expect(await axe(container)).toHaveNoViolations()
   })
 })

package/src/components/shell/TopBar.tsx

@@ -1,28 +1,34 @@
-import { useState } from 'react'
+import { Fragment, useState, type ReactNode } from 'react'
 import { View, type LayoutChangeEvent } from 'react-native'
 import { cn } from '../../utils/cn'
 import { surfaceGradient } from '../../theme/gradients'
 import { Divider } from '../ui/divider'
 import { DateTime } from '../custom/DateTime'
 import { BrandLockup } from './BrandLockup'
-import { SessionStatePill, type SessionState } from './SessionStatePill'
-import { DeviceMenu } from './DeviceMenu'
-import { type Device } from './DeviceRow'
+import { type BrandKey } from './brands'
 
 export interface TopBarProps {
-  /** Global session state → the status pill. */
-  state: SessionState
-  /** Devices for the connection glyph + dropdown. */
-  devices: Device[]
-  /** The moment to display in the clock (Date/timestamp). Omit for a live ticking clock. */
-  time?: number | Date
-  /** Brand subtitle. Default "wall dashboard". */
+  /** Which app identity the default {@link BrandLockup} renders. */
+  brand?: BrandKey
+  /** Brand subtitle. Defaults to the brand preset's own. */
   subtitle?: string
   /** Force the subtitle on/off; defaults to container-responsive (hidden below ~1024px). */
   showSubtitle?: boolean
+  /**
+   * Replace the whole brand region. Wins over `brand` / `subtitle`, and opts out
+   * of the responsive subtitle collapse — the node owns its own behaviour.
+   */
+  leading?: ReactNode
+  /**
+   * App chrome for the right cluster, left → right. An array is rendered with the
+   * bar's own vertical dividers between the items, so an app supplies its
+   * controls and the shell keeps the divider rhythm.
+   */
+  trailing?: ReactNode | ReactNode[]
+  /** The moment to display in the clock (Date/timestamp). Omit for a live ticking clock. */
+  time?: number | Date
   /** Force the clock on/off; defaults to container-responsive (hidden below ~720px). */
   showClock?: boolean
-  onSelectDevice?: (device: Device) => void
   className?: string
 }
 
@@ -30,20 +36,39 @@ export interface TopBarProps {
 const SUBTITLE_MIN = 1024
 const CLOCK_MIN = 720
 
+function ClusterDivider() {
+  return <Divider orientation="vertical" className="h-4 bg-border-prominent" />
+}
+
+/** Interleave the bar's divider between slot items, skipping empty slots. */
+function dividedCluster(items: ReactNode[]) {
+  return items
+    .filter((item) => item !== null && item !== undefined && item !== false)
+    .map((item, i) => (
+      <Fragment key={i}>
+        {i > 0 ? <ClusterDivider /> : null}
+        {item}
+      </Fragment>
+    ))
+}
+
 /**
- * S1 · TopBar — the persistent shell chrome band. Brand (left) + a right cluster
- * of session state · device glyph · clock (clock edge-pinned so spacing stays
- * stable as the state text changes). Collapses subtitle then clock as its
- * container narrows.
+ * S1 · TopBar — the persistent shell chrome band, generic over the app. Brand
+ * (left) + a `trailing` cluster of app-supplied chrome and the wall clock (clock
+ * edge-pinned so spacing stays stable as the items' text changes). Collapses
+ * subtitle then clock as its container narrows.
+ *
+ * @example
+ * <TopBar brand="brain" trailing={[<IndexStatus />, <SearchScope />]} />
  */
 export function TopBar({
-  state,
-  devices,
-  time,
-  subtitle = 'wall dashboard',
+  brand = 'voltras',
+  subtitle,
   showSubtitle,
+  leading,
+  trailing,
+  time,
   showClock,
-  onSelectDevice,
   className,
 }: TopBarProps) {
   const [width, setWidth] = useState(SUBTITLE_MIN)
@@ -52,6 +77,18 @@ export function TopBar({
   const subtitleVisible = showSubtitle ?? width >= SUBTITLE_MIN
   const clockVisible = showClock ?? width >= CLOCK_MIN
 
+  const clock = clockVisible ? (
+    <DateTime
+      value={time}
+      live={time == null}
+      format="time"
+      hour12={false}
+      variant="mono"
+      color="secondary"
+      className="text-[11px] min-w-[38px] text-right"
+    />
+  ) : null
+
   return (
     <View
       onLayout={onLayout}
@@ -62,27 +99,11 @@ export function TopBar({
         className
       )}
     >
-      <BrandLockup subtitle={subtitle} showSubtitle={subtitleVisible} />
+      {leading ?? <BrandLockup brand={brand} subtitle={subtitle} showSubtitle={subtitleVisible} />}
 
-      {/* right cluster — order: state · device · time (time pinned to the edge) */}
+      {/* right cluster — app chrome then the clock, pinned to the edge */}
       <View className="ml-auto flex-row items-center gap-[12px]">
-        <SessionStatePill state={state} />
-        <Divider orientation="vertical" className="h-4 bg-border-prominent" />
-        <DeviceMenu devices={devices} onSelectDevice={onSelectDevice} />
-        {clockVisible ? (
-          <>
-            <Divider orientation="vertical" className="h-4 bg-border-prominent" />
-            <DateTime
-              value={time}
-              live={time == null}
-              format="time"
-              hour12={false}
-              variant="mono"
-              color="secondary"
-              className="text-[11px] min-w-[38px] text-right"
-            />
-          </>
-        ) : null}
+        {dividedCluster([...(Array.isArray(trailing) ? trailing : [trailing]), clock])}
       </View>
     </View>
   )

package/src/components/shell/brands.tsx

@@ -0,0 +1,66 @@
+import type { ReactNode } from 'react'
+import { BotIcon, BrainIcon, HeadphonesIcon, KanbanIcon, VoltrasMark } from '../icons'
+
+/** The apps that are expected to mount this shell. */
+export type BrandKey = 'voltras' | 'audiobook' | 'active-work' | 'agents' | 'brain'
+
+export interface BrandPreset {
+  /** The mark glyph, rendered at 14px through the accent token via `currentColor`. */
+  mark: ReactNode
+  /** Uppercase product wordmark. */
+  wordmark: string
+  /** Semantic text token that colours the mark. */
+  accentClassName: string
+  /**
+   * The same accent as a background token, for the nav's active bar. Declared as
+   * a literal alongside its `text-*` twin because Tailwind only emits classes it
+   * can see in the source — a name built at runtime is never generated.
+   */
+  accentBarClassName: string
+  /** Default "/ subtitle" for that app's shell. */
+  subtitle: string
+}
+
+// Accents come from `data-*` rather than `status-*`: `data-*` is the library's
+// palette of N distinct, CVD-checked hues with no semantic load, which is exactly
+// what a per-app identity accent needs. Voltras keeps the real brand token.
+export const brandPresets: Record<BrandKey, BrandPreset> = {
+  voltras: {
+    mark: <VoltrasMark size={14} color="currentColor" />,
+    wordmark: 'VOLTRAS',
+    accentClassName: 'text-brand-primary',
+    accentBarClassName: 'bg-brand-primary',
+    subtitle: 'wall dashboard',
+  },
+  audiobook: {
+    mark: <HeadphonesIcon size={14} color="currentColor" />,
+    wordmark: 'AUDIOBOOK',
+    accentClassName: 'text-data-5',
+    accentBarClassName: 'bg-data-5',
+    subtitle: 'library',
+  },
+  'active-work': {
+    mark: <KanbanIcon size={14} color="currentColor" />,
+    wordmark: 'ACTIVE WORK',
+    accentClassName: 'text-data-1',
+    accentBarClassName: 'bg-data-1',
+    subtitle: 'initiatives',
+  },
+  agents: {
+    mark: <BotIcon size={14} color="currentColor" />,
+    wordmark: 'AGENTS',
+    accentClassName: 'text-data-2',
+    accentBarClassName: 'bg-data-2',
+    subtitle: 'fleet',
+  },
+  brain: {
+    mark: <BrainIcon size={14} color="currentColor" />,
+    wordmark: 'BRAIN',
+    accentClassName: 'text-data-3',
+    accentBarClassName: 'bg-data-3',
+    subtitle: 'knowledge',
+  },
+}
+
+/** Every brand key, in the order the stories present them. */
+export const brandKeys = Object.keys(brandPresets) as BrandKey[]

package/src/components/shell/index.ts

@@ -1,13 +1,14 @@
-// Shell chrome — persistent dashboard frame (nav / top bar / rail / drawers / strip).
-// S1 · Top bar family. (Icons live in the shared `components/icons` primitive.)
+// Shell chrome — the GENERIC persistent app frame (nav / top bar / brand).
+// App-specific chrome composes this family; it never leaks back into it.
+// (Icons live in the shared `components/icons` primitive.)
+export * from './brands'
 export * from './BrandLockup'
-export * from './SessionStatePill'
-export * from './DeviceIndicator'
-export * from './DeviceRow'
-export * from './DeviceMenu'
+// S1 · Top bar family.
 export * from './TopBar'
 // S2 · Side nav family.
 export * from './NavItem'
 export * from './SideNav'
-// S3 · Dashboard shell — composes the nav + top-bar chrome over a content slot.
-export * from './DashboardShell'
+// S3 · App shell — composes the nav + top-bar chrome over a content slot.
+export * from './AppShell'
+// AW-132 · Workout-app shell, composed over the generic family above.
+export * from './workout'

package/src/components/shell/{DeviceIndicator.stories.tsx → workout/DeviceIndicator.stories.tsx}

@@ -2,9 +2,9 @@ import type { Meta, StoryObj } from '@storybook/react-vite'
 import { DeviceIndicator } from './DeviceIndicator'
 
 const meta: Meta<typeof DeviceIndicator> = {
-  title: 'Shell/DeviceIndicator',
+  title: 'Shell/Workout/DeviceIndicator',
   component: DeviceIndicator,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
   args: { status: 'connected' },
   argTypes: {
     status: { control: 'select', options: ['connected', 'degraded', 'lost'] },

package/src/components/shell/{DeviceIndicator.tsx → workout/DeviceIndicator.tsx}

@@ -1,6 +1,6 @@
 import { View, Pressable, type ViewProps } from 'react-native'
-import { cn } from '../../utils/cn'
-import { BluetoothIcon } from '../icons'
+import { cn } from '../../../utils/cn'
+import { BluetoothIcon } from '../../icons'
 
 export type DeviceConnState = 'connected' | 'degraded' | 'lost'
 

package/src/components/shell/{DeviceMenu.stories.tsx → workout/DeviceMenu.stories.tsx}

@@ -10,9 +10,9 @@ const DEVICES: Device[] = [
 ]
 
 const meta: Meta<typeof DeviceMenu> = {
-  title: 'Shell/DeviceMenu',
+  title: 'Shell/Workout/DeviceMenu',
   component: DeviceMenu,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
   args: { devices: DEVICES, isOpen: false },
   argTypes: {
     devices: { control: 'object' },

package/src/components/shell/{DeviceMenu.tsx → workout/DeviceMenu.tsx}

@@ -1,7 +1,7 @@
 import { View } from 'react-native'
-import { cn } from '../../utils/cn'
-import { Typography } from '../custom/Typography'
-import { Popover, PopoverTrigger, PopoverContent } from '../ui/popover'
+import { cn } from '../../../utils/cn'
+import { Typography } from '../../custom/Typography'
+import { Popover, PopoverTrigger, PopoverContent } from '../../ui/popover'
 import { DeviceIndicator, type DeviceConnState } from './DeviceIndicator'
 import { DeviceRow, type Device } from './DeviceRow'
 

package/src/components/shell/{DeviceRow.stories.tsx → workout/DeviceRow.stories.tsx}

@@ -3,9 +3,9 @@ import { View } from 'react-native'
 import { DeviceRow } from './DeviceRow'
 
 const meta: Meta<typeof DeviceRow> = {
-  title: 'Shell/DeviceRow',
+  title: 'Shell/Workout/DeviceRow',
   component: DeviceRow,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
   args: {
     device: { id: 'Voltra-A3F2', nickname: 'Left Cable', slot: 'L', state: 'connected' },
   },

package/src/components/shell/{DeviceRow.tsx → workout/DeviceRow.tsx}

@@ -1,7 +1,7 @@
 import { View, Pressable, type ViewProps } from 'react-native'
-import { cn } from '../../utils/cn'
-import { Indicator, type IndicatorColor } from '../ui/indicator'
-import { Typography } from '../custom/Typography'
+import { cn } from '../../../utils/cn'
+import { Indicator, type IndicatorColor } from '../../ui/indicator'
+import { Typography } from '../../custom/Typography'
 
 export type DeviceRowState = 'connected' | 'available' | 'degraded' | 'lost'
 

package/src/components/shell/{SessionStatePill.stories.tsx → workout/SessionStatePill.stories.tsx}

@@ -2,9 +2,9 @@ import type { Meta, StoryObj } from '@storybook/react-vite'
 import { SessionStatePill } from './SessionStatePill'
 
 const meta: Meta<typeof SessionStatePill> = {
-  title: 'Shell/SessionStatePill',
+  title: 'Shell/Workout/SessionStatePill',
   component: SessionStatePill,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
   args: { state: 'live' },
   argTypes: {
     state: { control: 'select', options: ['live', 'rest', 'idle'] },

package/src/components/shell/{SessionStatePill.tsx → workout/SessionStatePill.tsx}

@@ -1,7 +1,7 @@
 import { View, type ViewProps } from 'react-native'
-import { cn } from '../../utils/cn'
-import { Indicator, type IndicatorColor, type IndicatorPulse } from '../ui/indicator'
-import { Typography, type TypographyColor } from '../custom/Typography'
+import { cn } from '../../../utils/cn'
+import { Indicator, type IndicatorColor, type IndicatorPulse } from '../../ui/indicator'
+import { Typography, type TypographyColor } from '../../custom/Typography'
 
 export type SessionState = 'live' | 'rest' | 'idle'
 
@@ -32,6 +32,8 @@ const stateConfig: Record<
  * The global session-state readout (dot + label). Shared: the top bar's status
  * and the Live-view header both use it (this is the ledger's "StatusPill",
  * Family C — built once). S1 · SessionStatePill.
+ *
+ * @deprecated Use `<Pill tone="…" leading="dot">` — removed after AW-127 consumer migration.
  */
 export function SessionStatePill({ state, label, className, ...props }: SessionStatePillProps) {
   const cfg = stateConfig[state]

package/src/components/shell/workout/WorkoutShell.stories.tsx

@@ -0,0 +1,71 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View } from 'react-native'
+import { WorkoutShell } from './WorkoutShell'
+import { Surface } from '../../ui/surface'
+import { Typography } from '../../custom/Typography'
+
+/**
+ * `Pages/WorkoutShell` — the workout wall-dashboard chrome as one registered surface.
+ * Composes the generic AppShell and fills its slots with the workout's own chrome, so
+ * the dashboard app mounts a single component.
+ */
+const meta: Meta<typeof WorkoutShell> = {
+  title: 'Pages/WorkoutShell',
+  component: WorkoutShell,
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          '**Page shell (workout app).** Composes ' +
+          '[AppShell](?path=/docs/pages-appshell--docs) and fills its top-bar slot with ' +
+          '[WorkoutTopBar](?path=/docs/shell-workout-workouttopbar--docs) — which pulls in ' +
+          'DeviceMenu, DeviceRow, DeviceIndicator and SessionStatePill — and its nav slot with ' +
+          'the four workout categories. Mount this instead of re-assembling the chrome per ' +
+          'view.\n\nThis is the AW-132 shape: the generic shell knows nothing about devices or ' +
+          'session state; this component is the whole workout-specific surface.',
+      },
+    },
+  },
+  argTypes: {
+    state: { control: 'select', options: ['live', 'rest', 'idle'] },
+    activeKey: { control: 'select', options: ['live', 'review', 'program', 'body'] },
+    liveKey: { control: 'select', options: [null, 'live', 'review', 'program', 'body'] },
+    onNavigate: { control: false },
+    onSelectDevice: { control: false },
+  },
+  decorators: [
+    (Story) => (
+      <Surface level="base" style={{ height: '100vh' as unknown as number }}>
+        <Story />
+      </Surface>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof WorkoutShell>
+
+export const Default: Story = {
+  args: { activeKey: 'live', state: 'live' },
+}
+
+export const WithContent: Story = {
+  args: { activeKey: 'review', state: 'rest', liveKey: 'live' },
+  render: (args) => (
+    <WorkoutShell {...args}>
+      <View className="flex-1 gap-1.5 p-7">
+        <Typography variant="h4" color="primary">
+          Review
+        </Typography>
+        <Typography variant="body2" color="tertiary">
+          A page mounts its content here; the shell keeps the nav + top-bar chrome persistent.
+        </Typography>
+      </View>
+    </WorkoutShell>
+  ),
+  parameters: {
+    docs: { description: { story: 'The shell with a page mounted in its content slot.' } },
+  },
+}