@appinternalleads/ui 0.2.0

package/src/components/onboarding/shared/contract.ts

@@ -0,0 +1,191 @@
+import type { DataType } from '../../../tokens';
+import type { IconName } from '../../../core';
+
+/**
+ * **What the seven onboarding components share — `onboarding/1`.**
+ *
+ * Source: `design_handoff_onboarding_components` (README "Recommended implementation shape";
+ * `solarium-design-prd-7-components.md` overrides it where they conflict). Each component is
+ * written ONCE and configured by a plain `config` object; its five case studies are presets of that
+ * object and nothing else — the ThresholdFlow pattern.
+ *
+ * Merge order, verbatim from the handoff: `BASE_COPY ← BASE ← CASES[preset] ← config`, shallow —
+ * a case that changes `sources` replaces the whole list, never merges into it.
+ *
+ * **What is NOT config, on purpose.** Pattern status (loading / empty / error), the async result,
+ * density and the demo boards' `scene` are the host's runtime or presentation choices; a restored
+ * session is an `initial` seed. A config that carried them would render the same component
+ * differently depending on where it was saved from.
+ */
+
+export const ONBOARDING_SCHEMA = 'onboarding/1' as const;
+
+export const ONBOARDING_COMPONENTS = [
+  'brand-kit', 'budget-allocation', 'calendar-sync', 'carousel', 'contact-import', 'dashboard-config', 'export-format',
+  /* Batch 2 (design_handoff_onboarding_components_batch2, 2026-09-25). */
+  'setup-tasks', 'cicd-setup', 'completion', 'department-setup', 'help-center', 'permissions-setup', 'plan-selection',
+  'quick-actions', 'rate-limit', 'seat-allocation', 'status-page', 'tag-creation', 'terms-consent', 'trial-countdown', 'two-factor',
+  /* Batch 3 — notification + verification (design_handoff_notification_components_batch3, 2026-09-25). */
+  'achievement', 'event-reminder', 'file-shared', 'filter-panel', 'floating', 'mark-read', 'password-expiry',
+  'payment-alert', 'onboarding-step', 'queue-status', 'shipping-update', 'id-verification',
+  /* Batch 4 — data views, output containers and C14 (design_handoff_data_components_batch4, 2026-09-25). */
+  'table', 'grid', 'combobox', 'tabbed', 'fallback',
+  /* Batch 5 — data-viz dashboards (design_handoff_dataviz_batch5, 2026-09-26). M15 data reveal. */
+  'budget-tracker', 'ab-tests', 'conversion-funnel',
+  /* Batch 6 — reviews & insight (design_handoff_insights_batch6, 2026-09-26). M15 data reveal; M16 shape morph. */
+  'expandable-feed', 'score-summary', 'criteria-spider', 'activity-heatmap', 'tag-cloud',
+  /* Receipt Printer (2026-09-27) — the first New component animated with Rive (rive/receipt-printer). */
+  'receipt-printer',
+] as const;
+export type OnboardingComponent = (typeof ONBOARDING_COMPONENTS)[number];
+
+/* Table has a sixth — batch 5's Content Performance. `presetsOf` lists only what a component has. */
+export const PRESETS = ['case1', 'case2', 'case3', 'case4', 'case5', 'case6'] as const;
+export type OnboardingPreset = (typeof PRESETS)[number];
+
+/**
+ * **The case studies one component actually has, in order.** Batches 1–3 have five each; batch 4's
+ * Tabbed, Fallback and C14 have three (the handoff's own count). Every list of a component's case
+ * studies reads this, never `PRESETS`, so a three-case component never shows an empty fourth board.
+ */
+export function presetsOf(p: { cases: Partial<Record<OnboardingPreset, unknown>> }): OnboardingPreset[] {
+  return PRESETS.filter(k => k in p.cases);
+}
+
+/** The shell's pattern status (S1) — the host's loading of the step, not the component's own action. */
+export type PatternStatus = 'ready' | 'loading' | 'empty' | 'error';
+
+/** A save-style action's lifecycle — Brand Kit, Budget, Dashboard, Export. */
+export type SavePhase = 'idle' | 'saving' | 'saved' | 'failed';
+
+/** How the component's one async action turns out, when a host wants to force it (demo, test). */
+export type OnboardingResult = 'success' | 'error';
+
+/** Case-study copy for the demo boards and the site — eyebrow, title, one-line scenario. */
+export type CaseMeta = { eyebrow: string; title: string; scenario: string };
+
+/** The copy every component's load states share. */
+export type LoadCopy = {
+  loadErrorTitle: string;
+  loadErrorBody: string;
+  retryLabel: string;
+  emptyTitle: string;
+  emptyBody: string;
+  emptyCta: string;
+};
+
+/** The header every component draws: a 32px tile, a title, a subtitle. */
+export type HeaderConfig = {
+  /** Resolves the tile's hue through `TYPE_HUE`. */
+  type: DataType;
+  /** A handoff icon name — `iconFor` resolves it. */
+  icon: string;
+  title: string;
+  subtitle: string;
+};
+
+/**
+ * One component's presets file — `presets.json` next to its code, the single source of its data.
+ * `cases` and `meta` list case1… in order; iterate them with `presetsOf`, since not every component
+ * has five.
+ */
+export type PresetsFile<C> = {
+  component: OnboardingComponent;
+  baseCopy?: Partial<C>;
+  base: C;
+  cases: Record<OnboardingPreset, Partial<C>>;
+  meta: Record<OnboardingPreset, CaseMeta>;
+};
+
+/** `BASE_COPY ← BASE ← CASES[preset] ← config`, shallow. */
+export function resolveConfig<C extends object>(p: PresetsFile<C>, preset?: OnboardingPreset, config?: Partial<C>): C {
+  return { ...(p.baseCopy ?? {}), ...p.base, ...(preset ? p.cases[preset] ?? {} : {}), ...(config ?? {}) } as C;
+}
+
+/**
+ * **"What the config changes"** — the keys a resolved config sets differently from the default,
+ * in the order the preset names them. Generated, never hand-written: the site's case-study panel
+ * reads this, so a preset edit is reflected without touching a page.
+ */
+export function configChanges<C extends object>(p: PresetsFile<C>, preset: OnboardingPreset): { key: string; value: unknown }[] {
+  const base = resolveConfig(p) as Record<string, unknown>;
+  const resolved = resolveConfig(p, preset) as Record<string, unknown>;
+  return Object.keys(p.cases[preset] ?? {})
+    .filter(k => JSON.stringify(base[k]) !== JSON.stringify(resolved[k]))
+    .map(k => ({ key: k, value: resolved[k] }));
+}
+
+/** A config value as the panel prints it: lists by name or count, objects as their fields. */
+export function describeValue(v: unknown): string {
+  if (Array.isArray(v)) {
+    const names = v.map(x => (typeof x === 'object' && x !== null
+      ? String((x as Record<string, unknown>).label ?? (x as Record<string, unknown>).name ?? (x as Record<string, unknown>).title ?? '')
+      : String(x))).filter(Boolean);
+    return names.length === v.length ? names.join(', ') : `${v.length} items`;
+  }
+  if (typeof v === 'object' && v !== null) return Object.entries(v).map(([k, x]) => `${k}: ${Array.isArray(x) ? x.join(', ') : String(x)}`).join(' · ');
+  return String(v);
+}
+
+/** `{source}`-style placeholders in copy. */
+export function fill(template: string, values: Record<string, string | number>): string {
+  return template.replace(/\{(\w+)\}/g, (m, k: string) => (k in values ? String(values[k]) : m));
+}
+
+/** A config problem. The view refuses to render an invalid config and says why. */
+export type OnboardingIssue = { path: string; message: string };
+
+/**
+ * **The handoff's icon names** (the `ICONS` objects in the prototypes) — what a config may name.
+ * `iconFor` maps them onto `core/Icon`'s glyph names; those that differ are aliased below
+ * and an unknown name falls back to `spark`, as the prototypes do.
+ */
+export const ONBOARDING_ICONS = [
+  'alert', 'bell', 'bolt', 'briefcase', 'building', 'calendar', 'camera', 'cash', 'chart', 'chat', 'clock', 'code',
+  'compass', 'contacts', 'db', 'doc', 'download', 'eye', 'file', 'flame', 'flask', 'globe', 'grid', 'headset',
+  'hourglass', 'inbox', 'key', 'layers', 'layout', 'lifebuoy', 'link', 'mail', 'megaphone', 'monitor', 'palette', 'pen',
+  'phone', 'pie', 'pin', 'plane', 'pulse', 'receipt', 'refresh', 'rocket', 'search', 'server', 'shield', 'smile',
+  'spark', 'sparkle', 'table', 'tag', 'target', 'tasks', 'ticket', 'trend', 'upload', 'user', 'users', 'utensils',
+  'video', 'wallet',
+  /* Batch 2. */
+  'bellRing', 'book', 'box', 'card', 'cart', 'checkCircle', 'external', 'flag', 'folder', 'git', 'handshake', 'hardDrive',
+  'image', 'laptop', 'lock', 'map', 'mic', 'pencil', 'play', 'printer', 'question', 'template', 'terminal', 'truck',
+  'webhook', 'wifi',
+  /* Batch 3. */
+  'check2', 'filter', 'send', 'star', 'trophy', 'userCheck',
+  /* Batch 4. */
+  'receiptX',
+  /* Batch 5. */
+  'cloud',
+] as const;
+export type OnboardingIcon = (typeof ONBOARDING_ICONS)[number];
+
+const ICON_ALIAS: Partial<Record<OnboardingIcon, IconName>> = {
+  cloud: 'cloud-up',
+  sparkle: 'spark', smile: 'emoji', db: 'data', pin: 'map-pin',
+  bellRing: 'bell-ringing', checkCircle: 'check', hardDrive: 'hard-drive', image: 'media', pencil: 'edit',
+  check2: 'check', filter: 'funnel', userCheck: 'user-check', receiptX: 'receipt-x',
+};
+
+export function iconFor(name: string): IconName {
+  if ((ONBOARDING_ICONS as readonly string[]).includes(name)) return ICON_ALIAS[name as OnboardingIcon] ?? (name as IconName);
+  return 'spark';
+}
+
+/**
+ * **A demo-board scene as props** — the one mapping stories, the site's state switcher and the
+ * playground all use. `loading` / `empty` / `error` are the host's pattern status; every other
+ * scene is an `initial` seed; `default` is the case as it ships. `hold` says the scene is an
+ * operation in flight (Saving…, Connecting…): a board that wants it to stay put passes a
+ * `holdOperation()` — the README's `scene` prop is demo-only and is not shipped.
+ */
+export function sceneProps<C, Seed, S extends string>(
+  config: C,
+  scene: S | 'loading' | 'empty' | 'error',
+  seedOf: (config: C, scene: S) => Seed,
+  inFlight: readonly string[],
+): { status?: PatternStatus; initial?: Seed; hold: boolean } {
+  if (scene === 'loading' || scene === 'empty' || scene === 'error') return { status: scene as PatternStatus, hold: false };
+  if (scene === 'default') return { hold: false };
+  return { initial: seedOf(config, scene as S), hold: inFlight.includes(scene) };
+}

