@appinternalleads/ui 0.2.0

package/src/components/onboarding/conversion-funnel/presets.json

@@ -0,0 +1,217 @@
+{
+  "component": "conversion-funnel",
+  "baseCopy": {
+    "loadErrorTitle": "Couldn’t load this step",
+    "loadErrorBody": "Nothing was lost. Retry to load it again.",
+    "retryLabel": "Retry",
+    "emptyCta": "Refresh"
+  },
+  "base": {
+    "type": "data",
+    "icon": "filter",
+    "title": "Product funnel",
+    "subtitle": "Visitors to retained customers · last 30 days",
+    "stages": [
+      {
+        "name": "Visitors",
+        "count": 100000
+      },
+      {
+        "name": "Sign-ups",
+        "count": 12000
+      },
+      {
+        "name": "Activated",
+        "count": 8412
+      },
+      {
+        "name": "Subscribed",
+        "count": 2100
+      },
+      {
+        "name": "Retained",
+        "count": 1800
+      }
+    ],
+    "emptyTitle": "Add at least 2 stages",
+    "emptyBody": "A funnel needs a starting stage and at least one step after it.",
+    "emptyCta": "Add stage",
+    "period": null,
+    "periods": [],
+    "ship": null
+  },
+  "cases": {
+    "case1": {},
+    "case2": {
+      "type": "data",
+      "icon": "cart",
+      "title": "Checkout funnel",
+      "subtitle": "Harbor Goods · web store",
+      "period": "Aug 2026",
+      "periods": [
+        "Aug 2026",
+        "Sep 2026"
+      ],
+      "stages": [
+        {
+          "name": "Product view",
+          "count": 48000,
+          "period": "Aug 2026"
+        },
+        {
+          "name": "Add to cart",
+          "count": 9600,
+          "period": "Aug 2026"
+        },
+        {
+          "name": "Checkout",
+          "count": 6200,
+          "period": "Aug 2026"
+        },
+        {
+          "name": "Payment",
+          "count": 4900,
+          "period": "Aug 2026"
+        },
+        {
+          "name": "Order",
+          "count": 4100,
+          "period": "Aug 2026"
+        },
+        {
+          "name": "Product view",
+          "count": 52000,
+          "period": "Sep 2026"
+        },
+        {
+          "name": "Add to cart",
+          "count": 14600,
+          "period": "Sep 2026"
+        },
+        {
+          "name": "Checkout",
+          "count": 3900,
+          "period": "Sep 2026"
+        },
+        {
+          "name": "Payment",
+          "count": 3100,
+          "period": "Sep 2026"
+        },
+        {
+          "name": "Order",
+          "count": 2700,
+          "period": "Sep 2026"
+        }
+      ]
+    },
+    "case3": {
+      "type": "action",
+      "icon": "briefcase",
+      "title": "Hiring pipeline",
+      "subtitle": "Senior product designer · since June",
+      "stages": [
+        {
+          "name": "Applied",
+          "count": 1240
+        },
+        {
+          "name": "Screened",
+          "count": 310
+        },
+        {
+          "name": "Interviewed",
+          "count": 64
+        },
+        {
+          "name": "Offer",
+          "count": 9
+        },
+        {
+          "name": "Hired",
+          "count": 6
+        }
+      ]
+    },
+    "case4": {
+      "type": "agent",
+      "icon": "sparkle",
+      "title": "Agent task funnel",
+      "subtitle": "Assistant requests · this week",
+      "stages": [
+        {
+          "name": "Requests",
+          "count": 18400
+        },
+        {
+          "name": "Understood",
+          "count": 17300
+        },
+        {
+          "name": "Tool succeeded",
+          "count": 14100
+        },
+        {
+          "name": "Answer accepted",
+          "count": 11900
+        }
+      ]
+    },
+    "case5": {
+      "type": "action",
+      "icon": "mail",
+      "title": "Email campaign",
+      "subtitle": "Autumn launch · sent Tuesday",
+      "ship": "loadReady",
+      "stages": [
+        {
+          "name": "Sent",
+          "count": 40000
+        },
+        {
+          "name": "Delivered",
+          "count": 38900
+        },
+        {
+          "name": "Opened",
+          "count": 12400
+        },
+        {
+          "name": "Clicked",
+          "count": 1900
+        },
+        {
+          "name": "Converted",
+          "count": 0
+        }
+      ]
+    }
+  },
+  "meta": {
+    "case1": {
+      "eyebrow": "Case study 1 · SaaS",
+      "title": "Product funnel",
+      "scenario": "The reference funnel. The biggest drop is 88%, at sign-up."
+    },
+    "case2": {
+      "eyebrow": "Case study 2 · E-commerce",
+      "title": "Checkout funnel",
+      "scenario": "Switch from August to September: the widths tween and the biggest drop moves from Add to cart to Checkout."
+    },
+    "case3": {
+      "eyebrow": "Case study 3 · Hiring",
+      "title": "Hiring pipeline",
+      "scenario": "Small numbers, from 1,240 down to 6. The last stage is 0.5% wide, so it sits on the 2px floor."
+    },
+    "case4": {
+      "eyebrow": "Case study 4 · AI agent",
+      "title": "Agent task funnel",
+      "scenario": "Four stages, from request to accepted answer."
+    },
+    "case5": {
+      "eyebrow": "Case study 5 · Marketing",
+      "title": "Email campaign",
+      "scenario": "Loads, then cascades. Nothing converted, so the last stage has no bar and a 100% drop-off."
+    }
+  }
+}

