@appinternalleads/ui 0.2.0

package/src/widgets/output/renderers/ranked/RankedCard.tsx

@@ -0,0 +1,117 @@
+import { Box, MotionView, Text } from '../../../../core';
+import { groundFor } from '../../../../core/roles';
+import { useDs } from '../../../../tokens';
+import { OutputWidgetShell } from '../../OutputWidgetShell';
+import { outputRow, outputRanked } from '../../tokens';
+import { staggerDelay, useEntrance, useEntranceTracker } from '../../motion';
+import type { OutputActionId } from '../../document';
+
+/**
+ * **`ranked` — X4.** `docs/output-type-sheets/ranked.md`, variation A, "medallion rows (as
+ * shipped)". No evaluative colour-coding by score or rank — the medallion and bar are always the
+ * same accent regardless of magnitude ("correct when the scores are made up anyway").
+ */
+
+export type RankedItem = { id: string; rank?: number; title: string; note?: string; score?: number };
+export type RankedPhase = 'loading' | 'partial' | 'settled';
+
+function Medallion({ n }: { n: number }) {
+  const { colors } = useDs();
+  return (
+    <Box style={{ width: 28, height: 28, borderRadius: 14, backgroundColor: groundFor(colors, 'accentFill'), alignItems: 'center', justifyContent: 'center' }}>
+      <Text style={{ fontSize: 13, fontWeight: '700', color: colors.textOnAccent }}>{n}</Text>
+    </Box>
+  );
+}
+
+function RankedSkeletonRow() {
+  const { colors } = useDs();
+  return (
+    <Box row align="center" style={{ gap: 12, paddingVertical: outputRow.pad.web.y, paddingHorizontal: outputRow.pad.web.x, borderBottomWidth: 1, borderBottomColor: colors.hairline }}>
+      <Box style={{ width: 28, height: 28, borderRadius: 14, backgroundColor: colors.hairlineStrong }} />
+      <Box style={{ flex: 1, gap: 6 }}>
+        <Box style={{ width: 100, height: 12, borderRadius: 6, backgroundColor: colors.hairlineStrong }} />
+        <Box style={{ width: 160, height: 9, borderRadius: 4, backgroundColor: colors.hairlineStrong }} />
+      </Box>
+    </Box>
+  );
+}
+
+function RankedRowView({ item, index, seen }: { item: RankedItem; index: number; seen: Set<string> }) {
+  const { colors } = useDs();
+  const rank = item.rank ?? index + 1;
+  const { opacity, translateY } = useEntrance(item.id, seen, { variant: 'rise', delayMs: staggerDelay(index, 70) });
+  const b = outputRanked.bar;
+  return (
+    <MotionView style={{ opacity, transform: [{ translateY }] }}>
+      <Box row align="center" style={{ gap: 12, paddingVertical: outputRow.pad.web.y, paddingHorizontal: outputRow.pad.web.x, borderBottomWidth: 1, borderBottomColor: colors.hairline }}>
+        <Medallion n={rank} />
+        <Box style={{ flex: 1 }}>
+          <Text style={{ fontSize: 14.5, fontWeight: '600', color: colors.textPrimary }}>{item.title}</Text>
+          {item.note ? <Text color="textSecondary" style={{ fontSize: 12.5, lineHeight: 17 }}>{item.note}</Text> : null}
+        </Box>
+        {item.score !== undefined ? (
+          <Box align="flex-end" style={{ gap: 4 }}>
+            <Text style={{ fontSize: 15, fontWeight: '600', color: colors.textPrimary }}>{item.score}</Text>
+            <Box style={{ width: b.width, height: b.height, borderRadius: b.height / 2, backgroundColor: colors.hairline, overflow: 'hidden' }}>
+              <Box style={{ width: `${Math.max(0, Math.min(100, item.score))}%`, height: '100%', backgroundColor: groundFor(colors, 'accentFill') }} />
+            </Box>
+          </Box>
+        ) : null}
+      </Box>
+    </MotionView>
+  );
+}
+
+export type RankedCardProps = {
+  title: string;
+  chip?: string;
+  meta?: string;
+  items: RankedItem[];
+  /** Accepted for contract-completeness. Drag-to-reorder (`mount: 'write'`) is not built this
+      pass — it needs a real, keyboard-accessible reorder interaction
+      (`docs/output-type-sheets/ranked.md`'s own accessibility note), not a pointer-drag-only
+      stand-in, so it is disclosed as not-yet-implemented rather than shipped half-accessible.
+      `read` mode (the common case) is fully implemented. */
+  mount?: 'read' | 'write';
+  phase?: RankedPhase;
+  loadingCount?: number;
+  onReorder?: (items: RankedItem[]) => void;
+  onMenu?: () => void;
+  onAction?: (id: OutputActionId) => void;
+  testID?: string;
+};
+
+export function RankedCard({
+  title, chip = 'ranked', meta, items, phase = 'settled', loadingCount = 4, onMenu, onAction, testID,
+}: RankedCardProps) {
+  const seen = useEntranceTracker();
+
+  if (phase === 'loading') {
+    return (
+      <OutputWidgetShell kind={chip} title={title} onMenu={onMenu} onAction={onAction} meta={meta} provisional testID={testID}>
+        <Box>{Array.from({ length: loadingCount }, (_, i) => <RankedSkeletonRow key={i} />)}</Box>
+      </OutputWidgetShell>
+    );
+  }
+
+  if (items.length === 0) {
+    return (
+      <OutputWidgetShell kind={chip} title={title} onMenu={onMenu} onAction={onAction} meta={meta} testID={testID}>
+        <Box style={{ padding: 16 }}><Text color="textSecondary" style={{ fontSize: 12.5 }}>No ranking available</Text></Box>
+      </OutputWidgetShell>
+    );
+  }
+
+  return (
+    <OutputWidgetShell kind={chip} title={title} onMenu={onMenu} onAction={onAction} meta={meta} provisional={phase === 'partial'} testID={testID}>
+      <Box>
+        {items.map((it, i) => <RankedRowView key={it.id} item={it} index={i} seen={seen} />)}
+      </Box>
+    </OutputWidgetShell>
+  );
+}
+
+export function rankedToText(items: RankedItem[]): string {
+  return items.map((it, i) => `${it.rank ?? i + 1}. ${it.title}${it.score !== undefined ? ` (${it.score})` : ''}`).join('\n');
+}