package/src/components/onboarding/shared/guard.tsx

@@ -0,0 +1,126 @@
+import { Component, useMemo, useRef, type ComponentType, type ReactNode } from 'react';
+import { BlockCard, Callout } from '../../../ds';
+import { resolveConfig, type OnboardingPreset, type PresetsFile } from './contract';
+import { InvalidConfig } from './InvalidConfig';
+import { shapeIssues } from './shape';
+import { ONBOARDING_BUTTONS, actionIssues, type ButtonAction, type ButtonActions } from './actions-data';
+import { runButtonAction } from './actions';
+import type { OnboardingComponent } from './contract';
+
+/**
+ * **Every onboarding component, guarded.** Two nets under the component's own validator:
+ *
+ * 1. **Before rendering** — the config's kinds are held to the presets' (`shapeIssues`); a wrong
+ *    kind is refused with the same "This step can't be shown" card the validator uses, naming the
+ *    field. A key set to `undefined` is left alone: it unsets the preset's value, as it always has.
+ * 2. **While rendering** — anything that still throws is caught here, shown as that card, and
+ *    handed to `onError` for the host's logging. The rest of the page keeps working. A new config,
+ *    preset, seed or status tries again.
+ *
+ * Operations that throw or reject never reach here: they end as the component's own failed state,
+ * with Retry.
+ */
+
+export type GuardProps = {
+  /** A render error the component could not show — for the host's error reporting. */
+  onError?: (error: Error) => void;
+  /**
+   * Custom actions for the buttons — by operation id (\`confirm\`), event (\`onSkip\`) or \`reload\`
+   * (the error state's Retry). A function, or JSON an agent can send (\`{ type: 'webhook', url }\`).
+   * Used where \`operations\` has none; see \`shared/actions\`.
+   */
+  actions?: ButtonActions;
+  /** One catch-all for every button operation that has neither an operation nor an action. (Not `onAction`: Floating has its own.) */
+  onButtonAction?: (action: string, request: unknown, ctx: { signal: AbortSignal; component: string }) => unknown;
+};
+
+type Base = { preset?: OnboardingPreset; config?: object; testID?: string; initial?: unknown; status?: unknown; operations?: object; reload?: unknown };
+
+export function guarded<P extends Base>(View: ComponentType<P>, presets: PresetsFile<object>, name: string) {
+  const component = presets.component as OnboardingComponent;
+  function Guarded({ onError, actions, onButtonAction, ...props }: P & GuardProps) {
+    const issues = useMemo(() => [...shapeIssues(presets, props.config), ...actionIssues(component, actions)], [props.config, actions]);
+    const wired = useButtonActions(component, props as unknown as Record<string, unknown>, actions, onButtonAction);
+    const title = (resolveConfig(presets, props.preset) as { title?: unknown }).title;
+    const heading = typeof title === 'string' ? title : undefined;
+    if (issues.length) return <InvalidConfig title={heading} issues={issues} testID={props.testID} />;
+    return (
+      <RenderNet title={heading} testID={props.testID} onError={onError} resetOn={[props.preset, props.config, props.initial, props.status]}>
+        <View {...(props as unknown as P)} {...(wired as Partial<P>)} />
+      </RenderNet>
+    );
+  }
+  Guarded.displayName = name;
+  return Guarded;
+}
+
+type NetProps = { title?: string; testID?: string; onError?: (e: Error) => void; resetOn: unknown[]; children: ReactNode };
+
+class RenderNet extends Component<NetProps, { error: Error | null }> {
+  state = { error: null as Error | null };
+
+  static getDerivedStateFromError(error: unknown) {
+    return { error: error instanceof Error ? error : new Error(String(error)) };
+  }
+
+  componentDidCatch(error: unknown) {
+    this.props.onError?.(error instanceof Error ? error : new Error(String(error)));
+  }
+
+  componentDidUpdate(prev: NetProps) {
+    if (this.state.error && prev.resetOn.some((v, i) => v !== this.props.resetOn[i])) this.setState({ error: null });
+  }
+
+  render() {
+    if (!this.state.error) return this.props.children;
+    return (
+      <BlockCard title={this.props.title || 'Onboarding step'} testID={this.props.testID}>
+        <Callout alert title="This step can’t be shown">
+          {`Something in its data could not be displayed (${this.state.error.message}). Check the config.`}
+        </Callout>
+      </BlockCard>
+    );
+  }
+}
+
+/**
+ * **Actions into the props the component already has.** Operations the host did not give are made
+ * from \`actions\` (then \`onButtonAction\`, for button operations); \`reload\` likewise; event actions run
+ * after the component's own callback. Nothing is added when nothing is asked for, so the built-in
+ * demo stays the last fallback. Stable across renders unless the actions change.
+ */
+function useButtonActions(
+  component: OnboardingComponent,
+  props: Record<string, unknown>,
+  actions: ButtonActions | undefined,
+  onAction: GuardProps['onButtonAction'],
+): Record<string, unknown> {
+  const latest = useRef(props);
+  latest.current = props;
+  const hostOps = props.operations as Record<string, unknown> | undefined;
+  const hostReload = props.reload;
+  return useMemo(() => {
+    if (!actions && !onAction) return {};
+    const as = (action: ButtonAction, id: string) => (request: unknown, ctx: { signal: AbortSignal; onProgress?: (p: number) => void }) =>
+      runButtonAction(action, request, { ...ctx, component, action: id });
+    const out: Record<string, unknown> = {};
+    const made: Record<string, unknown> = {};
+    for (const op of ONBOARDING_BUTTONS[component]?.operations ?? []) {
+      if (hostOps?.[op.id]) continue;
+      const a = actions?.[op.id];
+      if (a) made[op.id] = as(a, op.id);
+      else if (onAction && !op.data) made[op.id] = as((r, c) => onAction(op.id, r, { signal: c.signal, component }), op.id);
+    }
+    if (Object.keys(made).length) out.operations = { ...hostOps, ...made };
+    if (!hostReload && actions?.reload) out.reload = as(actions.reload, 'reload');
+    for (const [id, a] of Object.entries(actions ?? {})) {
+      if (!/^on[A-Z]/.test(id)) continue;
+      out[id] = (...args: unknown[]) => {
+        (latest.current[id] as ((...x: unknown[]) => void) | undefined)?.(...args);
+        void runButtonAction(a, args.length === 1 ? args[0] : args, { signal: new AbortController().signal, component, action: id })
+          .then(r => { if (!r.ok) console.warn(`[comppack] ${component} ${id}: ${r.message ?? 'the action failed'}`); });
+      };
+    }
+    return out;
+  }, [actions, onAction, hostOps, hostReload]);
+}

