@titan-design/react-ui 0.12.0 → 0.13.0

package/src/components/custom/Fatigue/panel-layout.ts

@@ -0,0 +1,185 @@
+/**
+ * The {@link LiveFatiguePanel}'s responsive layout, as one pure function (TD-03.58).
+ *
+ * The panel is container-responsive, not prop-sized (SIZE-D01): it measures its own width
+ * in `onLayout` and feeds it here. Everything the two columns need — whether they stack,
+ * the padding, the gap, the card's width, and the split of the ONE body height — comes out
+ * of this one call, so the hero and the card cannot disagree about any of it.
+ *
+ * Pure, with no `react-native` import, so the breakpoint behaviour is unit-testable
+ * without `onLayout` (which never fires under jsdom).
+ *
+ * SOURCED vs CHOSEN. The breakpoint edges are titan's own `primitiveBreakpoints` — not
+ * invented here. The per-tier padding/gap/card numbers below the `md` edge, the `xl`
+ * card-width ratio and its cap, and the stacked height share ARE chosen; each is a single
+ * named constant and each is called out in the PR body.
+ */
+import { primitiveBreakpoints } from '../../../theme/tokens/primitives'
+
+/** titan's breakpoint scale, re-exported as the panel's tier edges. Sourced, not chosen. */
+export const PANEL_BREAKPOINTS = primitiveBreakpoints
+
+export type PanelTier = keyof typeof PANEL_BREAKPOINTS
+
+/**
+ * The `md` edge (1000) is where the two columns fit side by side: the card's own default
+ * 318 plus the hero's usable minimum plus the padding and gap. Below it they stack.
+ */
+const ROW_TIER_MIN = PANEL_BREAKPOINTS.md
+
+/**
+ * The tier for a measured container width. An unmeasured container (0, before the first
+ * `onLayout`) resolves to `md` — today's side-by-side geometry — so the first paint matches
+ * what the panel has always rendered rather than flashing a stacked layout.
+ */
+export function panelTier(width: number): PanelTier {
+  if (width <= 0) return 'md'
+  if (width >= PANEL_BREAKPOINTS.xl) return 'xl'
+  if (width >= PANEL_BREAKPOINTS.lg) return 'lg'
+  if (width >= PANEL_BREAKPOINTS.md) return 'md'
+  if (width >= PANEL_BREAKPOINTS.sm) return 'sm'
+  return 'xs'
+}
+
+/** titan's long-standing card column width, and the floor every wider tier clamps to. */
+export const CARD_WIDTH_BASE = 318
+
+/**
+ * CHOSEN. At wall width a 318px card is ~17% of the content row against ~34% at the `md`
+ * edge, so it reads as a sliver beside the hero. 0.22 pulls it back toward the `md`
+ * proportion without letting the hero lose its lead.
+ */
+export const CARD_WIDTH_XL_RATIO = 0.22
+
+/**
+ * CHOSEN. The cap. The card's internal charts (`RomProgressionChart`, `GhostSpark`) were
+ * drawn around ~318 and go sparse rather than richer past roughly 1.5x that, so the
+ * expansion stops at 460 (reached at 2091px) instead of tracking the container forever.
+ */
+export const CARD_WIDTH_MAX = 460
+
+/**
+ * CHOSEN. Stacked, the CARD takes the larger share of the one body height. Its sections
+ * have hard floors — the verdict hero, the three lights, the ROM chart and the ghost spark —
+ * while the velocity hero is a bar plot that scales continuously, so squeezing the hero
+ * degrades gracefully and squeezing the card overflows it.
+ */
+export const CARD_HEIGHT_SHARE_STACKED = 0.55
+
+/** What the hero reserves above its plot for the `VELOCITY · this set` eyebrow, px. */
+export const HERO_EYEBROW_ALLOWANCE = 26
+
+// --- the card's own height arithmetic ------------------------------------------------
+// It lives here rather than inside LiveFatigueCard so the panel can reason about the card's
+// floor without importing a component (this module stays react-native-free and testable).
+
+/** Floor for the ghost-spark plot inside the card, px. */
+export const CARD_MIN_CHART_HEIGHT = 168
+/** Ceiling for the ghost-spark plot inside the card, px. */
+export const CARD_MAX_CHART_HEIGHT = 240
+/** Share of a pinned card height the ghost-spark plot takes, before the clamp. */
+export const CARD_CHART_HEIGHT_RATIO = 0.4
+/** What an unpinned card gives the ghost-spark plot, px. */
+export const CARD_NATURAL_CHART_HEIGHT = 172
+
+/** The ghost-spark plot height for a card height, or the natural height when unpinned. */
+export function cardChartHeight(cardHeight?: number): number {
+  if (cardHeight == null) return CARD_NATURAL_CHART_HEIGHT
+  const scaled = cardHeight * CARD_CHART_HEIGHT_RATIO
+  return Math.round(Math.min(CARD_MAX_CHART_HEIGHT, Math.max(CARD_MIN_CHART_HEIGHT, scaled)))
+}
+
+/**
+ * MEASURED, not chosen: everything in the card that is not the ghost-spark plot — the 18px
+ * padding top and bottom, the verdict hero, the three lights, the two 16px minimum spacers
+ * and the ROM chart. Taken from the rendered card in Storybook (`scrollHeight` 384 at the
+ * {@link CARD_MIN_CHART_HEIGHT} floor), so a change to those sections needs re-measuring.
+ */
+export const CARD_CHROME_HEIGHT = 216
+
+/**
+ * The shortest a stacked card can be drawn without its content spilling past the rounded
+ * edge. Before this floor existed, an `xs` panel at `bodyHeight` 560 gave the card 301px
+ * against a 384px content height and the ghost spark rendered outside the card.
+ */
+export const CARD_MIN_HEIGHT_STACKED = CARD_CHROME_HEIGHT + CARD_MIN_CHART_HEIGHT
+
+/** Padding and column gap per tier. `md` and up hold today's values exactly. */
+const TIER_SPACING: Record<PanelTier, { padding: number; gap: number }> = {
+  xs: { padding: 16, gap: 12 },
+  sm: { padding: 20, gap: 14 },
+  md: { padding: 24, gap: 18 },
+  lg: { padding: 24, gap: 18 },
+  xl: { padding: 24, gap: 18 },
+}
+
+export interface PanelLayout {
+  tier: PanelTier
+  /** Card below the hero rather than beside it. */
+  stacked: boolean
+  /** Uniform padding around the body row, px. */
+  padding: number
+  /** Gap between the hero and the card, px — column gap when row, row gap when stacked. */
+  gap: number
+  /**
+   * Card width, px. Stacked, this is the full content width, so the card takes a real
+   * number rather than needing a second `onLayout` of its own to size its charts.
+   */
+  cardWidth: number
+}
+
+/** The card column width for a row tier, before any explicit `cardWidth` override. */
+function rowCardWidth(tier: PanelTier, width: number): number {
+  if (tier !== 'xl') return CARD_WIDTH_BASE
+  const fluid = Math.round(width * CARD_WIDTH_XL_RATIO)
+  return Math.min(CARD_WIDTH_MAX, Math.max(CARD_WIDTH_BASE, fluid))
+}
+
+/** The whole layout for a measured container width. */
+export function panelLayout(width: number): PanelLayout {
+  const tier = panelTier(width)
+  const { padding, gap } = TIER_SPACING[tier]
+  const stacked = width > 0 && width < ROW_TIER_MIN
+  const cardWidth = stacked
+    ? Math.max(0, Math.round(width - padding * 2))
+    : rowCardWidth(tier, width)
+  return { tier, stacked, padding, gap, cardWidth }
+}
+
+export interface PanelBodySplit {
+  /** Height handed to the velocity hero's plot, px. */
+  heroHeight: number
+  /** Height handed to the fatigue card, px. */
+  cardHeight: number
+}
+
+/**
+ * CHOSEN. The shortest the velocity plot is still worth drawing. Below this the bars stop
+ * being readable across a room, so the stacked panel grows past `bodyHeight` rather than
+ * flattening the hero any further.
+ */
+export const HERO_MIN_PLOT_HEIGHT = 140
+
+/**
+ * The ONE body height split across the hero and the card (TD-03.60). Side by side both
+ * take the full height; stacked they share it by {@link CARD_HEIGHT_SHARE_STACKED} with the
+ * gap taken out first, and neither drops below its floor. Either way both numbers come from
+ * this one call, so changing `bodyHeight` moves both or neither.
+ */
+export function panelBodySplit(bodyHeight: number, layout: PanelLayout): PanelBodySplit {
+  if (!layout.stacked) {
+    return {
+      heroHeight: Math.max(0, bodyHeight - HERO_EYEBROW_ALLOWANCE),
+      cardHeight: Math.max(0, bodyHeight),
+    }
+  }
+  const usable = Math.max(0, bodyHeight - layout.gap)
+  const cardHeight = Math.max(
+    CARD_MIN_HEIGHT_STACKED,
+    Math.round(usable * CARD_HEIGHT_SHARE_STACKED)
+  )
+  return {
+    heroHeight: Math.max(HERO_MIN_PLOT_HEIGHT, usable - cardHeight - HERO_EYEBROW_ALLOWANCE),
+    cardHeight,
+  }
+}