package/src/widgets/output/renderers/ranked/index.ts

@@ -0,0 +1,4 @@
+export {
+  RankedCard, rankedToText,
+  type RankedCardProps, type RankedItem, type RankedPhase,
+} from './RankedCard';

package/src/widgets/output/renderers/sequence/SequenceCard.tsx

@@ -0,0 +1,172 @@
+import { useEffect, useRef, useState } from 'react';
+import { Animated, Easing } from 'react-native';
+import { Box, MotionView, Pressable, Text } from '../../../../core';
+import { groundFor } from '../../../../core/roles';
+import { useDs } from '../../../../tokens';
+import { OutputWidgetShell } from '../../OutputWidgetShell';
+import { outputSequence } from '../../tokens';
+import type { OutputActionId } from '../../document';
+
+/**
+ * **`sequence` — X3.** `docs/output-type-sheets/sequence.md`, variation A, "one at a time (as
+ * shipped)". Read-only; position is widget-local and never persisted — it is not a result.
+ */
+
+export type SequenceStep = {
+  id: string;
+  title: string;
+  body: string | null;
+  error?: boolean;
+};
+
+export type SequencePhase = 'loading' | 'partial' | 'settled';
+
+const POSITIONAL_TRANSITION = 170;
+const EASE = Easing.bezier(0.2, 0.8, 0.2, 1);
+
+function useStepTransition(active: number) {
+  const opacity = useRef(new Animated.Value(1)).current;
+  const first = useRef(true);
+  useEffect(() => {
+    if (first.current) { first.current = false; return; }
+    opacity.setValue(0);
+    Animated.timing(opacity, { toValue: 1, duration: POSITIONAL_TRANSITION, easing: EASE, useNativeDriver: false }).start();
+  }, [active]);
+  return opacity;
+}
+
+function SequenceSkeleton() {
+  const { colors } = useDs();
+  const c = outputSequence.card;
+  return (
+    <Box style={{ padding: c.pad, gap: c.gap }}>
+      <Box style={{ width: 140, height: 16, borderRadius: 6, backgroundColor: colors.hairlineStrong }} />
+      <Box style={{ width: '90%', height: 10, borderRadius: 5, backgroundColor: colors.hairlineStrong }} />
+      <Box style={{ width: '60%', height: 10, borderRadius: 5, backgroundColor: colors.hairlineStrong }} />
+    </Box>
+  );
+}
+
+export type SequenceCardProps = {
+  title: string;
+  chip?: string;
+  meta?: string;
+  steps: SequenceStep[];
+  activeIndex?: number;
+  phase?: SequencePhase;
+  onMenu?: () => void;
+  onAction?: (id: OutputActionId) => void;
+  testID?: string;
+};
+
+export function SequenceCard({
+  title, chip = 'sequence', meta, steps, activeIndex = 0, phase = 'settled', onMenu, onAction, testID,
+}: SequenceCardProps) {
+  const { colors } = useDs();
+  const [active, setActive] = useState(Math.min(activeIndex, Math.max(steps.length - 1, 0)));
+  const opacity = useStepTransition(active);
+  const c = outputSequence.card;
+  const n = outputSequence.nav;
+  const d = outputSequence.dots;
+
+  if (phase === 'loading') {
+    return (
+      <OutputWidgetShell kind={chip} title={title} onMenu={onMenu} onAction={onAction} meta={meta} provisional testID={testID}>
+        <SequenceSkeleton />
+      </OutputWidgetShell>
+    );
+  }
+
+  if (steps.length === 0) {
+    return (
+      <OutputWidgetShell kind={chip} title={title} onMenu={onMenu} onAction={onAction} meta={meta} testID={testID}>
+        <Box style={{ padding: c.pad }}>
+          <Text color="textSecondary" style={{ fontSize: 12.5, lineHeight: 16 }}>No steps</Text>
+        </Box>
+      </OutputWidgetShell>
+    );
+  }
+
+  const step = steps[Math.min(active, steps.length - 1)]!;
+  const showNav = steps.length > 1;
+  const showDots = steps.length > 1 && steps.length <= 8;
+
+  return (
+    <OutputWidgetShell
+      kind={chip} title={title} onMenu={onMenu} onAction={onAction} meta={meta}
+      provisional={phase === 'partial'} testID={testID}>
+      <Box style={{ padding: 14, gap: 11 }}>
+        <Box row align="center" style={{ gap: 12 }}>
+          {showNav ? (
+            <Pressable
+              onPress={() => setActive(i => Math.max(0, i - 1))}
+              disabled={active === 0}
+              hit={n.size}
+              radius="pill"
+              bg="surface1"
+              align="center" justify="center"
+              aria-label="Previous step"
+              style={{ width: n.size, height: n.size }}>
+              <Text color={active === 0 ? 'textSecondary' : 'textSecondary'} style={{ fontSize: 15, fontWeight: '600' }}>‹</Text>
+            </Pressable>
+          ) : null}
+
+          <MotionView style={{ flex: 1, opacity, backgroundColor: colors.surfaceSunken, borderRadius: 18, padding: c.pad, gap: c.gap }}>
+            {step.error ? (
+              <>
+                <Text mono uppercase style={{ fontSize: 10, fontWeight: '700', letterSpacing: 0.8, color: colors.status.needsUser }}>Failed</Text>
+                <Text style={{ fontSize: 16, fontWeight: '600', color: colors.textPrimary }}>{step.title}</Text>
+              </>
+            ) : (
+              <>
+                <Text style={{ fontSize: 16, fontWeight: '600', color: colors.textPrimary }}>{step.title}</Text>
+                {step.body != null ? (
+                  <Text color="textSecondary" style={{ fontSize: 12.5, lineHeight: 17 }}>{step.body}</Text>
+                ) : (
+                  <Box style={{ width: '80%', height: 10, borderRadius: 5, backgroundColor: colors.hairlineStrong }} />
+                )}
+              </>
+            )}
+          </MotionView>
+
+          {showNav ? (
+            <Pressable
+              onPress={() => setActive(i => Math.min(steps.length - 1, i + 1))}
+              disabled={active === steps.length - 1}
+              hit={n.size}
+              radius="pill"
+              bg="surface1"
+              align="center" justify="center"
+              aria-label="Next step"
+              style={{ width: n.size, height: n.size }}>
+              <Text color="textPrimary" style={{ fontSize: 15, fontWeight: '600' }}>›</Text>
+            </Pressable>
+          ) : null}
+        </Box>
+
+        <Box align="center" style={{ gap: 8 }}>
+          <Text color="textSecondary" style={{ fontSize: 13 }}>{active + 1} / {steps.length}</Text>
+          {showDots ? (
+            <Box row style={{ gap: d.gap }} aria-hidden>
+              {steps.map((s, i) => (
+                <Box
+                  key={s.id}
+                  style={{
+                    width: d.size, height: d.size, borderRadius: d.size / 2,
+                    backgroundColor: i === active ? groundFor(colors, 'accentFill') : colors.hairline,
+                  }}
+                />
+              ))}
+            </Box>
+          ) : null}
+        </Box>
+      </Box>
+    </OutputWidgetShell>
+  );
+}
+
+export function sequenceToText(steps: SequenceStep[], activeIndex = 0): string {
+  const step = steps[activeIndex];
+  if (!step) return 'No steps';
+  return `Step ${activeIndex + 1} of ${steps.length}: ${step.title}${step.body ? ` — ${step.body}` : ''}`;
+}

