@titan-design/react-ui 0.12.0 → 0.13.0

package/src/components/custom/ActiveWork/PortfolioOverview.tsx

@@ -0,0 +1,83 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+import { View, type ViewProps } from 'react-native'
+import { Card } from '../../ui/card'
+import { Metric } from '../Metric'
+import { Typography } from '../Typography'
+import { Eyebrow } from './Eyebrow'
+import { InitiativeCard, type InitiativeCardProps } from './InitiativeCard'
+
+export interface PortfolioOverviewStat {
+  value: string
+  label: string
+}
+
+export interface PortfolioOverviewSection {
+  /** Section eyebrow, e.g. "Focused · by rank" or "Backburner". */
+  heading: string
+  items: InitiativeCardProps[]
+}
+
+export interface PortfolioOverviewProps extends ViewProps {
+  title: string
+  subtitle?: string
+  /** KPI tiles rendered above the sections, e.g. Focused / Open tasks / Initiatives. */
+  stats: PortfolioOverviewStat[]
+  /** Initiative groups, rendered top-to-bottom in the order given. */
+  sections: PortfolioOverviewSection[]
+  className?: string
+}
+
+/**
+ * PortfolioOverview — at-a-glance status across every tracked initiative: a
+ * KPI row followed by initiative groups (typically Focused, then Backburner).
+ * Composes Card / Metric / Eyebrow / {@link InitiativeCard} — presentational
+ * only, all data supplied by props.
+ *
+ * Data plan: the caller is responsible for computing `stats` and `sections`
+ * from its own source of truth (e.g. the active-work session-mining export).
+ * This component has no fetch/store dependency, so wiring it to a live data
+ * source is a caller-side concern — flagged here as the integration's only
+ * open gap.
+ */
+export function PortfolioOverview({
+  title,
+  subtitle,
+  stats,
+  sections,
+  className,
+  ...props
+}: PortfolioOverviewProps) {
+  return (
+    <View className={`gap-5 ${className ?? ''}`} {...props}>
+      <View>
+        <Typography variant="h4" className="text-text-primary">
+          {title}
+        </Typography>
+        {subtitle ? (
+          <Typography variant="body2" className="text-text-tertiary">
+            {subtitle}
+          </Typography>
+        ) : null}
+      </View>
+
+      <View className="flex-row flex-wrap gap-3">
+        {stats.map((stat) => (
+          <Card key={stat.label} className="min-w-[150px] flex-1 p-4" testID="portfolio-stat">
+            <Metric value={stat.value} label={stat.label} />
+          </Card>
+        ))}
+      </View>
+
+      {sections.map((section) => (
+        <View key={section.heading} className="gap-2.5">
+          <Eyebrow>{section.heading}</Eyebrow>
+          <View className="flex-row flex-wrap gap-3">
+            {section.items.map((item) => (
+              <InitiativeCard key={item.slug} {...item} />
+            ))}
+          </View>
+        </View>
+      ))}
+    </View>
+  )
+}

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