package/src/components/custom/Gauge/Gauge.stories.tsx

@@ -2,9 +2,9 @@ import type { Meta, StoryObj } from '@storybook/react-vite'
 import { Gauge } from './Gauge'
 
 const meta: Meta<typeof Gauge> = {
-  title: 'Components/DataViz/Gauge',
+  title: 'Custom/Charts/Gauge',
   component: Gauge,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
   argTypes: {
     value: { control: { type: 'range', min: 0, max: 100, step: 1 } },
     size: { control: { type: 'range', min: 100, max: 320, step: 10 } },

package/src/components/custom/Gauge/Gauge.test.tsx

@@ -50,7 +50,7 @@ describe('Gauge', () => {
           { value: 0, color: '#14B8A6' },
           { value: 50, color: '#D14343' },
         ]}
-      />,
+      />
     )
     expect(screen.getByTestId('gauge-value')).toHaveStyle({ color: '#14B8A6' })
   })

package/src/components/custom/Gauge/Gauge.tsx

@@ -152,7 +152,10 @@ export function Gauge({
       ))}
 
       {/* Center readout — Metric visual language. */}
-      <View style={{ position: 'absolute', top: 0, left: 0, width: size, height: size }} className="items-center justify-center">
+      <View
+        style={{ position: 'absolute', top: 0, left: 0, width: size, height: size }}
+        className="items-center justify-center"
+      >
         <View className="flex-row items-baseline gap-0.5">
           <Text testID="gauge-value" className="text-3xl font-bold" style={{ color: displayColor }}>
             {formatValue(value)}