package/src/components/onboarding/criteria-spider/CriteriaSpiderView.tsx

@@ -0,0 +1,319 @@
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
+import { View } from 'react-native';
+import { Box, Pressable, Radar, Select, Text } from '../../../core';
+import { blockRadii, useDs, type DensityName } from '../../../tokens';
+import { resolveConfig, type OnboardingPreset, type OnboardingResult, type PatternStatus } from '../shared/contract';
+import type { OnboardingOperation } from '../shared/mock';
+import { InvalidConfig } from '../shared/InvalidConfig';
+import { OnboardingCard } from '../shared/OnboardingCard';
+import { usePatternStatus, useSceneReport } from '../shared/runtime';
+import { guarded } from '../shared/guard';
+import { Hidden, PlainChip } from '../shared/parts';
+import { BandChip, ClampText, SplitWells } from '../shared/insight-parts';
+import { RADAR, radarLabel, radarPoint } from '../shared/insight';
+import { M15, progress, toneIn } from '../shared/m15';
+import { DataTip, VizBar, useInView, useRevealClock, useTweenedValues } from '../shared/viz';
+import { SPIDER_PRESETS, validateSpider, type SpiderSettings } from './contract';
+import {
+  bestWorst, initialSpider, radarSummary, spiderBand, spiderDigits, spiderRevealEnd, spiderRows, spiderScene, spiderSeed, spiderTip, type SpiderSeed,
+} from './engine';
+
+export type CriteriaSpiderProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<SpiderSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  /** Read-only; accepted for the shared shape. */
+  result?: OnboardingResult;
+  reload?: OnboardingOperation<void>;
+  initial?: SpiderSeed;
+  /** `mobile`: the radar caps at 300, the criteria take one column, the split stacks. */
+  viewport?: 'web' | 'mobile';
+  /** A tab chosen — the item's id. */
+  onItemChange?: (id: string) => void;
+  /** Compare turned on (the compared item's id) or off (`null`). */
+  onCompare?: (id: string | null) => void;
+  replay?: number;
+  forceReduced?: boolean;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/** M16: a shape morph is 400ms. */
+const MORPH_MS = 400;
+const SUMMARY_LIMIT = 260;
+
+/**
+ * **Criteria Spider** — a segmented tablist of items (←/→/Home/End), the item's score (32/700) and
+ * band, an SVG radar (5 rings, spokes, the ink polygon at 10% fill, vertex dots; a dashed compare
+ * overlay), the criteria as bars (best mint, worst apricot, after the count), Strongest / Weakest,
+ * a summary that clamps at 4 lines, and chips. M15 grows the polygon from the centre; M16 morphs it
+ * between items.
+ */
+function CriteriaSpiderView(props: CriteriaSpiderProps) {
+  const config = resolveConfig(SPIDER_PRESETS, props.preset, props.config);
+  const issues = validateSpider(config);
+  if (issues.length) return <InvalidConfig title={config.title} issues={issues} testID={props.testID} />;
+  return <Valid {...props} config={config} />;
+}
+
+function Valid({
+  config, density, status, reload, initial, viewport = 'web', onItemChange, onCompare, replay, forceReduced, onScene, testID,
+}: Omit<CriteriaSpiderProps, 'config'> & { config: SpiderSettings }) {
+  const { colors, lift1 } = useDs();
+  const uid = useId().replace(/:/g, '');
+  const key = JSON.stringify([config, initial ?? null]);
+  const rows = useMemo(() => spiderRows(config), [key]);
+  const seed = useMemo(() => initialSpider(config, initial ?? (config.ship ? spiderSeed(config, config.ship) : {})), [key]);
+  const [active, setActive] = useState(seed.active);
+  const [compare, setCompare] = useState(seed.compare);
+  /* After Compare turns off, the overlay keeps its shape while it fades (160ms), then rests at the centre. */
+  const [fading, setFading] = useState<string | null>(null);
+  useEffect(() => { setActive(seed.active); setCompare(seed.compare); setFading(null); }, [seed]);
+  useEffect(() => {
+    if (!fading) return;
+    const t = setTimeout(() => setFading(null), 200);
+    return () => clearTimeout(t);
+  }, [fading]);
+
+  const pattern = usePatternStatus(status ?? (seed.loadReady ? 'loading' : rows.length ? 'ready' : 'empty'), reload);
+  useEffect(() => {
+    if (!seed.loadReady || status) return;
+    const t = setTimeout(() => pattern.set('ready'), 1200);
+    return () => clearTimeout(t);
+  }, [seed, status, replay]);
+  useSceneReport(pattern.status === 'ready' ? (seed.loadReady ? 'loadReady' : spiderScene({ ...seed, active, compare }, config)) : pattern.status, onScene);
+
+  const n = config.criteria.length;
+  const max = config.max;
+  const digits = spiderDigits(max);
+  const item = rows.find(r => r.id === active) ?? rows[0];
+  const cmp = compare ? rows.find(r => r.id === compare) ?? null : null;
+  const ghost = fading ? rows.find(r => r.id === fading) ?? null : null;
+
+  const [ref, inView] = useInView();
+  const clock = useRevealClock(inView && pattern.status === 'ready' && Boolean(item), spiderRevealEnd(n), `${replay ?? 0}|${pattern.status}`, forceReduced);
+  const t = clock.t;
+
+  /* M16: the item's values, the score and the overlay tween between items over 400ms. */
+  const vals = item?.values ?? [];
+  const shown = useTweenedValues([item?.score ?? 0, ...vals], MORPH_MS, clock.done, clock.reduced);
+  const overlayTarget = (cmp ?? ghost)?.values ?? vals.map(() => 0);
+  /* The overlay always tweens (its reveal is its own): on, it grows from the centre. */
+  const overlay = useTweenedValues(overlayTarget, MORPH_MS, true, clock.reduced);
+  const overlayOp = useTweenedValues([cmp ? 1 : 0], M15.toneMs, true, clock.reduced)[0]!;
+  const [hi, setHi] = useState(-1);
+  const tabs = useRef<Record<string, { focus?: () => void } | null>>({});
+
+  if (!item) return <OnboardingCard testID={testID} header={config} copy={config} density={density} status={pattern.status} onRetry={pattern.retry} onEmptyAction={pattern.retry}>{null}</OnboardingCard>;
+  const grow = clock.done ? 1 : progress(t, 0, M15.fillMs);
+  const vOf = (i: number) => (clock.done ? shown[1 + i]! : vals[i]!);
+  const { best, worst } = bestWorst(vals);
+  const band = spiderBand(item, max);
+  const scoreShown = clock.done ? shown[0]! : item.score * grow;
+  const lateIn = clock.done ? 1 : progress(t, 1200, M15.toneMs);
+  const mobile = viewport === 'mobile';
+
+  const vertex = (i: number, v: number) => radarPoint(i, n, (RADAR.r * Math.max(0, Math.min(v, max))) / max);
+  const scaled = (p: [number, number]): [number, number] => [RADAR.cx + (p[0] - RADAR.cx) * grow, RADAR.cy + (p[1] - RADAR.cy) * grow];
+  const primary = vals.map((_, i) => scaled(vertex(i, vOf(i))));
+  const rings = [1, 2, 3, 4, 5].map(q => config.criteria.map((_, i) => radarPoint(i, n, (RADAR.r * q) / RADAR.rings)));
+  const spokes = config.criteria.map((_, i) => ({ from: [RADAR.cx, RADAR.cy] as [number, number], to: radarPoint(i, n, RADAR.r), color: hi === i ? colors.hairlineStrong : colors.hairline }));
+  const showOverlay = Boolean(cmp || ghost);
+  const overlayPts = overlay.map((v, i) => vertex(i, v));
+
+  const pick = (id: string) => {
+    if (id === active) return;
+    setActive(id);
+    if (compare === id) setCompare(null);
+    onItemChange?.(id);
+  };
+  const onTabKey = (e: { key: string; preventDefault: () => void }) => {
+    const ids = rows.map(r => r.id);
+    const k = ids.indexOf(item.id);
+    const m: Record<string, number> = { ArrowRight: k + 1, ArrowLeft: k - 1 + ids.length, Home: 0, End: ids.length - 1 };
+    if (!(e.key in m)) return;
+    e.preventDefault();
+    const next = ids[m[e.key]! % ids.length]!;
+    pick(next);
+    setTimeout(() => tabs.current[next]?.focus?.(), 30);
+  };
+  const others = rows.filter(r => r.id !== item.id);
+  const toggleCompare = () => {
+    if (cmp) { setFading(cmp.id); setCompare(null); onCompare?.(null); return; }
+    const next = others[0]?.id ?? null;
+    setCompare(next);
+    onCompare?.(next);
+  };
+
+  return (
+    <OnboardingCard testID={testID} header={config} copy={config} density={density} status={pattern.status} onRetry={pattern.retry} onEmptyAction={pattern.retry}>
+      <View ref={ref} style={{ opacity: clock.reduced ? clock.fade : 1, gap: 16 }}>
+        {rows.length > 1 ? (
+          <View role={'tablist' as never} aria-label={config.title} style={{ flexDirection: 'row', padding: 3, gap: 2, borderRadius: blockRadii.inset, backgroundColor: colors.surfaceSunken, alignSelf: mobile ? 'stretch' : 'flex-start' }}>
+            {rows.map(r => {
+              const on = r.id === item.id;
+              return (
+                <Pressable
+                  key={r.id}
+                  ref={((el: unknown) => { tabs.current[r.id] = el as never; }) as never}
+                  role={'tab' as never}
+                  aria-selected={on}
+                  tabIndex={on ? 0 : -1}
+                  onPress={() => pick(r.id)}
+                  onKeyDown={onTabKey}
+                  align="center"
+                  justify="center"
+                  flex={mobile ? 1 : undefined}
+                  style={{ height: 30, paddingHorizontal: 12, borderRadius: blockRadii.tile, backgroundColor: on ? colors.surface1 : 'transparent', boxShadow: on ? lift1 : 'none' } as object}>
+                  <Text numberOfLines={1} style={{ fontSize: 13, fontWeight: '600', color: on ? colors.textPrimary : colors.textSecondary }}>{r.name}</Text>
+                </Pressable>
+              );
+            })}
+          </View>
+        ) : null}
+
+        <Box row align="flex-start" justify="space-between" gap="s3" style={{ flexWrap: 'wrap' }}>
+          <View style={{ flexShrink: 1, gap: 2 }}>
+            <Text style={{ fontSize: 14, fontWeight: '600', color: colors.textPrimary }}>{item.name}</Text>
+            {item.category ? <Text style={{ fontSize: 12, color: colors.textSecondary }}>{item.category}</Text> : null}
+          </View>
+          <View style={{ alignItems: 'flex-end', gap: 4 }}>
+            <Box row align="flex-end" gap="s1">
+              <Text numeric style={{ fontSize: 32, lineHeight: 36, fontWeight: '700', letterSpacing: -0.6, color: colors.textPrimary }}>{scoreShown.toFixed(digits)}</Text>
+              <Text numeric style={{ fontSize: 13, color: colors.textSecondary, marginBottom: 5 }}>{`/ ${max}`}</Text>
+            </Box>
+            <Box row align="center" gap="s2">
+              <View style={{ opacity: clock.done ? 1 : toneIn(M15.fillMs, t) }}><BandChip label={band.label} tone={band.tone} height={22} /></View>
+              {item.reviews ? <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{item.reviews}</Text> : null}
+            </Box>
+          </View>
+        </Box>
+
+        <View style={{ gap: 8 }}>
+          {others.length ? (
+            <Box row align="center" justify="flex-end" gap="s2" style={{ flexWrap: 'wrap' }}>
+              {cmp ? (
+                <Box style={{ minWidth: 150 }}>
+                  <Select
+                    aria-label="Compare with"
+                    value={cmp.id}
+                    options={others.map(o => ({ value: o.id, label: o.name }))}
+                    onChange={id => { setCompare(id); onCompare?.(id); }}
+                  />
+                </Box>
+              ) : null}
+              <Pressable
+                onPress={toggleCompare}
+                aria-pressed={Boolean(cmp)}
+                row
+                align="center"
+                press="scale"
+                minHeight={28}
+                style={{ paddingHorizontal: 10, borderRadius: blockRadii.inset, borderWidth: 1, borderColor: colors.hairlineStrong, backgroundColor: cmp ? colors.surfaceSunken : colors.surface1 }}>
+                <Text style={{ fontSize: 12, fontWeight: '600', color: colors.textPrimary }}>{cmp ? 'Comparing' : 'Compare'}</Text>
+              </Pressable>
+            </Box>
+          ) : null}
+          <View role="status" aria-live="polite" style={{ position: 'absolute', width: 1, height: 1, overflow: 'hidden', left: -10000 }}>
+            <Text>{cmp ? `Comparing with ${cmp.name}` : ''}</Text>
+          </View>
+          <View style={{ position: 'relative', width: '100%', maxWidth: mobile ? 300 : 380, alignSelf: 'center' }}>
+            <Radar
+              width={RADAR.w}
+              height={RADAR.h}
+              rings={rings}
+              spokes={spokes}
+              ringColor={colors.hairline}
+              label={radarSummary(item, config.criteria.map(k => k.label), max, cmp)}
+              shapes={[
+                ...(showOverlay ? [{ points: overlayPts, stroke: colors.textSecondary, strokeWidth: 1.5, dash: '4 3', opacity: overlayOp }] : []),
+                { points: primary, stroke: colors.textPrimary, strokeWidth: 1.5, fill: colors.textPrimary, fillOpacity: 0.1 * grow },
+              ]}
+              dots={[
+                ...(showOverlay ? overlayPts.map(([x, y]) => ({ x, y, r: 3.5, fill: colors.surface1, stroke: colors.textSecondary, opacity: overlayOp })) : []),
+                ...primary.map(([x, y], i) => {
+                  const q = clock.done ? 1 : progress(t, 400 + i * 60, M15.toneMs);
+                  return { x, y, r: 4, fill: colors.textPrimary, stroke: colors.surface1, opacity: q, scale: 0.6 + 0.4 * q };
+                }),
+              ]}
+            />
+            {config.criteria.map((k, i) => {
+              const l = radarLabel(i, n);
+              return (
+                <View
+                  key={k.id ?? i}
+                  aria-hidden
+                  pointerEvents="none"
+                  style={{
+                    position: 'absolute', left: `${l.left}%`, top: `${l.top}%`, width: 96,
+                    transform: [{ translateX: l.anchor === 'start' ? 0 : l.anchor === 'end' ? -96 : -48 }, { translateY: '-50%' }],
+                  } as object}>
+                  <Text style={{ fontSize: 11, lineHeight: 14, textAlign: l.anchor === 'start' ? 'left' : l.anchor === 'end' ? 'right' : 'center', color: hi === i ? colors.textPrimary : colors.textSecondary }}>{k.label}</Text>
+                </View>
+              );
+            })}
+          </View>
+        </View>
+
+        <View role={'list' as never} aria-label="Criteria" style={{ flexDirection: 'row', flexWrap: 'wrap', columnGap: 16 } as object}>
+          {config.criteria.map((k, i) => {
+            const v = vals[i]!;
+            const start = 600 + i * 60;
+            const fill = clock.done ? 1 : progress(t, start, M15.fillMs);
+            const toneP = clock.done ? 1 : toneIn(start + M15.fillMs, t);
+            const tone = i === best ? colors.status.executed : i === worst ? colors.status.needsUser : undefined;
+            const cv = cmp ? cmp.values[i]! : 0;
+            const text = `${(clock.done ? vOf(i) : v * fill).toFixed(digits)}${cmp ? ` vs ${cv.toFixed(digits)}` : ''}`;
+            return (
+              <View key={k.id ?? i} role={'listitem' as never} style={{ width: mobile ? '100%' : '48%', flexGrow: 1 }}>
+                <DataTip
+                  label={spiderTip(k.label, v, max, cmp ? { name: cmp.name, value: cv } : undefined)}
+                  onHover={on => setHi(h => (on ? i : h === i ? -1 : h))}
+                  style={{ paddingHorizontal: 6, paddingVertical: 6 }}>
+                  <Box row align="center" gap="s2">
+                    <Text numberOfLines={1} style={{ width: 108, fontSize: 12, color: colors.textPrimary }}>{k.label}</Text>
+                    <View style={{ flex: 1, gap: 3 }}>
+                      <VizBar
+                        scale={(clock.done ? vOf(i) : v * fill) / max}
+                        height={cmp ? 4 : 6}
+                        color={colors.textPrimary}
+                        track={colors.band}
+                        a11y={{ role: 'meter', label: k.label, now: v, max, text: `${v.toFixed(digits)} of ${max}${i === best ? ', strongest' : i === worst ? ', weakest' : ''}` }}
+                      />
+                      {cmp ? <VizBar scale={(overlay[i] ?? 0) / max} height={3} color={colors.textSecondary} track={colors.band} /> : null}
+                    </View>
+                    <View style={{ minWidth: cmp ? 72 : 32, alignItems: 'flex-end' }}>
+                      <Text numeric style={{ fontSize: 12, fontWeight: '600', color: colors.textPrimary, opacity: tone ? 1 - toneP : 1 }}>{text}</Text>
+                      {tone ? <Text numeric aria-hidden style={{ position: 'absolute', right: 0, top: 0, fontSize: 12, fontWeight: '600', color: tone, opacity: toneP }}>{text}</Text> : null}
+                    </View>
+                    {i === best ? <Hidden>(strongest)</Hidden> : i === worst ? <Hidden>(weakest)</Hidden> : null}
+                  </Box>
+                </DataTip>
+              </View>
+            );
+          })}
+        </View>
+
+        <View style={{ opacity: lateIn, gap: 12 }}>
+          <SplitWells
+            positiveTitle={item.strongest.title ?? `Strongest: ${config.criteria[best]?.label ?? ''}`}
+            positive={item.strongest.points}
+            negativeTitle={item.weakest.title ?? `Weakest: ${config.criteria[worst >= 0 ? worst : best]?.label ?? ''}`}
+            negative={item.weakest.points}
+            stacked={mobile}
+          />
+          {item.summary ? <ClampText key={item.id} body={item.summary} limit={SUMMARY_LIMIT} lines={4} nativeID={`${uid}-sum`} /> : null}
+          {item.chips.length ? (
+            <Box row gap="s2" style={{ flexWrap: 'wrap' }}>
+              {item.chips.map(c => <PlainChip key={c}>{c}</PlainChip>)}
+            </Box>
+          ) : null}
+        </View>
+      </View>
+    </OnboardingCard>
+  );
+}
+
+/** CriteriaSpider, guarded: a wrong-kind config is refused by name and a render error is caught (`shared/guard`). */
+export const CriteriaSpider = guarded(CriteriaSpiderView, SPIDER_PRESETS, 'CriteriaSpider');