@@ -0,0 +1,305 @@
+# ActiveWork — component family
+
+Presentational components for surfacing `active-work` data: initiative/task rollups (portfolio status),
+the cross-initiative task table, session logs (the session reader) and per-file mined history (the
+file-history explorer). Read-only: every component takes plain data as props and
+has no fetch/store dependency of its own — wiring to a live source (the active-work session-mining export, or
+a future API) is entirely the caller's concern. Components live flat on disk; the tiering below is a
+documentation contract, not a directory layout.
+
+## Composition trees
+
+```
+PortfolioOverview ................ organism
+├─ Eyebrow ....................... molecule → Typography (overline)
+├─ Card + Metric .................. (existing primitives, used inline for the KPI row)
+└─ InitiativeCard ................ card
+   ├─ Card ........................ (existing primitive)
+   ├─ Pill ........................ (existing primitive)
+   ├─ StatusDot .................... (Workout family primitive)
+   └─ SegmentedBar ................. (Workout family primitive)
+
+FileHistoryExplorer .............. organism
+├─ Tile .......................... (existing primitive, KPI strip)
+├─ Card + Divider ................ (existing primitives)
+├─ Eyebrow ....................... molecule
+├─ FileActivityRow ............... row          (listbox `option`)
+│  ├─ FilePathLabel .............. molecule → Typography (mono)
+│  └─ SparkBars .................. atom         (Custom/Charts — new shared primitive)
+├─ FileActivityDetail ............ card
+│  ├─ Tile / Pill / DataRow / DateTime .... (existing primitives)
+│  ├─ SparkBars .................. atom
+│  ├─ FilePathLabel .............. molecule
+│  └─ Eyebrow .................... molecule
+└─ CoChangeChip .................. molecule
+   ├─ Card + Pill ................ (existing primitives)
+   └─ FilePathLabel .............. molecule
+
+TaskTable ........................ organism
+├─ Eyebrow ....................... molecule
+├─ Table (density="dense") ....... (existing primitive, Table family)
+│  └─ useTable ({ comparators }) . (existing hook, Table family)
+├─ SeverityLabel ................. molecule      (legend tallies)
+└─ TaskRow ....................... row
+   ├─ TableRow + TableCell ....... (existing primitives, Table family)
+   ├─ SeverityLabel .............. molecule → Indicator
+   └─ Pill ....................... (existing primitive)
+
+Session reader ................... (no organism: the host composes the two halves)
+├─ SessionList ................... list
+│  ├─ Eyebrow .................... molecule
+│  └─ SessionListItem ............ row          (listbox `option`)
+│     ├─ DateTime / Pill ......... (existing primitives)
+│     └─ Typography .............. (existing primitive)
+└─ SessionDetail ................. card
+   ├─ Card / Divider / Pill / DateTime .... (existing primitives)
+   └─ MarkdownProse .............. molecule     (Custom/Prose — new shared primitive)
+      └─ Typography .............. (existing primitive)
+
+Initiative reader (no organism: the host composes the pieces)
+├─ InitiativeHeader .............. molecule
+│  ├─ StatusDot / Pill / DateTime ...... (existing primitives; INITIATIVE_STATE_META shared with InitiativeCard)
+│  └─ Typography ................. (existing primitive)
+├─ OpenLoops ..................... list
+│  ├─ Eyebrow / Pill / Divider ... (existing primitives)
+│  └─ MarkdownProse .............. molecule
+├─ InitiativeBrief ............... card         (single-open `##` accordion + prev/next stepper)
+│  ├─ Eyebrow / Typography ....... (existing primitives)
+│  └─ MarkdownProse .............. molecule
+├─ TaskTable ..................... organism     (embedded, hideColumns)
+└─ SessionList ................... list
+```
+
+## Dependency map
+
+| Component             | Tier     | Composes ↓                                                                   | Used-by ↑                                                                          |
+| --------------------- | -------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `PortfolioOverview`   | organism | Card, Metric, Eyebrow, InitiativeCard                                        | app root (`Custom/ActiveWork/PortfolioOverview`)                            |
+| `InitiativeCard`      | card     | Card, Pill, StatusDot, SegmentedBar, Typography                              | PortfolioOverview                                                                  |
+| `FileHistoryExplorer` | organism | Card, Tile, Divider, Eyebrow, FileActivityRow/Detail, CoChangeChip           | app root (`Custom/ActiveWork/FileHistoryExplorer`)                         |
+| `FileActivityDetail`  | card     | Card, Tile, Pill, DataRow, DateTime, SparkBars, FilePathLabel, Eyebrow       | FileHistoryExplorer                                                                |
+| `FileActivityRow`     | row      | FilePathLabel, SparkBars, Typography                                         | FileHistoryExplorer                                                                |
+| `CoChangeChip`        | molecule | Card, Pill, FilePathLabel, Typography                                        | FileHistoryExplorer                                                                |
+| `FilePathLabel`       | molecule | Typography (`mono`)                                                          | FileActivityRow, FileActivityDetail, CoChangeChip                                  |
+| `TaskTable`           | organism | Table, useTable, TableHeader/Row/HeaderCell, TaskRow, SeverityLabel, Eyebrow | app root (`Custom/ActiveWork/TaskTable`)                                           |
+| `TaskRow`             | row      | TableRow, TableCell, SeverityLabel, Pill, Typography                         | TaskTable                                                                          |
+| `SeverityLabel`       | molecule | Indicator, Typography (`caption`)                                            | TaskRow, TaskTable (legend), InitiativeCard (vocabulary)                           |
+| `Eyebrow`             | molecule | Typography (`overline`)                                                      | PortfolioOverview, FileHistoryExplorer, FileActivityDetail, TaskTable, SessionList |
+| `SessionList`         | list     | Eyebrow, SessionListItem                                                     | host composition (`Custom/ActiveWork/SessionReader` story)                        |
+| `SessionListItem`     | row      | DateTime, Pill, Typography                                                   | SessionList                                                                        |
+| `SessionDetail`       | card     | Card, Divider, Pill, DateTime, MarkdownProse (+ `sessionLinkers`)            | host composition (`Custom/ActiveWork/SessionReader` story)                        |
+| `InitiativeHeader`    | molecule | StatusDot, Pill, DateTime, Typography (+ `INITIATIVE_STATE_META`)            | host composition (`Custom/ActiveWork/InitiativeReader` story)                     |
+| `OpenLoops`           | list     | Eyebrow, Pill, Divider, MarkdownProse                                        | host composition (`Custom/ActiveWork/InitiativeReader` story)                     |
+| `InitiativeBrief`     | card     | Eyebrow, Typography, MarkdownProse                                           | host composition (`Custom/ActiveWork/InitiativeReader` story)                     |
+
+## Surfaces and depth
+
+The page is a `<Surface level="base">` (greyRamp[925], `#252321`). Every content container on it is a
+**default `<Card>`** — no variant, no `bg-*` className — which lifts two planes to greyRamp[875]
+(`#31302F`) and wears the lift: a 1px top rim-light at 0.12 plus an ambient shadow. Depth here is tone AND
+lift together, not tone alone.
+
+Inside a lifted card, nothing lifts again. Organise with `CardInset` (a pressed well one plane down,
+greyRamp[900] `#2C2A28`, with the `insetWell` recess), a tone-only `filled` tile, or a `Divider`.
+`variant="outline"` is reserved for a status edge; it is not how you make a box.
+
+`Card` writes its plane into `style`, so a `bg-surface-*` className on a `Card` is **discarded**. `bgColor`
+is the only override. The M2 reader shipped with `className="… bg-surface-raised" variant="subtle"` on its
+three cards and rendered flat on greyRamp[900] with a hairline ring — that combination is the bug, not the
+model.
+
+## Shared substrates introduced here (reusable beyond this family)
+
+- **`Eyebrow`** — a generic uppercase micro-label. Not active-work-specific; exported at
+  `Components/Molecules/Eyebrow` (not nested under `ActiveWork/`) so any family can reach for it instead of
+  hand-rolling `Typography` + tracking/uppercase classes again.
+- **`SparkBars`** (`components/custom/charts`, `Custom/Charts/SparkBars`) — a bar-mark sparkline for a
+  signed series, the counterpart to `Sparkline`'s line mark. Domain-neutral and exported top-level, not
+  nested under `ActiveWork/`. `custom/charts` gained an `index.ts` that deliberately exports **only**
+  `SparkBars`: `SetBarChart` and `live-rep-growth` stay workout-internal and imported by path.
+- **`formatCompact` / `formatSignedCompact`** (`utils/number-format`) — `1234 → "1.2k"`, `+514689 → "+514.7k"`.
+  Generic dense-readout formatting; no equivalent existed (`workout-format` is domain-specific).
+- **`MarkdownProse`** (`components/custom/Prose`, `Custom/Prose/MarkdownProse`) — a small markdown subset
+  (headings, bullets, paragraphs, bold, code) rendered as themed prose, with caller-supplied `linkers` that
+  auto-link references in a `brand` / `link` / `muted` tone and, when a linker carries `onPress`, make them
+  pressable `link`-role spans. Deliberately not a markdown engine. Domain-neutral; the active-work patterns
+  (`taskRefLinker`, `wikiLinkLinker`, `prRefLinker`, bundled as `sessionLinkers`) live in this family's
+  `session-linkers.ts`. Second consumer is the initiative reader (M2: brief and handoff prose). Inline refs
+  are `Text` with `onPress`, not `Link`: `Link` wraps a `Pressable` view, which cannot sit inline in prose.
+- **`formatTaskAge` / `formatSessionDuration`** (`format-time.ts`) — the compact age label moved out of
+  `TaskTable` so the session reader shares it (`TaskTable` still re-exports it), plus `1h 4m` / `42m` for a
+  session's wall-clock length. `hooks/useTimer`'s `formatDuration` is `mm:ss` for timers, a different job.
+
+## Changes to existing primitives
+
+- **`DataRow.label` widened from `string` to `ReactNode`** (plus a new `labelClassName`), mirroring how
+  `value` already worked. The co-change rows need a rich `FilePathLabel` on the left; the alternative was
+  passing `label=""` and hand-rolling the row, which defeats the primitive. Backwards compatible — `string`
+  is a `ReactNode` and the string branch is unchanged.
+- **`Table` gained a `density` axis** (`comfortable` | `dense`, default `comfortable`). Cell padding is
+  chosen once in `CELL_PADDING` and read from context by both `TableHeaderCell` and `TableCell`, so a row's
+  header and body halves cannot drift. `TaskTable` is a scannable backlog grid, not a reading table; without
+  this it would have had to hand-roll the whole grid to get 34px rows.
+- **`useTable` gained per-column `comparators`.** It previously sorted on the raw field value only, which
+  cannot express "rank severity critical→low" (alphabetically `low` lands between `high` and `medium`),
+  "tie-break on priority", or "read this date newest-first". Columns absent from the map keep the default
+  compare, so this is additive. Two ordering rules were also made explicit while in there: `desc` **inverts**
+  the comparator rather than reversing the array (reversing also flips tied rows), and blank values rank last
+  in **both** directions rather than reading as the smallest value when the column flips.
+- **`status-error-vivid` fixed from `#D14343` to `#FF4757`** (both themes). It pointed at `ramp.red[600]`,
+  the exact value of `status-error`, so the two rendered as one colour — Critical and High were
+  indistinguishable, and so were `DeviceRow`/`DeviceIndicator`'s `lost` state and a plain error. Three other
+  places already encoded the correct vivid red (`--color-status-error-vivid-rgb`, the `-subtle` rgba, and
+  `Indicator`'s `glow` shadow); only the value anyone rendered was wrong. Found 2026-08-31 by measuring the
+  Storybook render, not by reading tokens. Guarded by `theme/status-distinctness.test.ts`, which asks whether
+  tokens LOOK different — a question the existing presence/parity tests structurally cannot ask, since a
+  collapsed token is present and parity-matched.
+
+- **`Tooltip` gained a controlled `isOpen` and a `useHoverState` hook.** RNW's `Pressable` hovers with
+  `contain: true`, which locks the pointer to the innermost Pressable and ends any ancestor's hover, so a
+  `Tooltip` wrapped around a pressable row never shows in a real browser (jsdom's synthetic `mouseEnter`
+  hides this). In controlled mode the Tooltip renders no Pressable of its own, so it can sit _inside_ a
+  pressable row without taking its press; the field owns hover through `useHoverState`'s pointer
+  enter/leave props. The session row's age and task count use this. Same trap as the T2 header tooltip, seen
+  from the other side.
+- **`CollapseButton` gained `accessibilityLabel`**, so a bare chevron toggle (the tasks-touched table) has an
+  accessible name.
+- **`TaskTable` gained `hideColumns`** (mirrored by `TaskRow`), so an embedded table can drop columns its
+  context already implies: the session detail hides `slug` and `tags` to give the title room.
+- **`Table` gained a column drop order** (`useMeasuredWidth` + `useColumnFit` + `Table.contentMinWidth`), and
+  `TaskTable` declares one: severity, priority, estimate, tags, age, initiative. `title` and `id` declare no
+  `dropPriority`, so they never drop and the table scrolls horizontally instead. Found in the initiative
+  reader at an 865px viewport: the card measured 369px against 418px of fixed columns, the flexible title
+  collapsed to 0 and painted its header over the severity column, and the age column was clipped off the
+  right edge. `priority`, `estimate` and `severityCompact` also widened (42/42/44 → 56/56/56) because each
+  was narrower than its own uppercase header plus the sort glyph — the arithmetic behind `SEV`/`PRI`
+  overlapping at every width, not just narrow ones.
+- **Subtle coloured `Pill`s are borderless with a stronger tint** (`bg-*/15`, `border-transparent`; the
+  neutral `default` keeps its hairline). The 25%-alpha coloured border read as a dark outline on dark
+  surfaces. System-wide; visual baselines for coloured subtle pills move.
+
+## Severity vocabulary has one owner
+
+`SeverityLabel.tsx` owns `TaskSeverity`, `SEVERITY_ORDER`, `SEVERITY_RANK`/`severityRank`, `SEVERITY_META`
+(dot colours) and `SEVERITY_BAR_COLOR` (area-mark fills). `InitiativeCard` previously declared its own copy
+of the type plus private `SEVERITY_ORDER`/`SEVERITY_COLOR` constants; it now imports them. The two colour
+maps stay separate on purpose — `low` is `status-info` as a dot (it must stay legible among four) and
+`text-tertiary` as a bar segment (it should recede) — but the _set_ of severities is defined once.
+
+## Reuse audit
+
+| Concern            | Uses                                                  | Not                                                                                                                   |
+| ------------------ | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| status dot + label | `StatusDot` (Workout family)                          | the original Lab specimen's hand-rolled `DotLabel` (deleted)                                                          |
+| severity mix bar   | `SegmentedBar` (Workout family)                       | the original Lab specimen's hand-rolled `SeverityBar` (deleted)                                                       |
+| bar sparkline      | `SparkBars` (new, `Custom/Charts`)                    | the specimen's hand-rolled `MiniBars` (deleted); `Sparkline` is a _line_ mark, `SetBar`/`SetStrip` are workout-domain |
+| KPI stat boxes     | `Tile` (bare on the page; one plane up inside a card) | the specimen's redundant `Card variant="filled"` wrapper around `Tile`                                                |
+| label ↔ value rows | `DataRow` (label widened to `ReactNode`)              | a hand-rolled `flex-row justify-between`                                                                              |
+| short dates        | `DateTime` `format="short"` + `fallback`              | the specimen's hand-rolled `shortDate` (deleted)                                                                      |
+| compact numbers    | `formatCompact` / `formatSignedCompact` (new util)    | the specimen's inline `compact` / `signedCompact` (deleted)                                                           |
+| count badges       | `Pill` `variant="subtle"`                             | ad-hoc bordered `View`                                                                                                |
+| card chrome        | `Card` (default; `accent` for focused state)          | ad-hoc bordered `View`; `subtle`/`outline` used to make a box                                                         |
+| colors             | `getSemanticColors` / `greyRamp` tokens               | magic hex                                                                                                             |
+| session prose      | `MarkdownProse` (new, `Custom/Prose`)                 | the specimen's inline `parseBlocks` / `renderInline` / `BlockView` (deleted); no markdown renderer existed            |
+| session durations  | `formatSessionDuration` (new, `format-time.ts`)       | the specimen's inline `duration`; `useTimer.formatDuration` is `mm:ss`                                                |
+| selectable rows    | `Pressable` + `role="option"` (the F1 pattern)        | the specimen's bordered `Card`-per-row; `ListItem` has no selected state                                              |
+
+### Colour vocabularies
+
+Two live here and must not be conflated:
+
+- **`FILE_EVENT_COLOR`** — read / write / edit, i.e. _what kind of event_. Two variants ship:
+  `FILE_EVENT_COLOR_CATEGORICAL` (**the default** — the canonical CVD-safe palette taken in order, on the
+  grounds that the three kinds are peer categories) and `FILE_EVENT_COLOR_SEMANTIC` (the alternative —
+  colours by importance, greying reads out). Overridable per component via `eventColors`. Note the default
+  spends three of `CATEGORICAL_CVD_SAFE_MAX`: a view that also plots series must start from index 3.
+- **`GROWTH_COLOR`** — added / removed / neutral, i.e. _char deltas_. Uses `result-*`, because a file that
+  net-shrank was refactored, not broken. `status-error` would say something is wrong. See TOKENS.md §1.
+
+All colours resolve through `resolveColor(token)`, never `getSemanticColors('dark')` — the latter freezes
+to the dark hex and silently breaks light theme.
+
+### Surfaces and depth
+
+Follows _Foundations → Depth_ as corrected on 2026-09-08. Every container plane is a step on the grey ramp,
+and a plane that sits above its host wears the **lift** — a 1px top rim-light at 0.12 plus an ambient
+shadow. The earlier claim on this page that levels 1–3 separate by tone alone, and that "nothing here
+floats, so nothing casts a shadow", was reversed: the upper ramp steps are only ΔL\* 2.5–3 apart, too tight
+for tone to carry the separation on its own.
+
+Measured planes (dark mode; light mode is a separate pass):
+
+| Role                                      | Component                               | Plane                 | Colour    | Treatment                     |
+| ----------------------------------------- | --------------------------------------- | --------------------- | --------- | ----------------------------- |
+| Page                                      | `<Surface level="base">`                | `base` / grey-925     | `#252321` | flat, no lift                 |
+| List pane, detail pane, reader cards, KPI | `<Card>` (default, `elevation={2}`)     | `raised` / grey-875   | `#31302F` | rim `inset 0 1px 0` + ambient |
+| Focused initiative                        | `<Card variant="accent">`               | `raised` / grey-875   | `#31302F` | lift + brand left stripe      |
+| Growth block (grouped stats)              | `<CardInset>`                           | `elevated` / grey-900 | `#2C2A28` | `insetWell` recess            |
+| Co-change chips                           | `<Card variant="filled">`               | `raised` / grey-875   | `#31302F` | tone only, no lift            |
+| Activity tiles inside the detail pane     | `<Tile className="bg-surface-overlay">` | `overlay` / grey-850  | `#373635` | tone only, no lift            |
+| Table frame, month rules, section rules   | `border-hairline` / `Divider`           | host plane            | —         | hairline edge only            |
+
+Three rules the family now holds:
+
+1. **Lift sparingly.** One lift per page-level container. A card inside a card does not lift again; it
+   becomes a `CardInset`, a `filled` tile, or a `Divider`.
+2. **Never pass a `bg-*` className to a `Card`.** The plane is written into `style`, so the class is
+   silently dropped. `bgColor` is the one override.
+3. **A hairline is an edge, not a plane.** Dividers, table rules and the `outline` variant's status edge
+   are the only places it belongs. `variant="subtle"`/`"outline"` used to make a box is the anti-pattern
+   this migration removed.
+
+`Tile` still hand-rolls `bg-surface-raised`, which _is_ the card plane. At page level that is right; inside
+a lifted card the call site steps it up one (`className="bg-surface-overlay"`). Teaching `Tile` to resolve
+its plane from the surface context is a separate epic.
+
+### Token discipline
+
+This family is on the **token-pure** eslint list (`eslint.config.js`, error-level): no raw hex, no
+arbitrary spacing/radius/type values, no hardcoded inline `fontSize`, no `getSemanticColors` in a
+component. It was brought to zero violations when F1 was hardened — including retrofitting T1, which had
+carried 19 arbitrary values in from its specimen. Adding a family to that list is the last step of
+hardening it; see TOKENS.md §6.
+
+**Watch-list (known gaps):**
+
+- `InitiativeCard`'s state→`StatusDot` variant mapping (`focused → on-track`, `backburner → future`,
+  `paused → deviation`, `done → success`) is a first-pass color choice, not yet operator-confirmed against a
+  render — flagged for Gate 2 review rather than blocking hardening on a separate round-trip.
+- The live data wiring (active-work → `PortfolioOverview` / `FileHistoryExplorer` props) still lives only in
+  the `titan-aw-dashboard` Lab specimen story files, not in a shared adapter. Promoting that mapping out of
+  the specimens is a follow-up, not part of this unit.
+- `FilePathLabel` is domain-neutral (a file path is not an active-work concept) but every consumer today is
+  in this family, so it stays here. Promote it top-level the moment a second family needs it.
+- The KPI strip now uses bare `Tile` while `PortfolioOverview` still uses `Card` + `Metric`. The family is
+  internally inconsistent until T1 is revisited — deliberate, since changing T1 is out of this unit's scope.
+
+## Accessibility notes
+
+- The ranked list is a real **`listbox`** and each `FileActivityRow` a real **`option`** carrying
+  `aria-selected`. This uses raw `role` / `aria-selected` props rather than `accessibilityState={{ selected }}`,
+  because **RNW silently drops the latter** — the gap `components/shell/README.md` flags as unresolved for
+  `NavItem`, where active state is asserted via an accent-bar testID instead. The same fix applies there.
+- React Native's `Role` union has `'option'` but omits `'listbox'`, so `FileHistoryExplorer` casts once
+  through a named `LISTBOX_ROLE` constant rather than dropping the ARIA parent. `SessionList` does the same;
+  each `SessionListItem` is an `option` with `aria-selected` and an accessible name of title plus footer.
+- `MarkdownProse` references with a handler carry `accessibilityRole="link"`; inert ones carry no role, so
+  a screen reader does not announce a link that goes nowhere.
+
+## Testing
+
+- Unit: `*.test.tsx` per component (render/behavior/a11y via `jest-axe`). Branch coverage on state/rank/topTask
+  presence and the all-zero-severity case (T1); on controlled-vs-uncontrolled selection, unmatched
+  `selectedPath`, empty `files`, empty `coEdges`, missing touch dates, no-co-change, net-negative growth, and
+  `maxRows` / `maxCoEdges` capping (F1).
+- Fixtures: `file-history-fixture.ts` — a small hand-trimmed slice of a real mine with fixed values (no
+  `Date.now()`, no randomness) so visual baselines stay deterministic. `session-fixture.ts` likewise: five
+  real session logs (their real markdown, so the linkers meet real references) plus one synthesized ad-hoc
+  session, paired with `SESSION_NOW`.
+- Visual: not yet added to `tests/visual/stories.spec.ts` — see follow-up in the PR description.
+- Lint guardrails: the token-pure rule set above; no
+  re-implemented status dot, segmented bar, or sparkline.
+
+```
+
+```