package/src/components/custom/Metric/Metric.stories.tsx

@@ -5,7 +5,16 @@ import { Metric, MetricGroup } from './Metric'
 const meta: Meta<typeof Metric> = {
   title: 'Components/Molecules/Metric',
   component: Metric,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Composes RN primitives only. `MetricGroup` arranges several with a divider rule ' +
+          'between them.',
+      },
+    },
+  },
   argTypes: {
     value: {
       control: 'text',

package/src/components/custom/Metric/Metric.test.tsx

@@ -60,9 +60,7 @@ describe('Metric', () => {
 
   describe('accessibility', () => {
     it('has no accessibility violations', async () => {
-      const { container } = render(
-        <Metric value="42" label="Reps" unit="reps" trend="up" />
-      )
+      const { container } = render(<Metric value="42" label="Reps" unit="reps" trend="up" />)
       const results = await axe(container)
       expect(results).toHaveNoViolations()
     })

package/src/components/custom/Metric/Metric.tsx

@@ -46,18 +46,10 @@ export function Metric({
     <View className={cn('items-center', className)} {...props}>
       <View className="flex-row items-baseline gap-1">
         <Text className={cn(styles.value, 'text-text-primary')}>{value}</Text>
-        {unit && (
-          <Text className={cn(styles.unit, 'text-text-tertiary')}>{unit}</Text>
-        )}
-        {trend && (
-          <Text className={cn(styles.unit, trendColors[trend])}>
-            {trendArrows[trend]}
-          </Text>
-        )}
+        {unit && <Text className={cn(styles.unit, 'text-text-tertiary')}>{unit}</Text>}
+        {trend && <Text className={cn(styles.unit, trendColors[trend])}>{trendArrows[trend]}</Text>}
       </View>
-      <Text className={cn(styles.label, 'text-text-secondary mt-1')}>
-        {label}
-      </Text>
+      <Text className={cn(styles.label, 'text-text-secondary mt-1')}>{label}</Text>
     </View>
   )
 }
@@ -67,11 +59,7 @@ export interface MetricGroupProps extends ViewProps {
   children: React.ReactNode
 }
 
-export function MetricGroup({
-  className,
-  children,
-  ...props
-}: MetricGroupProps) {
+export function MetricGroup({ className, children, ...props }: MetricGroupProps) {
   const items = React.Children.toArray(children)
 
   return (
@@ -80,10 +68,7 @@ export function MetricGroup({
         <React.Fragment key={i}>
           <View className="flex-1 items-center">{child}</View>
           {i < items.length - 1 && (
-            <View
-              className="w-px h-8 bg-divider mx-2"
-              testID="metric-divider"
-            />
+            <View className="w-px h-8 bg-divider mx-2" testID="metric-divider" />
           )}
         </React.Fragment>
       ))}

package/src/components/custom/Prose/MarkdownProse.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View } from 'react-native'
+import { MarkdownProse, type ProseLinker } from './MarkdownProse'
+
+const SAMPLE = `# Shipped AW-17 and AW-18
+
+Resolved the cwd to an initiative via the registered worktree, then folded the
+result into [[bootstrap-prompt]]. See #42 for the file-history explorer.
+
+## What changed
+
+- \`active-work open\` now resolves **worktree-registered** cwds first
+- A missing worktree no longer aborts the launch; AW-116 tracks the prune
+- TD-07.14 unified the greys, so the shell planes moved with it
+
+### Follow-ups
+
+Nothing blocks AW-22; the reader is next.`
+
+const TASK_LINKER: ProseLinker = {
+  id: 'task',
+  pattern: /\b[A-Z]{2,}-\d+(?:\.\d+)?\b/,
+  tone: 'brand',
+}
+const WIKI_LINKER: ProseLinker = {
+  id: 'wiki',
+  pattern: /\[\[[^\]]+\]\]/,
+  tone: 'link',
+  label: (ref) => ref.slice(2, -2),
+}
+const PR_LINKER: ProseLinker = { id: 'pr', pattern: /#\d+\b/, tone: 'muted' }
+
+/**
+ * **MarkdownProse** — a small markdown subset (headings, bullets, paragraphs,
+ * bold, code) rendered as themed prose, with caller-described references
+ * auto-linked in one of three tones.
+ *
+ * Composes `Typography`. Used by `SessionDetail` and the initiative reader.
+ */
+const meta: Meta<typeof MarkdownProse> = {
+  title: 'Custom/Prose/MarkdownProse',
+  component: MarkdownProse,
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  args: {
+    body: SAMPLE,
+    linkers: [TASK_LINKER, WIKI_LINKER, PR_LINKER],
+  },
+  argTypes: {
+    linkers: { table: { disable: true } },
+  },
+  decorators: [
+    (Story) => (
+      <View className="w-full max-w-[640px] p-4">
+        <Story />
+      </View>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Composes **Typography**. Linkers are tried in order; a match renders in its tone and, when the linker carries `onPress`, as a pressable link.',
+      },
+    },
+  },
+}
+export default meta
+
+type Story = StoryObj<typeof MarkdownProse>
+
+/** Task ids in brand, `[[links]]` as links, PR numbers muted. */
+export const Default: Story = {}
+
+/** The same body with no linkers: plain prose. */
+export const NoLinkers: Story = {
+  args: { linkers: [] },
+}
+
+/** Pressable references: each linker carries an `onPress`. */
+export const Pressable: Story = {
+  args: {
+    linkers: [
+      { ...TASK_LINKER, onPress: (id) => console.log('task', id) },
+      { ...WIKI_LINKER, onPress: (name) => console.log('link', name) },
+      { ...PR_LINKER, onPress: (ref) => console.log('pr', ref) },
+    ],
+  },
+}

package/src/components/custom/Prose/MarkdownProse.test.tsx

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { MarkdownProse, parseProseBlocks, type ProseLinker } from './MarkdownProse'
+
+const taskLinker: ProseLinker = { id: 'task', pattern: /\b[A-Z]{2,}-\d+\b/, tone: 'brand' }
+const wikiLinker: ProseLinker = {
+  id: 'wiki',
+  pattern: /\[\[[^\]]+\]\]/,
+  tone: 'link',
+  label: (ref) => ref.slice(2, -2),
+}
+
+describe('parseProseBlocks', () => {
+  it('joins consecutive lines into one paragraph and splits on blank lines', () => {
+    const blocks = parseProseBlocks('one\ntwo\n\nthree')
+    expect(blocks).toEqual([
+      { type: 'p', text: 'one two' },
+      { type: 'p', text: 'three' },
+    ])
+  })
+
+  it('reads headings and bullets, flattening deep headings to h3', () => {
+    const blocks = parseProseBlocks('# Title\n## Section\n#### Deep\n- item\n* other')
+    expect(blocks.map((b) => b.type)).toEqual(['h1', 'h2', 'h3', 'li', 'li'])
+    expect(blocks[2]!.text).toBe('Deep')
+    expect(blocks[4]!.text).toBe('other')
+  })
+
+  it('folds an indented continuation line into the bullet above it', () => {
+    const blocks = parseProseBlocks('- first `code\n  span` continues\nnot indented')
+    expect(blocks).toEqual([
+      { type: 'li', text: 'first `code span` continues' },
+      { type: 'p', text: 'not indented' },
+    ])
+  })
+
+  it('renders nothing for an empty body', () => {
+    expect(parseProseBlocks('')).toEqual([])
+  })
+})
+
+describe('MarkdownProse', () => {
+  it('renders bold and code spans without their markers', () => {
+    render(<MarkdownProse body="a **bold** and `code` span" />)
+    expect(screen.getByText('bold')).toBeInTheDocument()
+    expect(screen.getByText('code')).toBeInTheDocument()
+    expect(screen.queryByText(/\*\*/)).not.toBeInTheDocument()
+  })
+
+  it('auto-links each linker in its tone and applies the label', () => {
+    render(
+      <MarkdownProse body="See AW-22 and [[memory-note]]." linkers={[taskLinker, wikiLinker]} />
+    )
+    expect(screen.getByTestId('prose-ref-task')).toHaveTextContent('AW-22')
+    expect(screen.getByTestId('prose-ref-wiki')).toHaveTextContent('memory-note')
+    expect(screen.queryByText('[[memory-note]]')).not.toBeInTheDocument()
+  })
+
+  it('makes a reference pressable only when its linker has a handler', () => {
+    const onPress = vi.fn()
+    render(
+      <MarkdownProse body="AW-1 then [[note]]" linkers={[{ ...taskLinker, onPress }, wikiLinker]} />
+    )
+    fireEvent.click(screen.getByTestId('prose-ref-task'))
+    expect(onPress).toHaveBeenCalledWith('AW-1')
+    expect(screen.getByTestId('prose-ref-task')).toHaveAttribute('role', 'link')
+    expect(screen.getByTestId('prose-ref-wiki')).not.toHaveAttribute('role')
+  })
+
+  it('lets the first matching linker win when two patterns overlap', () => {
+    const broad: ProseLinker = { id: 'broad', pattern: /\b[A-Z]+-\d+\b/ }
+    render(<MarkdownProse body="AW-9" linkers={[taskLinker, broad]} />)
+    expect(screen.getByTestId('prose-ref-task')).toBeInTheDocument()
+    expect(screen.queryByTestId('prose-ref-broad')).not.toBeInTheDocument()
+  })
+
+  it('has no a11y violations', async () => {
+    const { container } = render(
+      <MarkdownProse
+        body="# Head\n\nBody with AW-3.\n\n- a bullet"
+        linkers={[{ ...taskLinker, onPress: () => {} }]}
+      />
+    )
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})

package/src/components/custom/Prose/MarkdownProse.tsx

@@ -0,0 +1,201 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+import { useMemo, type ReactNode } from 'react'
+import { Text, View } from 'react-native'
+import { cn } from '../../../utils/cn'
+import { Typography } from '../Typography'
+
+/** How a linked reference reads: brand for the domain's own ids, link for cross-references, muted for asides. */
+export type ProseLinkTone = 'brand' | 'link' | 'muted'
+
+/**
+ * A pattern the prose auto-links. Patterns must not carry the `g` flag or
+ * capture groups: the renderer combines them into one tokenizer.
+ */
+export interface ProseLinker {
+  /** Stable id, used in keys and test ids. */
+  id: string
+  pattern: RegExp
+  tone?: ProseLinkTone
+  /** Text to show for a match. Defaults to the match itself. */
+  label?: (ref: string) => string
+  /** When set the reference is pressable and exposes a link role. */
+  onPress?: (ref: string) => void
+}
+
+export type ProseBlockType = 'h1' | 'h2' | 'h3' | 'li' | 'p'
+
+export interface ProseBlock {
+  type: ProseBlockType
+  text: string
+}
+
+export interface MarkdownProseProps {
+  /** Markdown source. Headings, bullet lists, paragraphs, bold and code are understood. */
+  body: string
+  /** Reference patterns to auto-link, tried in order. */
+  linkers?: ProseLinker[]
+  className?: string
+  testID?: string
+}
+
+const BOLD = /\*\*[^*]+\*\*/
+const CODE = /`[^`]+`/
+
+/**
+ * Splits markdown into the block kinds this renderer understands. Consecutive
+ * text lines join into one paragraph; a blank line ends it. An indented line
+ * straight after a bullet continues that bullet. Deeper headings flatten to
+ * h3, since session prose never needs more than three levels.
+ */
+export function parseProseBlocks(body: string): ProseBlock[] {
+  const blocks: ProseBlock[] = []
+  let paragraph: string[] = []
+  const flush = () => {
+    if (paragraph.length) blocks.push({ type: 'p', text: paragraph.join(' ') })
+    paragraph = []
+  }
+  for (const raw of body.split('\n')) {
+    const line = raw.trim()
+    if (!line) {
+      flush()
+      continue
+    }
+    const heading = line.match(/^(#{1,6})\s+(.*)/)
+    if (heading) {
+      flush()
+      const level = Math.min(3, heading[1]!.length)
+      blocks.push({ type: `h${level}` as ProseBlockType, text: heading[2]! })
+      continue
+    }
+    const item = line.match(/^[-*]\s+(.*)/)
+    if (item) {
+      flush()
+      blocks.push({ type: 'li', text: item[1]! })
+      continue
+    }
+    // Lazy continuation: an indented line straight after a bullet belongs to it.
+    const last = blocks[blocks.length - 1]
+    if (last?.type === 'li' && paragraph.length === 0 && /^\s/.test(raw)) {
+      last.text = `${last.text} ${line}`
+      continue
+    }
+    paragraph.push(line)
+  }
+  flush()
+  return blocks
+}
+
+// One step denser than body2, with a 20px line so long logs stay readable at that size.
+const BODY_TEXT = 'text-xs leading-5 text-text-secondary'
+
+const TONE_CLASS: Record<ProseLinkTone, string> = {
+  brand: 'font-semibold text-brand-primary',
+  link: 'font-medium text-text-link',
+  muted: 'text-text-tertiary',
+}
+
+function anchored(pattern: RegExp): RegExp {
+  return new RegExp(`^(?:${pattern.source})$`)
+}
+
+/** One tokenizer for bold, code and every linker, so a span is classified exactly once. */
+function buildTokenizer(linkers: ProseLinker[]): RegExp {
+  const parts = [BOLD.source, CODE.source, ...linkers.map((l) => l.pattern.source)]
+  return new RegExp(`(${parts.join('|')})`, 'g')
+}
+
+function LinkedRef({ linker, value }: { linker: ProseLinker; value: string }) {
+  const label = linker.label ? linker.label(value) : value
+  const pressable = !!linker.onPress
+  return (
+    <Text
+      className={TONE_CLASS[linker.tone ?? 'link']}
+      onPress={pressable ? () => linker.onPress?.(value) : undefined}
+      accessibilityRole={pressable ? 'link' : undefined}
+      testID={`prose-ref-${linker.id}`}
+    >
+      {label}
+    </Text>
+  )
+}
+
+function renderInline(text: string, linkers: ProseLinker[], tokenizer: RegExp): ReactNode[] {
+  const anchoredLinkers = linkers.map((l) => ({ linker: l, test: anchored(l.pattern) }))
+  return text
+    .split(tokenizer)
+    .filter((piece) => piece !== '' && piece !== undefined)
+    .map((piece, i) => {
+      if (anchored(BOLD).test(piece)) {
+        return (
+          <Text key={i} className="font-semibold text-text-primary">
+            {piece.slice(2, -2)}
+          </Text>
+        )
+      }
+      if (anchored(CODE).test(piece)) {
+        return (
+          <Text key={i} className="font-mono text-text-primary">
+            {piece.slice(1, -1)}
+          </Text>
+        )
+      }
+      const hit = anchoredLinkers.find((l) => l.test.test(piece))
+      if (hit) return <LinkedRef key={i} linker={hit.linker} value={piece} />
+      return <Text key={i}>{piece}</Text>
+    })
+}
+
+function Block({ block, inline }: { block: ProseBlock; inline: (text: string) => ReactNode[] }) {
+  if (block.type === 'h1' || block.type === 'h2') {
+    return (
+      <Typography variant={block.type === 'h1' ? 'h5' : 'h6'} className="mt-1.5 text-text-primary">
+        {block.text}
+      </Typography>
+    )
+  }
+  if (block.type === 'h3') {
+    return (
+      <Typography variant="subtitle2" className="mt-1 font-bold text-text-primary">
+        {inline(block.text)}
+      </Typography>
+    )
+  }
+  if (block.type === 'li') {
+    return (
+      <View className="flex-row gap-2 pl-1">
+        <Text className="text-xs leading-5 text-brand-primary">•</Text>
+        <Typography variant="body2" className={cn('flex-1', BODY_TEXT)}>
+          {inline(block.text)}
+        </Typography>
+      </View>
+    )
+  }
+  return (
+    <Typography variant="body2" className={BODY_TEXT}>
+      {inline(block.text)}
+    </Typography>
+  )
+}
+
+/**
+ * MarkdownProse — renders a small, predictable markdown subset as themed prose
+ * and auto-links references the caller describes.
+ *
+ * It is deliberately not a full markdown engine: headings, bullet lists,
+ * paragraphs, bold and code cover the notes, briefs and session logs this
+ * system reads, and anything richer would need a design pass of its own.
+ * Composes {@link Typography}. Used by `SessionDetail` (session logs) and the
+ * initiative reader (brief and handoff prose).
+ */
+export function MarkdownProse({ body, linkers = [], className, testID }: MarkdownProseProps) {
+  const blocks = useMemo(() => parseProseBlocks(body), [body])
+  const tokenizer = useMemo(() => buildTokenizer(linkers), [linkers])
+  const inline = (text: string) => renderInline(text, linkers, tokenizer)
+  return (
+    <View className={cn('gap-2', className)} testID={testID}>
+      {blocks.map((block, i) => (
+        <Block key={i} block={block} inline={inline} />
+      ))}
+    </View>
+  )
+}