package/src/components/onboarding/shared/index.ts

@@ -0,0 +1,19 @@
+export {
+  ONBOARDING_COMPONENTS, ONBOARDING_ICONS, ONBOARDING_SCHEMA, PRESETS,
+  configChanges, describeValue, fill, iconFor, presetsOf, resolveConfig, sceneProps,
+  type CaseMeta, type HeaderConfig, type LoadCopy, type OnboardingComponent, type OnboardingIcon, type OnboardingIssue,
+  type OnboardingPreset, type OnboardingResult, type PatternStatus, type PresetsFile, type SavePhase,
+} from './contract';
+export {
+  ONBOARDING_TIMING, createMockOperation, createMockProgressOperation, holdOperation, mockReload,
+  type MockOperationOptions, type OnboardingOperation, type OnboardingOutcome, type ProgressOperation,
+} from './mock';
+export { runOutcome, useDefaultOperation, usePatternStatus, useSceneReport, useSeededReducer } from './runtime';
+export { FieldLabel, OnboardingCard, type FooterButton, type OnboardingCardProps } from './OnboardingCard';
+export { InvalidConfig } from './InvalidConfig';
+export { BusyGhost, CopyField, CrossFadeText, ExpandRegion, Hidden, HueTile, MintCheck, PlainChip, RevealRow, Slot, Spinner, StatusMark, UnreadDot } from './parts';
+export { guarded, type GuardProps } from './guard';
+export { shapeIssues } from './shape';
+/* The data half (server-importable) and the runner (React Native's Linking) — separate modules, so a server can read the buttons. */
+export { BUTTON_ACTION_TYPES, ONBOARDING_BUTTONS, actionIssues, type ButtonAction, type ButtonActionContext, type ButtonActionFn, type ButtonActionSpec, type ButtonActions } from './actions-data';
+export { runButtonAction } from './actions';