package/src/widgets/output/renderers/sequence/index.ts

@@ -0,0 +1,4 @@
+export {
+  SequenceCard, sequenceToText,
+  type SequenceCardProps, type SequenceStep, type SequencePhase,
+} from './SequenceCard';

package/src/widgets/output/renderers/stats/StatsCard.tsx

@@ -0,0 +1,351 @@
+import { useState } from 'react';
+import { Box, MotionView, Pressable, Text } from '../../../../core';
+import { groundFor, radiusFor } from '../../../../core/roles';
+import { useDs } from '../../../../tokens';
+import { useSurface } from '../../../useSurface';
+import { OutputWidgetShell } from '../../OutputWidgetShell';
+import { outputStats } from '../../tokens';
+import { staggerDelay, useEntrance, useEntranceTracker, type StreamingContract } from '../../motion';
+import type { OutputActionId } from '../../document';
+
+/**
+ * **`stats` — X2.** `tasks/OUTPUT-WIDGETS.md` X2, from
+ * `design_handoff_output_blocks_stats/README.md` Part 3. A small fixed set of scalar metrics,
+ * read at a glance, read-only.
+ *
+ * **Value semantics, extended beyond the spec's own `string | null` sketch:** a metric's `value`
+ * is `undefined` while still in flight (renders `resolving…`), explicit `null` once resolved to
+ * genuinely nothing (renders `No data` — never `0`), or the string itself. The spec's prose
+ * requires all three states (`loading`/`partial` tiles read `resolving…`; `no data` is its own,
+ * distinct state) but its TS sketch only names two — this fills the gap rather than collapsing
+ * "not here yet" and "resolved to nothing" into the same `null`.
+ */
+
+export type TrendTone = 'up' | 'down' | 'flat';
+
+export type StatsTrend = {
+  tone: TrendTone;
+  /** The magnitude, no arrow, no sign — `"18%"`, `"2"`. Omit for a flat trend with nothing to show. */
+  magnitude?: string;
+  /** D3 — the wire's explicit `null` baseline. Distinct from `flat`: there is no prior period at all. */
+  noBaseline?: boolean;
+};
+
+export type StatsMetric = {
+  /** Stable — keys the entrance animation. Never the array index. */
+  id: string;
+  label: string;
+  /** `undefined` = still resolving · `null` = resolved, no data · a string = the value. */
+  value?: string | null;
+  trend?: StatsTrend;
+  error?: string;
+  /** Drillable only. */
+  href?: string;
+};
+
+export type StatsBehaviour = 'inert' | 'drillable' | 'trend';
+export type StatsPhase = 'loading' | 'partial' | 'settled';
+
+export const STATS_STREAMING: StreamingContract = {
+  minimumViablePartial: 'one label/value pair',
+  reservedHeight: outputStats.tile.minHeight,
+};
+
+/** The trend pill's plain-language accessible name — direction must survive without the arrow or the hue. */
+function trendAccessibleName(t: StatsTrend): string {
+  if (t.noBaseline) return 'no prior period';
+  if (t.tone === 'flat') return 'no change';
+  return `${t.tone} ${t.magnitude ?? ''} versus last period`.trim();
+}
+
+/** The trend pill's visual text — `"↑ 18%"`, `"↓ 2"`, `"No change"`, `"—"`. */
+function trendVisualText(t: StatsTrend): string {
+  if (t.noBaseline) return '—';
+  if (t.tone === 'flat') return t.magnitude ? t.magnitude : 'No change';
+  const arrow = t.tone === 'up' ? '↑' : '↓';
+  return `${arrow} ${t.magnitude ?? ''}`.trim();
+}
+
+/** The flat-text fallback's parenthetical — `"(+18%)"`, `"(no change)"`, `"(no prior period)"`. */
+function trendFlatText(t: StatsTrend): string {
+  if (t.noBaseline) return 'no prior period';
+  if (t.tone === 'flat') return 'no change';
+  const sign = t.tone === 'up' ? '+' : '-';
+  return `${sign}${t.magnitude ?? ''}`;
+}
+
+function TrendPill({ trend }: { trend: StatsTrend }) {
+  const { colors } = useDs();
+  /* `design_handoff_output_blockers` §1.4/§3.2 (2026-09-17), superseding the earlier X6 call:
+     negative direction is NEUTRAL, not apricot and not clay — "a fall in exceptions is good
+     news; the renderer cannot know polarity, so it must not assert one." `down` now renders
+     identically to `flat`/`noBaseline`; only `up` keeps mint, and only because the payload's own
+     `tone: 'up'` is the producer declaring that direction favourable. */
+  const tone =
+    trend.noBaseline || trend.tone === 'flat' || trend.tone === 'down'
+      ? { bg: colors.surfaceSunken, fg: colors.textSecondary }
+      : { bg: colors.statusBg.executed, fg: colors.status.executed };
+  const p = outputStats.trendPill;
+  return (
+    <Box
+      style={{
+        backgroundColor: tone.bg,
+        paddingVertical: p.padY,
+        paddingHorizontal: p.padX,
+        borderRadius: p.radius,
+        alignSelf: 'flex-start',
+      }}
+      aria-label={trendAccessibleName(trend)}>
+      <Text mono style={{ fontSize: p.size, lineHeight: p.size, color: tone.fg }}>
+        {trendVisualText(trend)}
+      </Text>
+    </Box>
+  );
+}
+
+function SkeletonTile() {
+  const { colors } = useDs();
+  const t = outputStats.tile;
+  const surface = useSurface();
+  const pad = t.pad[surface];
+  return (
+    <Box
+      flex={1}
+      style={{
+        minHeight: t.minHeight,
+        borderRadius: radiusFor('control'),
+        backgroundColor: colors.surfaceSunken,
+        paddingVertical: pad.y,
+        paddingHorizontal: pad.x,
+        justifyContent: 'space-between',
+      }}>
+      <Box style={{ width: 62, height: 10, borderRadius: 5, backgroundColor: colors.hairlineStrong }} />
+      <Box style={{ width: 96, height: 20, borderRadius: 6, backgroundColor: colors.hairlineStrong }} />
+    </Box>
+  );
+}
+
+function StatsTile({
+  metric, behaviour, hero, selected, onSelect, seen, index,
+}: {
+  metric: StatsMetric;
+  behaviour: StatsBehaviour;
+  hero: boolean;
+  selected: boolean;
+  onSelect?: (id: string) => void;
+  seen: Set<string>;
+  index: number;
+}) {
+  const { colors } = useDs();
+  const surface = useSurface();
+  const t = outputStats.tile;
+  const v = outputStats.value;
+  const pad = t.pad[surface];
+  const { opacity, translateY } = useEntrance(metric.id, seen, {
+    variant: 'rise',
+    delayMs: staggerDelay(index, outputStats.stagger),
+  });
+  /* Hover is a transition, not one of the twelve motions (the spec says so explicitly) — a
+     press-triggered state, not entrance choreography, so it lives outside `motion.ts`. Web-only
+     by nature; `onHoverIn`/`onHoverOut` are no-ops without a pointer. */
+  const [hovered, setHovered] = useState(false);
+
+  const resolving = metric.value === undefined && !metric.error;
+  const noData = metric.value === null && !metric.error;
+  const drillable = behaviour === 'drillable' && !resolving && !noData && !metric.error;
+  const isTrend = behaviour === 'trend' && metric.trend && !resolving;
+  const lifted = drillable && hovered;
+
+  const valueSize = hero ? v.size.web : v.size[surface];
+  const content = (
+    <Box
+      flex={1}
+      lift={lifted ? 2 : undefined}
+      style={{
+        minHeight: t.minHeight,
+        borderRadius: t.radius,
+        paddingVertical: pad.y,
+        paddingHorizontal: pad.x,
+        justifyContent: 'space-between',
+        /* `design_handoff_output_blockers` §3.3/C7 (2026-09-17): "Failed" has no real token yet
+           — every warm fill in this palette is within 1.06 contrast of every other, and coral is
+           already the primary accent, so a proper `--alert-*` pair needs a brand decision this
+           repo doesn't own. Interim rule, explicit stopgap: apricot fill, apricot-deep ink AND a
+           border (attention states normally have none — this is the one exception), PLUS the
+           literal word "Failed", because colour alone is never the signal for a terminal state.
+           This reverses the X6-era clay/`status.error` call once the errata bundle confirmed
+           `needsUser` is what the spec means here, not what it looked like a mismatch for. */
+        backgroundColor: metric.error
+          ? colors.statusBg.needsUser
+          : selected
+          ? groundFor(colors, 'accentTint')
+          : colors.surfaceSunken,
+        /* No `lift` outside the hover case (this tile isn't a resting elevated card), so a real
+           border is legitimate here — same reasoning as the `no data` dashed border below, not
+           the shell's doubled-edge case. `selected`: "background #FBF0E8, border: 1px solid
+           #C1552C." */
+        borderWidth: noData || selected || metric.error ? 1 : undefined,
+        borderStyle: noData ? 'dashed' : 'solid',
+        borderColor: noData
+          ? colors.hairlineStrong
+          : selected
+          ? groundFor(colors, 'accentFill')
+          : metric.error
+          ? colors.status.needsUser
+          : undefined,
+        transform: lifted ? [{ translateY: -2 }] : undefined,
+      }}>
+      <Box row align="center" justify="space-between">
+        <Text
+          mono uppercase color="textSecondary"
+          numberOfLines={1}
+          style={{ fontSize: outputStats.label.size, lineHeight: outputStats.label.size, letterSpacing: outputStats.label.size * outputStats.label.tracking }}>
+          {metric.label}
+        </Text>
+      </Box>
+
+      {resolving ? (
+        <Text mono color="accentInk" style={{ fontSize: 11, lineHeight: 11 }}>resolving…</Text>
+      ) : metric.error ? (
+        <Box gap="s1">
+          {/* The word is the signal, not the colour alone — §3.3's interim rule, literally. */}
+          <Text
+            mono uppercase
+            style={{ fontSize: 10, lineHeight: 10, letterSpacing: 10 * 0.08, fontWeight: '600', color: colors.status.needsUser }}>
+            Failed
+          </Text>
+          <Text style={{ fontSize: 12.5, lineHeight: 16, color: colors.status.needsUser }}>{metric.error}</Text>
+        </Box>
+      ) : noData ? (
+        <Text color="textSecondary" style={{ fontSize: 12.5, lineHeight: 16 }}>No data</Text>
+      ) : (
+        <Box gap="s1">
+          <Text
+            numeric
+            style={{
+              fontSize: valueSize,
+              lineHeight: valueSize * v.lineHeight,
+              fontWeight: '600',
+              letterSpacing: valueSize * v.tracking,
+            }}>
+            {metric.value}
+          </Text>
+          {isTrend && metric.trend ? <TrendPill trend={metric.trend} /> : null}
+        </Box>
+      )}
+    </Box>
+  );
+
+  return (
+    <MotionView style={{ flex: 1, opacity, transform: [{ translateY }] }}>
+      {drillable ? (
+        <Pressable
+          onPress={() => onSelect?.(metric.id)}
+          onHoverIn={() => setHovered(true)}
+          onHoverOut={() => setHovered(false)}
+          aria-pressed={selected}
+          aria-label={metric.label}
+          minHeight={t.minHeight}
+          style={{ width: '100%' }}>
+          {content}
+        </Pressable>
+      ) : (
+        content
+      )}
+    </MotionView>
+  );
+}
+
+/** The flat-text fallback — feeds the clipboard, the share sheet, email/SMS, and a screen-reader summary. */
+export function statsToText(metrics: StatsMetric[]): string {
+  return metrics
+    .map(m => {
+      if (m.value === undefined) return `${m.label}: resolving…`;
+      if (m.value === null) return `${m.label}: No data`;
+      const trend = m.trend ? ` (${trendFlatText(m.trend)})` : '';
+      return `${m.label}: ${m.value}${trend}`;
+    })
+    .join('\n');
+}
+
+export type StatsCardProps = {
+  title: string;
+  /** The kind chip's text. "chip is a label, not a type" (O1) — defaults to `"stats"`. */
+  chip?: string;
+  metrics: StatsMetric[];
+  behaviour?: StatsBehaviour;
+  phase?: StatsPhase;
+  /** How many skeleton tiles to draw while `phase === 'loading'` and no metrics are known yet. */
+  loadingCount?: number;
+  /** The metric id that leads as a hero tile spanning both columns. O9's recommended default. */
+  heroId?: string;
+  selected?: string | null;
+  onSelect?: (id: string) => void;
+  onMenu?: () => void;
+  /** When given, the shell's ⋮ opens the standard popover instead of calling `onMenu`. */
+  onAction?: (id: OutputActionId) => void;
+  meta?: string;
+  testID?: string;
+};
+
+/** Chunks a list into rows of `n`, the "two columns, always" grid without needing CSS grid on native. */
+function chunk<T>(items: T[], n: number): T[][] {
+  const rows: T[][] = [];
+  for (let i = 0; i < items.length; i += n) rows.push(items.slice(i, i + n));
+  return rows;
+}
+
+export function StatsCard({
+  title, chip = 'stats', metrics, behaviour = 'inert', phase = 'settled', loadingCount = 4, heroId,
+  selected = null, onSelect, onMenu, onAction, meta, testID,
+}: StatsCardProps) {
+  const seen = useEntranceTracker();
+  const g = outputStats;
+
+  if (phase === 'loading') {
+    return (
+      <OutputWidgetShell
+        kind={chip} title={title} onMenu={onMenu} onAction={onAction}
+        meta={meta} provisional testID={testID}>
+        <Box style={{ paddingTop: g.body.padTop, paddingHorizontal: g.body.padX, paddingBottom: g.body.padBottom }}>
+          {chunk(Array.from({ length: loadingCount }, (_, i) => i), 2).map((row, ri) => (
+            <Box key={ri} row style={{ gap: g.grid.gap, marginBottom: ri === 0 ? undefined : g.grid.gap }}>
+              {row.map(i => <SkeletonTile key={i} />)}
+            </Box>
+          ))}
+        </Box>
+      </OutputWidgetShell>
+    );
+  }
+
+  const hero = heroId ? metrics.find(m => m.id === heroId) : undefined;
+  const rest = hero ? metrics.filter(m => m.id !== heroId) : metrics;
+  const rows = chunk(rest, 2);
+
+  return (
+    <OutputWidgetShell
+      kind={chip} title={title} onMenu={onMenu} onAction={onAction}
+      meta={meta} provisional={phase === 'partial'} testID={testID}>
+      <Box style={{ paddingTop: g.body.padTop, paddingHorizontal: g.body.padX, paddingBottom: g.body.padBottom, gap: g.grid.gap }}>
+        {hero ? (
+          <Box row style={{ gap: g.grid.gap }}>
+            <StatsTile
+              metric={hero} behaviour={behaviour} hero selected={selected === hero.id}
+              onSelect={onSelect} seen={seen} index={0}
+            />
+          </Box>
+        ) : null}
+        {rows.map((row, ri) => (
+          <Box key={ri} row style={{ gap: g.grid.gap }}>
+            {row.map((m, ci) => (
+              <StatsTile
+                key={m.id} metric={m} behaviour={behaviour} hero={false} selected={selected === m.id}
+                onSelect={onSelect} seen={seen} index={(hero ? 1 : 0) + ri * 2 + ci}
+              />
+            ))}
+          </Box>
+        ))}
+      </Box>
+    </OutputWidgetShell>
+  );
+}

package/src/widgets/output/renderers/stats/index.ts

@@ -0,0 +1,4 @@
+export {
+  StatsCard, statsToText, STATS_STREAMING,
+  type StatsCardProps, type StatsMetric, type StatsTrend, type StatsBehaviour, type StatsPhase, type TrendTone,
+} from './StatsCard';