package/src/components/onboarding/criteria-spider/contract.ts

@@ -0,0 +1,83 @@
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import type { Band } from '../shared/insight';
+import presetsJson from './presets.json';
+
+/**
+ * **Criteria Spider (batch 6 §4.3)** — items scored on shared criteria: tabs, a radar with an
+ * optional compare overlay, the criteria as bars (the accessible version of the data), the
+ * strongest and weakest points, a summary and chips. Read-only. M15 on first view; M16 — the
+ * shape morph — on a tab switch or a new compared item.
+ */
+
+export type SpiderCriterion = { id?: string; label: string };
+/** Points, or `{ title, points }` to replace "Strongest: {criterion}". */
+export type SpiderPoints = string[] | { title?: string; points: string[] };
+export type SpiderItem = {
+  id?: string;
+  name: string;
+  category?: string;
+  /** The overall score, 0…max. */
+  score: number;
+  /** "4,827 reviews" */
+  reviews?: string;
+  /** One value per criterion, in order — or keyed by criterion id. */
+  values: number[] | Record<string, number>;
+  strongest?: SpiderPoints;
+  weakest?: SpiderPoints;
+  summary?: string;
+  chips?: string[];
+  /** Overrides the default band (≥ 90% Excellent, ≥ 80% Very good, ≥ 60% Good, else Needs work). */
+  band?: Band;
+};
+
+export const SPIDER_SCENES = ['default', 'next', 'compare', 'compareNext', 'loadReady', 'loading', 'empty', 'error'] as const;
+export type SpiderScene = (typeof SPIDER_SCENES)[number];
+export const SPIDER_IN_FLIGHT: readonly string[] = [];
+
+export type SpiderSettings = HeaderConfig & LoadCopy & {
+  /** The scale every value and score is on (10, 100). */
+  max: number;
+  /** The axes, clockwise from 12 o'clock. Three or more. */
+  criteria: SpiderCriterion[];
+  items: SpiderItem[];
+  /** The item shown first (default: the first). */
+  activeId: string | null;
+  /** Compare on arrival, with this item. */
+  compareId: string | null;
+  /** Demo-only: the scene this case ships in. */
+  ship: SpiderScene | null;
+};
+
+export const SPIDER_PRESETS = presetsJson as unknown as PresetsFile<SpiderSettings>;
+
+const num = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+const points = (v: unknown) => v === undefined || (Array.isArray(v) && v.every(x => typeof x === 'string'))
+  || (!!v && typeof v === 'object' && Array.isArray((v as { points?: unknown }).points));
+
+export function validateSpider(c: SpiderSettings): OnboardingIssue[] {
+  if (!c || typeof c !== 'object') return [{ path: 'config', message: 'must be an object.' }];
+  const out: OnboardingIssue[] = [];
+  if (!num(c.max) || c.max <= 0) out.push({ path: 'max', message: 'max is a number above 0.' });
+  if (!Array.isArray(c.criteria)) return [...out, { path: 'criteria', message: 'criteria is a list of { label }.' }];
+  if (!Array.isArray(c.items)) return [...out, { path: 'items', message: 'items is a list.' }];
+  c.criteria.forEach((k, i) => { if (!k || typeof k !== 'object' || typeof k.label !== 'string') out.push({ path: `criteria[${i}].label`, message: 'Every criterion needs a label.' }); });
+  if (c.items.length && c.criteria.length < 3) out.push({ path: 'criteria', message: 'A radar needs at least 3 criteria.' });
+  const ids = c.criteria.map((k, i) => (k && typeof k.id === 'string' ? k.id : `k${i}`));
+  c.items.forEach((it, i) => {
+    const p = `items[${i}]`;
+    if (!it || typeof it !== 'object') { out.push({ path: p, message: 'Each item is { name, score, values }.' }); return; }
+    if (typeof it.name !== 'string' || !it.name.trim()) out.push({ path: `${p}.name`, message: 'Every item needs a name.' });
+    if (!num(it.score)) out.push({ path: `${p}.score`, message: 'score is a number.' });
+    if (Array.isArray(it.values)) {
+      if (it.values.length !== c.criteria.length) out.push({ path: `${p}.values`, message: `values has ${it.values.length}; there are ${c.criteria.length} criteria.` });
+      if (!it.values.every(num)) out.push({ path: `${p}.values`, message: 'values are numbers.' });
+    } else if (it.values && typeof it.values === 'object') {
+      const missing = ids.filter(id => !num((it.values as Record<string, unknown>)[id]));
+      if (missing.length === ids.length) out.push({ path: `${p}.values`, message: `values are keyed by criterion id (${ids.join(', ')}).` });
+    } else out.push({ path: `${p}.values`, message: 'values is a list of numbers, one per criterion.' });
+    if (!points(it.strongest)) out.push({ path: `${p}.strongest`, message: 'strongest is a list of text.' });
+    if (!points(it.weakest)) out.push({ path: `${p}.weakest`, message: 'weakest is a list of text.' });
+    if (it.chips !== undefined && !(Array.isArray(it.chips) && it.chips.every(x => typeof x === 'string'))) out.push({ path: `${p}.chips`, message: 'chips is a list of text.' });
+  });
+  return out;
+}