package/src/components/custom/ActiveWork/SessionDetail.stories.tsx

@@ -0,0 +1,71 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Surface } from '../../ui/surface'
+import { SessionDetail } from './SessionDetail'
+import { SESSION_FIXTURE, SESSION_NOW, SESSION_TASK_FIXTURE } from './session-fixture'
+
+/**
+ * **SessionDetail** — one session log: when it ran and for how long, the
+ * tasks it touched, then the body as auto-linked prose.
+ *
+ * Composes `Card` · `Divider` · `Pill` · `DateTime` · `MarkdownProse`.
+ */
+const meta: Meta<typeof SessionDetail> = {
+  title: 'Custom/ActiveWork/SessionDetail',
+  component: SessionDetail,
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  args: {
+    session: SESSION_FIXTURE[0],
+    tasks: SESSION_TASK_FIXTURE,
+    now: SESSION_NOW,
+  },
+  argTypes: {
+    session: { table: { disable: true } },
+    tasks: { table: { disable: true } },
+    now: { table: { disable: true } },
+    onPressTask: { action: 'onPressTask' },
+    onPressLink: { action: 'onPressLink' },
+    onPressPr: { action: 'onPressPr' },
+  },
+  decorators: [
+    (Story) => (
+      <Surface level="base" className="min-h-screen w-full max-w-[760px] p-6" testID="page-surface">
+        <Story />
+      </Surface>
+    ),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Composes **Card** · **Divider** · **Pill** · **DateTime** · **MarkdownProse** (with the session linkers). Used-by ↑ the Session Reader composition.',
+      },
+    },
+  },
+}
+export default meta
+
+type Story = StoryObj<typeof SessionDetail>
+
+/** A long canonical session touching six tasks. */
+export const Default: Story = {}
+
+/** A six-minute session with a short log. */
+export const Short: Story = {
+  args: { session: SESSION_FIXTURE[5] },
+}
+
+/** An ad-hoc session: `[[name]]` link and a PR number, one task mentioned. */
+export const AdHoc: Story = {
+  args: { session: SESSION_FIXTURE[1] },
+}
+
+/** No task rows supplied: the strip is pills only, with no table toggle. */
+export const WithoutTasks: Story = {
+  args: { tasks: [] },
+}
+
+/** No handlers: references stay highlighted but are not pressable. */
+export const Inert: Story = {
+  args: { onPressTask: undefined, onPressLink: undefined, onPressPr: undefined },
+}