package/src/components/onboarding/shared/insight-parts.tsx

@@ -0,0 +1,146 @@
+import { useState, type ReactNode } from 'react';
+import { View } from 'react-native';
+import { Box, Icon, Pressable, Text } from '../../../core';
+import { blockRadii, useDs } from '../../../tokens';
+import { Hidden } from './parts';
+import { starFills, starsLabel } from './insight';
+
+/**
+ * **Batch 6's drawn parts** — the pieces two or more insight components share: stars (Feed, Score
+ * Summary), the split wells (Feed's `split`, Spider's Strongest / Weakest), clamped text with Show
+ * more (Feed's `text`, Spider's summary) and the footer well strip.
+ */
+
+/**
+ * **Five stars: ink fill on line** — half at ≥ .25, full at ≥ .75 — and the words ("4 out of 5
+ * stars") for a screen reader. `pop(i)` is star i's M15 pop (opacity, scale .6→1), when it has one.
+ */
+export function Stars({ value, max = 5, size = 12, pop }: { value: number; max?: number; size?: number; pop?: (i: number) => { opacity: number; scale: number } }) {
+  const { colors } = useDs();
+  return (
+    <View style={{ flexDirection: 'row', alignItems: 'center', gap: 1 }}>
+      <View aria-hidden style={{ flexDirection: 'row', gap: 1 }}>
+        {starFills(value, max).map((f, i) => {
+          const p = pop ? pop(i) : { opacity: 1, scale: 1 };
+          return (
+            <View key={i} style={{ width: size, height: size, opacity: p.opacity, transform: [{ scale: p.scale }] }}>
+              <Icon name="star" size={size} filled color={f === 'full' ? colors.textPrimary : colors.hairlineStrong} />
+              {f === 'half' ? <View style={{ position: 'absolute', left: 0, top: 0 }}><Icon name="star-half" size={size} filled color={colors.textPrimary} /></View> : null}
+            </View>
+          );
+        })}
+      </View>
+      <Hidden>{starsLabel(value, max)}</Hidden>
+    </View>
+  );
+}
+
+/** A 32px initials circle on line soft (12/600). Decoration: the row's title names the person. */
+export function Initials({ text, size = 32 }: { text: string; size?: number }) {
+  const { colors } = useDs();
+  return (
+    <Box width={size} height={size} align="center" justify="center" aria-hidden style={{ flexShrink: 0, borderRadius: size / 2, backgroundColor: colors.band }}>
+      <Text style={{ fontSize: 12, fontWeight: '600', color: colors.textPrimary }}>{text.slice(0, 3)}</Text>
+    </Box>
+  );
+}
+
+/**
+ * **Two wells side by side** — mint-deep "+" items, apricot-deep "−" items (radius 12, padding
+ * 12/14, gap 8). An empty side is hidden; both empty, nothing is drawn. `stacked` on mobile.
+ */
+export function SplitWells({ positiveTitle, positive, negativeTitle, negative, stacked }: {
+  positiveTitle: string; positive: string[]; negativeTitle: string; negative: string[]; stacked?: boolean;
+}) {
+  const { colors } = useDs();
+  const sides = [
+    { title: positiveTitle, items: positive, ink: colors.status.executed, mark: '+' },
+    { title: negativeTitle, items: negative, ink: colors.status.needsUser, mark: '−' },
+  ].filter(s => s.items.length > 0);
+  if (!sides.length) return null;
+  return (
+    <View style={{ flexDirection: stacked ? 'column' : 'row', gap: 8 }}>
+      {sides.map(s => (
+        <Box key={s.title} gap="s1" style={{ flex: stacked ? undefined : 1, flexBasis: stacked ? undefined : 0, minWidth: 0, paddingVertical: 12, paddingHorizontal: 14, borderRadius: blockRadii.mid, backgroundColor: colors.surfaceSunken }}>
+          <Text style={{ fontSize: 12, fontWeight: '700', color: s.ink }}>{s.title}</Text>
+          <View role={'list' as never} aria-label={s.title} style={{ gap: 4 }}>
+            {s.items.map((it, i) => (
+              <View key={i} role={'listitem' as never} style={{ flexDirection: 'row', gap: 6 }}>
+                <Text aria-hidden style={{ fontSize: 13, fontWeight: '600', color: s.ink, width: 10 }}>{s.mark}</Text>
+                <Text style={{ flex: 1, fontSize: 13, lineHeight: 19, color: colors.textPrimary }}>{it}</Text>
+              </View>
+            ))}
+          </View>
+        </Box>
+      ))}
+    </View>
+  );
+}
+
+/** A coral-deep 12/600 text button — Show more, Clear, View as list. */
+export function InlineAction({ label, onPress, expanded, controls, accessibilityLabel }: { label: string; onPress: () => void; expanded?: boolean; controls?: string; accessibilityLabel?: string }) {
+  const { colors } = useDs();
+  return (
+    <Pressable onPress={onPress} aria-expanded={expanded} aria-controls={controls} aria-label={accessibilityLabel} alignSelf="flex-start" minHeight={24} style={{ paddingHorizontal: 2, paddingVertical: 2, borderRadius: blockRadii.inset }}>
+      <Text style={{ fontSize: 12, fontWeight: '600', color: colors.accentInk }}>{label}</Text>
+    </Pressable>
+  );
+}
+
+/**
+ * **Text that clamps past `limit` characters** — to `lines` lines, with Show more / Show less
+ * (`aria-expanded`). At or under the limit it is simply the text.
+ */
+export function ClampText({ body, limit, lines, nativeID, style }: { body: string; limit: number; lines: number; nativeID: string; style?: object }) {
+  const { colors } = useDs();
+  const [open, setOpen] = useState(false);
+  const long = body.length > limit;
+  return (
+    <View style={{ gap: 4 }}>
+      <Text nativeID={nativeID} numberOfLines={long && !open ? lines : undefined} style={{ fontSize: 13, lineHeight: 21, color: colors.textPrimary, ...style }}>{body}</Text>
+      {long ? <InlineAction label={open ? 'Show less' : 'Show more'} expanded={open} controls={nativeID} onPress={() => setOpen(o => !o)} /> : null}
+    </View>
+  );
+}
+
+/** The footer: a well strip (radius 12, padding 10/14, 12px muted) — one line left, one right. */
+export function WellStrip({ left, right }: { left?: ReactNode; right?: ReactNode }) {
+  const { colors } = useDs();
+  if (!left && !right) return null;
+  const txt = (v: ReactNode) => (typeof v === 'string' ? <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{v}</Text> : v);
+  return (
+    <View style={{ flexDirection: 'row', flexWrap: 'wrap', justifyContent: 'space-between', gap: 8, paddingVertical: 10, paddingHorizontal: 14, borderRadius: blockRadii.mid, backgroundColor: colors.surfaceSunken }}>
+      {left ? txt(left) : <View />}
+      {right ? txt(right) : null}
+    </View>
+  );
+}
+
+/** A band chip in the handoff's three tones — mint, plain, apricot — at 22 or 24px. */
+export function BandChip({ label, tone, height = 24 }: { label: string; tone: 'mint' | 'plain' | 'apricot'; height?: number }) {
+  const { colors } = useDs();
+  const skin = tone === 'mint' ? { bg: colors.statusBg.executed, ink: colors.status.executed }
+    : tone === 'apricot' ? { bg: colors.statusBg.needsUser, ink: colors.status.needsUser }
+    : { bg: colors.band, ink: colors.textPrimary };
+  return (
+    <Box row align="center" alignSelf="flex-start" gap="s1" height={height} radius="pill" style={{ paddingHorizontal: 10, backgroundColor: skin.bg }}>
+      {tone !== 'plain' ? <Box width={6} height={6} radius="pill" style={{ backgroundColor: skin.ink }} /> : null}
+      <Text numeric numberOfLines={1} style={{ fontSize: 12, fontWeight: '600', color: skin.ink }}>{label}</Text>
+    </Box>
+  );
+}
+
+/** An inline apricot alert (title 12/700, body 12) — "Couldn't save your vote", "Couldn't load this day". */
+export function ApricotAlert({ title, body, action }: { title: string; body?: string; action?: ReactNode }) {
+  const { colors } = useDs();
+  return (
+    <View role="alert" style={{ flexDirection: 'row', alignItems: 'flex-start', gap: 8, paddingVertical: 10, paddingHorizontal: 12, borderRadius: blockRadii.mid, backgroundColor: colors.statusBg.needsUser }}>
+      <Icon name="alert" size={15} color={colors.status.needsUser} />
+      <View style={{ flex: 1, gap: 2 }}>
+        <Text style={{ fontSize: 12, fontWeight: '700', color: colors.status.needsUser }}>{title}</Text>
+        {body ? <Text style={{ fontSize: 12, color: colors.status.needsUser }}>{body}</Text> : null}
+      </View>
+      {action}
+    </View>
+  );
+}