package/src/components/custom/ActiveWork/SessionDetail.test.tsx

@@ -0,0 +1,84 @@
+import { describe, it, expect, vi } from 'vitest'
+import { fireEvent, render, screen, within } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { SessionDetail, stripLeadingHeading } from './SessionDetail'
+import { SESSION_FIXTURE, SESSION_NOW, SESSION_TASK_FIXTURE } from './session-fixture'
+import { extractTaskRefs } from './session-linkers'
+
+const session = SESSION_FIXTURE[0]!
+const adhoc = SESSION_FIXTURE[1]!
+
+describe('SessionDetail', () => {
+  it('renders the header: title, date, age, duration and session id', () => {
+    render(<SessionDetail session={session} now={SESSION_NOW} />)
+    expect(screen.getByText(session.title)).toBeInTheDocument()
+    expect(screen.getByText('Jul 12, 2026')).toBeInTheDocument()
+    expect(screen.getByText('1d ago')).toBeInTheDocument()
+    expect(screen.getByText('· 1h 4m')).toBeInTheDocument()
+    expect(screen.getByText(session.id)).toBeInTheDocument()
+  })
+
+  it('lists every distinct task the log touches, once each, in first-seen order', () => {
+    render(<SessionDetail session={session} now={SESSION_NOW} />)
+    const strip = within(screen.getByTestId('session-tasks-touched'))
+    const refs = extractTaskRefs(session.body)
+    expect(refs.length).toBeGreaterThan(1)
+    for (const id of refs) expect(strip.getByText(id)).toBeInTheDocument()
+  })
+
+  it('routes presses on task pills and on in-body references to the host', () => {
+    const onPressTask = vi.fn()
+    const onPressLink = vi.fn()
+    const onPressPr = vi.fn()
+    render(
+      <SessionDetail
+        session={adhoc}
+        now={SESSION_NOW}
+        onPressTask={onPressTask}
+        onPressLink={onPressLink}
+        onPressPr={onPressPr}
+      />
+    )
+    fireEvent.click(within(screen.getByTestId('session-tasks-touched')).getByText('AW-17'))
+    expect(onPressTask).toHaveBeenCalledWith('AW-17')
+    fireEvent.click(screen.getByTestId('prose-ref-wiki'))
+    expect(onPressLink).toHaveBeenCalledWith('setup-walkthrough')
+    fireEvent.click(screen.getByTestId('prose-ref-pr'))
+    expect(onPressPr).toHaveBeenCalledWith(42)
+  })
+
+  it('leaves the leading h1 to the header and renders the rest as prose', () => {
+    render(<SessionDetail session={adhoc} now={SESSION_NOW} />)
+    const body = within(screen.getByTestId('session-body'))
+    expect(body.queryByText(adhoc.title)).not.toBeInTheDocument()
+    expect(body.getByText(/Tightened the install section/)).toBeInTheDocument()
+  })
+
+  it('expands the tasks-touched strip into a table only when task rows are supplied', () => {
+    const { rerender } = render(<SessionDetail session={adhoc} now={SESSION_NOW} />)
+    expect(screen.queryByRole('button', { name: /table/ })).not.toBeInTheDocument()
+    rerender(<SessionDetail session={adhoc} now={SESSION_NOW} tasks={SESSION_TASK_FIXTURE} />)
+    expect(screen.queryByTestId('task-row')).not.toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: /table/ }))
+    expect(screen.getByText('1 task touched')).toBeInTheDocument()
+    const rows = screen.getAllByTestId('task-row')
+    expect(rows).toHaveLength(1)
+    expect(within(rows[0]!).getByText('AW-17')).toBeInTheDocument()
+  })
+
+  it('has no a11y violations', async () => {
+    const { container } = render(
+      <SessionDetail session={adhoc} now={SESSION_NOW} onPressTask={() => {}} />
+    )
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})
+
+describe('stripLeadingHeading', () => {
+  it('drops a first-line h1 and nothing else', () => {
+    expect(stripLeadingHeading('# Title\n\nBody')).toBe('\nBody')
+    expect(stripLeadingHeading('\n# Title\nBody')).toBe('Body')
+    expect(stripLeadingHeading('## Section\nBody')).toBe('## Section\nBody')
+    expect(stripLeadingHeading('Body only')).toBe('Body only')
+  })
+})