@appinternalleads/ui 0.3.0 → 0.4.1

package/src/agent/search/types.ts

@@ -0,0 +1,68 @@
+/**
+ * **Component search — its internal types.** None of this is part of the agent contract: the agent
+ * calls `searchComponents(query)` and gets cards. How candidates are found — lexical, semantic,
+ * in memory or not — can change without it knowing.
+ */
+
+/** Turns text into vectors. Swap it for a hosted model without touching the search. */
+export interface EmbeddingProvider {
+  /** Changes whenever the vectors would: part of the index version. */
+  readonly id: string;
+  embed(texts: readonly string[]): Float32Array[];
+}
+
+/** The same, for a provider that has to wait (a hosted embedding API). */
+export interface AsyncEmbeddingProvider {
+  readonly id: string;
+  embed(texts: readonly string[]): Promise<Float32Array[]>;
+}
+
+/** What each piece of a component's search document says about it. */
+export type FieldType = 'name' | 'purpose' | 'signal' | 'useWhen' | 'scenario' | 'action' | 'state' | 'event' | 'data';
+
+/** A component, as search sees it: what problem it solves (positive) and what it is not for (negative). Built from its capability — nothing is written for search alone. */
+export type SearchDocument = {
+  component: string;
+  /** Catalogue order: the stable tie-break. */
+  order: number;
+  positive: { type: FieldType; text: string }[];
+  negative: { text: string }[];
+};
+
+export type SearchWeights = {
+  /** How much each kind of field counts when it is the closest to the query (0 leaves it out). */
+  fields: Record<FieldType, number>;
+  /** The semantic score is the mean of the best `topK` field similarities. */
+  topK: number;
+  /** How hard a query nearer to what a component is *not* for pushes it down. */
+  negative: number;
+  /** Before comparing: subtract the catalogue's mean vector (`mean`), and also its first principal component (`pc`) — what every document shares. */
+  centre: 'none' | 'mean' | 'pc';
+  semantic: number;
+  lexical: number;
+  /** The lexical score saturates: `s / (s + lexicalHalf)`. */
+  lexicalHalf: number;
+  /** Below this final score a component is not a candidate. */
+  minScore: number;
+  /** …nor if it scores below this share of the best one. */
+  relative: number;
+};
+
+export type ScoreBreakdown = {
+  component: string;
+  semantic: number | null;
+  negative: number | null;
+  lexical: number;
+  /** 1 when the component passes the request's filters (kinds), else 0. */
+  metadata: number;
+  /** 1 when the host may use it, else 0. */
+  availability: number;
+  final: number;
+};
+
+export type SearchOptions = {
+  /** Host policy: only these components may be offered. Absent → every approved component. */
+  available?: readonly string[];
+  /** Only components of these kinds. */
+  kinds?: readonly string[];
+};

package/src/agent/search/weights.ts

@@ -0,0 +1,32 @@
+import type { SearchWeights } from './types';
+
+/**
+ * **The ranking weights — measured, not guessed.** Chosen on the dev half of the evaluation set
+ * (`tests/agent/search-eval.ts`) with `tools/search/tune.ts` and a threshold sweep; the test half is
+ * reported, never tuned on. The record of why is in docs/DECISIONS.md §19.
+ *
+ * - Every document field counts; the ones about what a person does with the component (actions,
+ *   states, events, data) a little less than what it is for.
+ * - The semantic score is the mean of the three closest fields, after removing the catalogue mean.
+ * - A query closer to a component's `avoidWhen` than to anything it is for is pushed down by half
+ *   the difference.
+ * - Lexical matching adds up to 0.3 — a confident phrase or name match keeps its place; a shared
+ *   word alone cannot outvote meaning.
+ * - A candidate needs 0.3, and 60% of the best — so an ambiguous request keeps its alternatives and
+ *   a clear one does not trail five weak ones. (Off-topic and on-topic scores overlap; 0.3 rejects
+ *   about half the off-topic requests without losing on-topic ones.)
+ *
+ * Measured and not adopted: word-level alignment, reciprocal rank fusion, hubness (CSLS) correction
+ * and principal-component removal — none beat this on the development data.
+ */
+export const DEFAULT_WEIGHTS: SearchWeights = {
+  fields: { name: 1, purpose: 1, signal: 1, useWhen: 1, scenario: 1, action: 0.8, state: 0.8, event: 0.8, data: 0.8 },
+  topK: 3,
+  negative: 0.5,
+  centre: 'mean',
+  semantic: 1,
+  lexical: 0.3,
+  lexicalHalf: 6,
+  minScore: 0.3,
+  relative: 0.6,
+};

package/src/agent/types.ts

@@ -45,7 +45,7 @@ type Base = {
 };
 
 export type FieldSpec =
-  | Base & { type: 'text'; maxLength?: number; minLength?: number; pattern?: string; patternHint?: string; format?: 'date'; enum?: readonly string[]; unique?: boolean }
+  | Base & { type: 'text'; maxLength?: number; minLength?: number; pattern?: string; patternHint?: string; format?: 'date' | 'color'; enum?: readonly string[]; unique?: boolean }
   | Base & { type: 'number'; integer?: boolean; min?: number; max?: number; exclusiveMin?: number }
   | Base & { type: 'boolean' }
   | Base & { type: 'list'; item: FieldSpec; minItems?: number; maxItems?: number }

package/src/components/catalog.ts

@@ -40,7 +40,9 @@ export type ComponentFamily =
   | 'combobox' | 'tabbed' | 'fallback'
   | 'budget-tracker' | 'ab-tests' | 'conversion-funnel'
   | 'expandable-feed' | 'score-summary' | 'criteria-spider' | 'activity-heatmap' | 'tag-cloud'
-  | 'receipt-printer';
+  | 'receipt-printer'
+  | 'animated-status'
+  | 'send-completion';
 
 /**
  * **A set of families shipped and shown together.** The seven onboarding components (2026-09-24)
@@ -573,6 +575,24 @@ export const COMPONENT_CATALOGUE: ComponentCatalogueEntry[] = [
     playground: { slug: 'new/receipt-printer' },
     note: 'The first New component animated with Rive. The printer and the paper are a Rive file authored as RML with the Rive CLI (rive/receipt-printer/receipt-printer.rml, reference ~/Downloads/printerPDF.pdf) and shipped as base64 (riv.ts, `npm run rive:receipt-printer`); React owns the form, the checks, the print operation and the lifecycle, and talks to Rive only through the `Receipt` view model (ten strings, print/reset/reveal triggers, a status the machine writes). Web: @rive-app/react-canvas. Native: the same receipt as a still. Built to docs/COMPONENT-RULES.md.',
   },
+  {
+    type: 'animated-status', label: 'Animated Status', status: 'implemented', driver: 'configuration-driven', introduced: '2026-09-29', group: 'new', caseStudies: 5,
+    blurb: 'A six-scene animated message in a fixed motion design — give it the words, two colours and an icon; the motion never changes.',
+    fixtureDir: 'onboarding/animated-status',
+    storyId: 'Components/Onboarding/Animated Status',
+    resource: { slug: 'new/animated-status', defaultFixture: 'case1' },
+    playground: { slug: 'new/animated-status' },
+    note: 'Rebuilt from a reference GIF (720×1280, 271 frames at 24 fps) as one Rive file authored as RML with the Rive CLI (rive/animated-status, generated by authoring/generate-rml.mjs) and shipped as base64 (riv.ts, `npm run rive:animated-status`). The config holds only the words (six slots with fixed word limits), textColor, accentColor and emblemIcon; timing, layout and typography have no key, and every text box in the file is fixed and shrinks its type, so no word moves anything. `done` means the animation finished, not the task. Web: @rive-app/react-canvas. Native: a still. Standalone prototype: rive-prototype/. Built to docs/COMPONENT-RULES.md.',
+  },
+  {
+    type: 'send-completion', label: 'Send Completion', status: 'implemented', driver: 'configuration-driven', introduced: '2026-09-29', group: 'new', caseStudies: 5,
+    blurb: 'A send button that launches its icon, balls up into a check and says “Sent!” — once the send has really succeeded.',
+    fixtureDir: 'onboarding/send-completion',
+    storyId: 'Components/Onboarding/Send Completion',
+    resource: { slug: 'new/send-completion', defaultFixture: 'case1' },
+    playground: { slug: 'new/send-completion' },
+    note: 'Rebuilt natively in Rive from a reference GIF (720×540, 120 frames at 24 fps): one master timeline of measured keys cut into a state machine (tap cue → press → launch → wait → transform → sent), authored as RML (rive/send-completion, generated by authoring/generate-rml.mjs) and shipped as base64 (riv.ts, `npm run rive:send-completion`). The plane rides a path (FollowPathConstraint) with a trimmed trail; the button morphs by keyed size and a data-driven corner radius. The config holds the words, six colours, the icon, its scale, the corner radius, the width and the behaviour; the press runs the host `send` operation and the check waits for it. Web: @rive-app/react-canvas. Native: a still. Built to docs/COMPONENT-RULES.md.',
+  },
 ];
 
 /** The most recent `introduced` date among these — what "New" means on the site. */

package/src/components/onboarding/animated-status/AnimatedStage.tsx

@@ -0,0 +1,18 @@
+import { useEffect } from 'react';
+import { AnimatedStill } from './AnimatedStill';
+import type { AnimatedStageProps } from './AnimatedStage.types';
+
+export type { AnimatedStageProps };
+
+/**
+ * **The native half: a still.** The Rive runtime this component plays on the web
+ * (`@rive-app/react-canvas`) is a browser runtime, so it is never imported here. Play lands on
+ * `done` at once; reset returns to `idle`.
+ */
+export function AnimatedStage({ command, onStatus, ...still }: AnimatedStageProps) {
+  useEffect(() => {
+    if (!command) return;
+    onStatus(command.kind === 'reset' ? 'idle' : 'done');
+  }, [command?.n]);
+  return <AnimatedStill {...still} />;
+}

package/src/components/onboarding/animated-status/AnimatedStage.types.ts

@@ -0,0 +1,30 @@
+import type { AnimatedStatusStatus } from './contract';
+import type { AnimatedStatusWords } from './engine';
+
+/**
+ * **The animation — the one boundary between the component and how it is drawn.**
+ *
+ * The component hands over the words, two colours, an icon and a command, and hears back the
+ * playback status. The web half (`AnimatedStage.web.tsx`) plays the Rive file; the native half, and
+ * the web half whenever the Rive runtime cannot load, show a still (`AnimatedStill`) and finish at
+ * once. Nothing about Rive — artboards, view models, triggers — crosses this line.
+ */
+export type AnimatedStageCommand = { kind: 'play' | 'reset' | 'reveal'; n: number };
+
+export type AnimatedStageProps = {
+  words: AnimatedStatusWords;
+  textColor: string;
+  accentColor: string;
+  icon: string;
+  /** The latest command; a new `n` runs it again. */
+  command: AnimatedStageCommand | null;
+  /** Playback moved on: `idle`, `playing` or `done`. */
+  onStatus: (status: AnimatedStatusStatus) => void;
+  /** The animation's accessible name: every word it shows. */
+  label: string;
+  maxWidth: number;
+  testID?: string;
+};
+
+/** The artboard's 9:16. */
+export const STAGE_ASPECT = 720 / 1280;

package/src/components/onboarding/animated-status/AnimatedStage.web.tsx

@@ -0,0 +1,99 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Alignment, Fit, Layout, useRive } from '@rive-app/react-canvas';
+import { Box } from '../../../core';
+import { blockRadii } from '../../../tokens';
+import { ANIMATION_GROUND } from '../../../tokens/stage';
+import type { AnimatedStatusStatus } from './contract';
+import { riveWrites } from './engine';
+import { AnimatedStill } from './AnimatedStill';
+import { ANIMATED_STATUS_RIV } from './riv';
+import { STAGE_ASPECT, type AnimatedStageProps } from './AnimatedStage.types';
+
+export type { AnimatedStageProps };
+
+/**
+ * **The web half: the Rive animation.**
+ *
+ * The Rive file (`rive/animated-status/`) owns the artwork, the six scenes and every frame of
+ * motion. This owns only the conversation with it, through the `AnimatedStatus` view model: the
+ * words, the two colours and the icon index are written whenever they change; `play`, `reset` and
+ * `reveal` are triggers; `status` is written by the file's own state machine (`idle` · `playing` ·
+ * `done`). No word can move anything: every text box in the file is fixed and shrinks its type.
+ *
+ * If the runtime or the file cannot load, the stage shows the still and a play finishes at once.
+ */
+
+const ARTBOARD = 'AnimatedStatus';
+const MACHINE = 'AnimatedStatusMachine';
+
+let bytes: Uint8Array | null = null;
+/** The `.riv`, decoded once per page; each stage gets its own copy of the buffer. */
+function rivBuffer(): ArrayBuffer {
+  if (!bytes) {
+    const bin = atob(ANIMATED_STATUS_RIV);
+    bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  }
+  return bytes.slice().buffer;
+}
+
+type Prop = { value: string | number };
+type Instance = {
+  string(p: string): (Prop & { on(cb: () => void): void; off(cb?: () => void): void; value: string }) | null;
+  number(p: string): Prop | null;
+  color(p: string): Prop | null;
+  trigger(p: string): { trigger(): void } | null;
+};
+
+export function AnimatedStage({ words, textColor, accentColor, icon, command, onStatus, label, maxWidth, testID }: AnimatedStageProps) {
+  const [failed, setFailed] = useState(false);
+  const params = useMemo(() => ({
+    buffer: rivBuffer(),
+    artboard: ARTBOARD,
+    stateMachines: MACHINE,
+    autoplay: true,
+    autoBind: true,
+    layout: new Layout({ fit: Fit.Contain, alignment: Alignment.Center }),
+    onLoadError: () => setFailed(true),
+  }), []);
+  const { rive, RiveComponent } = useRive(params);
+  const heard = useRef(onStatus);
+  heard.current = onStatus;
+  const vm = rive?.viewModelInstance as unknown as Instance | undefined;
+
+  /* 1 · The words and the look, whenever they change — they never restart playback. */
+  useEffect(() => {
+    if (!vm) return;
+    for (const w of riveWrites(words, textColor, accentColor, icon)) {
+      const p = vm[w.kind](w.name);
+      if (p && p.value !== w.value) p.value = w.value;
+    }
+  }, [vm, words, textColor, accentColor, icon]);
+
+  /* 2 · Commands, as triggers. */
+  useEffect(() => {
+    if (!vm || !command) return;
+    vm.trigger(command.kind)?.trigger();
+    rive?.play();
+  }, [vm, command?.n]);
+
+  /* 3 · The file says where playback is. */
+  useEffect(() => {
+    const status = vm?.string('status');
+    if (!status) return;
+    const report = () => heard.current(status.value as AnimatedStatusStatus);
+    status.on(report);
+    return () => status.off(report);
+  }, [vm]);
+
+  /* Without the runtime, a command settles at once, exactly as on native. */
+  useEffect(() => { if (failed && command) heard.current(command.kind === 'reset' ? 'idle' : 'done'); }, [failed, command?.n]);
+
+  if (failed) return <AnimatedStill words={words} textColor={textColor} accentColor={accentColor} label={label} maxWidth={maxWidth} testID={testID} />;
+  return (
+    /* `data-rive` says whether the artboard has painted — a screenshot (the visual gate) waits for `ready`. */
+    <Box testID={testID} role="img" aria-label={label} style={{ width: '100%', maxWidth, aspectRatio: STAGE_ASPECT, borderRadius: blockRadii.mid, overflow: 'hidden', backgroundColor: ANIMATION_GROUND }}>
+      <RiveComponent aria-hidden="true" data-rive={rive ? 'ready' : 'loading'} style={{ width: '100%', height: '100%', display: 'block' }} />
+    </Box>
+  );
+}

package/src/components/onboarding/animated-status/AnimatedStatusView.tsx

@@ -0,0 +1,109 @@
+import { useEffect, useMemo, useRef, useState, type ComponentType } from 'react';
+import { Box, useReduceMotion } from '../../../core';
+import type { DensityName } from '../../../tokens';
+import { fill, resolveConfig, type OnboardingPreset, 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 { ANIMATED_STATUS_PRESETS, ANIMATED_STATUS_SECONDS, validateAnimatedStatus, type AnimatedStatusSettings, type AnimatedStatusStatus } from './contract';
+import { spokenText, wordsOf, type AnimatedStatusSeed } from './engine';
+import { AnimatedStage } from './AnimatedStage';
+import type { AnimatedStageCommand, AnimatedStageProps } from './AnimatedStage.types';
+
+export type AnimatedStatusProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<AnimatedStatusSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  reload?: OnboardingOperation<void>;
+  /** A demo scene's starting point — see `animatedStatusSeed`. */
+  initial?: AnimatedStatusSeed;
+  /** What draws the animation. Default: Rive on the web, a still on native. */
+  stage?: ComponentType<AnimatedStageProps>;
+  /** Playback moved on. `done` means the animation finished — not that the task it describes did. */
+  onStatusChange?: (status: AnimatedStatusStatus) => void;
+  /** Play (or Replay) was pressed. */
+  onPlay?: () => void;
+  /** Reset was pressed. */
+  onReset?: () => void;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/**
+ * **Animated Status** — the animation on a card: the header, the 9:16 stage, a status chip
+ * (Ready · Playing · Played), Play / Replay and Reset. With reduced motion, Play shows the last
+ * frame at once.
+ */
+function AnimatedStatusView(props: AnimatedStatusProps) {
+  const config = resolveConfig(ANIMATED_STATUS_PRESETS, props.preset, props.config);
+  const issues = validateAnimatedStatus(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, stage: Stage = AnimatedStage, onStatusChange, onPlay, onReset, onScene, testID }: Omit<AnimatedStatusProps, 'config'> & { config: AnimatedStatusSettings }) {
+  const pattern = usePatternStatus(status ?? 'ready', reload);
+  const reduceMotion = useReduceMotion();
+  const words = useMemo(() => wordsOf(config), [config.scene1Text, config.scene2Text, config.scene3Text, config.scene4Text, config.scene5Text, config.scene6Text]);
+  const [playback, setPlayback] = useState<AnimatedStatusStatus>('idle');
+  const [command, setCommand] = useState<AnimatedStageCommand | null>(null);
+  const n = useRef(0);
+  const run = (kind: AnimatedStageCommand['kind']) => setCommand({ kind, n: ++n.current });
+
+  /* A scene's seed, or autoplay, starts playback once the card shows. */
+  const seeded = initial?.status ?? (config.autoplay ? 'playing' : 'idle');
+  useEffect(() => {
+    if (seeded === 'playing') run(reduceMotion ? 'reveal' : 'play');
+    else if (seeded === 'done') run('reveal');
+  }, [seeded]);
+
+  const changed = useRef(onStatusChange);
+  changed.current = onStatusChange;
+  const last = useRef<AnimatedStatusStatus>('idle');
+  const heard = (s: AnimatedStatusStatus) => {
+    if (last.current === s) return;
+    last.current = s;
+    setPlayback(s);
+    changed.current?.(s);
+  };
+
+  useSceneReport(pattern.status === 'ready' ? (playback === 'idle' ? 'default' : playback) : pattern.status, onScene);
+
+  const chip = playback === 'playing'
+    ? { tone: 'attention' as const, label: config.playingLabel, dot: true }
+    : playback === 'done' ? { tone: 'success' as const, label: config.doneLabel } : { tone: 'neutral' as const, label: config.idleLabel };
+  return (
+    <OnboardingCard
+      testID={testID}
+      header={config}
+      copy={config}
+      density={density}
+      status={pattern.status}
+      onRetry={pattern.retry}
+      onEmptyAction={pattern.retry}
+      chip={chip}
+      hint={fill(config.hintText, { seconds: ANIMATED_STATUS_SECONDS })}
+      secondary={playback !== 'idle' ? { label: config.resetLabel, onPress: () => { onReset?.(); run('reset'); } } : undefined}
+      primary={{ label: playback === 'idle' ? config.playLabel : config.replayLabel, onPress: () => { onPlay?.(); run(reduceMotion ? 'reveal' : 'play'); } }}>
+      <Box align="center">
+        <Stage
+          words={words}
+          textColor={config.textColor}
+          accentColor={config.accentColor}
+          icon={config.emblemIcon}
+          command={command}
+          onStatus={heard}
+          label={spokenText(words)}
+          maxWidth={300}
+          testID={testID ? `${testID}-stage` : undefined}
+        />
+      </Box>
+    </OnboardingCard>
+  );
+}
+
+/** Animated Status, guarded: a wrong-kind config is refused by name and a render error is caught (`shared/guard`). */
+export const AnimatedStatus = guarded(AnimatedStatusView, ANIMATED_STATUS_PRESETS, 'AnimatedStatus');

package/src/components/onboarding/animated-status/AnimatedStill.tsx

@@ -0,0 +1,23 @@
+import { Box, Text } from '../../../core';
+import { blockRadii } from '../../../tokens';
+import { ANIMATION_GROUND } from '../../../tokens/stage';
+import { cssColor } from './engine';
+import { STAGE_ASPECT, type AnimatedStageProps } from './AnimatedStage.types';
+
+/**
+ * **The animation as a still** — native, and the web when the Rive runtime cannot load: the opening
+ * word and the call to action on the white ground, the sign-off on an accent rule. Same words and
+ * colours; no motion.
+ */
+export function AnimatedStill({ words, textColor, accentColor, label, maxWidth, testID }: Pick<AnimatedStageProps, 'words' | 'textColor' | 'accentColor' | 'label' | 'maxWidth' | 'testID'>) {
+  const ink = cssColor(textColor);
+  return (
+    <Box testID={testID} role="img" aria-label={label}
+      style={{ width: '100%', maxWidth, aspectRatio: STAGE_ASPECT, borderRadius: blockRadii.mid, overflow: 'hidden', backgroundColor: ANIMATION_GROUND, alignItems: 'center', justifyContent: 'center', gap: 18, padding: 16 }}>
+      <Text numberOfLines={1} style={{ fontSize: 44, fontWeight: '800', color: ink }}>{words.scene1Text}</Text>
+      <Text numberOfLines={1} style={{ fontSize: 18, fontWeight: '700', color: ink }}>{words.scene5Text}</Text>
+      <Box style={{ width: 96, height: 3, backgroundColor: cssColor(accentColor) }} />
+      <Text numberOfLines={1} style={{ fontSize: 11, color: ink, opacity: 0.7 }}>{words.scene6Text}</Text>
+    </Box>
+  );
+}

package/src/components/onboarding/animated-status/contract.ts

@@ -0,0 +1,105 @@
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import { COLOR_TOKENS, parseColor } from '../shared/configColor';
+import presetsJson from './presets.json';
+
+/**
+ * **Animated Status** — a short animated message in a fixed motion design (Rive,
+ * `rive/animated-status/`): six scenes, from an opening word a square bounces across to a dark end
+ * card with an icon. The config gives the words, two colours and the icon; the motion, layout,
+ * typography and timing are the component's and have no key.
+ *
+ * Every word slot has its own word limit, part of the design: over it, the config is refused with
+ * the reason — never cut short. A longer word shrinks inside its fixed box in the animation, so no
+ * text can move anything. `done` means the animation finished playing — not that the task the
+ * words describe is done; the host owns that.
+ */
+
+export const ANIMATED_STATUS_SCENES = ['default', 'playing', 'done', 'loading', 'empty', 'error'] as const;
+export type AnimatedStatusScene = (typeof ANIMATED_STATUS_SCENES)[number];
+export const ANIMATED_STATUS_IN_FLIGHT: readonly string[] = [];
+
+/** The emblem's icons, in the order the Rive file holds their artwork. */
+export const ANIMATED_STATUS_ICONS = ['search', 'location', 'document', 'calendar', 'check', 'sparkles', 'loader', 'warning'] as const;
+export type AnimatedStatusIcon = (typeof ANIMATED_STATUS_ICONS)[number];
+
+export type AnimatedStatusSlot = 'scene1Text' | 'scene2Text' | 'scene3Text' | 'scene4Text' | 'scene5Text' | 'scene6Text';
+/** Each slot's limits: words `[min, max]`, characters, and characters per word. */
+export const ANIMATED_STATUS_SLOTS: Record<AnimatedStatusSlot, { words: [number, number]; maxChars: number; maxWordChars?: number; shows: string }> = {
+  scene1Text: { words: [1, 1], maxChars: 12, shows: 'the opening word; a square bounces across it and fills it in' },
+  scene2Text: { words: [1, 1], maxChars: 12, shows: 'one word, stacked up the screen five times' },
+  scene3Text: { words: [6, 6], maxChars: 44, maxWordChars: 11, shows: 'six words, one per line, each larger; the fifth is emphasised' },
+  scene4Text: { words: [3, 3], maxChars: 20, maxWordChars: 6, shows: 'three words as hard cuts; a full stop follows the third' },
+  scene5Text: { words: [1, 3], maxChars: 22, shows: 'the call to action' },
+  scene6Text: { words: [1, 3], maxChars: 36, shows: 'the sign-off on the dark end card' },
+};
+export const ANIMATED_STATUS_SLOT_KEYS = Object.keys(ANIMATED_STATUS_SLOTS) as AnimatedStatusSlot[];
+
+export type AnimatedStatusStatus = 'idle' | 'playing' | 'done';
+
+/** Every word the card shows around the animation. */
+export type AnimatedStatusCopy = {
+  playLabel: string;
+  replayLabel: string;
+  resetLabel: string;
+  /** The status chip: before, during and after playback. */
+  idleLabel: string;
+  playingLabel: string;
+  doneLabel: string;
+  /** Under the animation: "Plays once · {seconds} s". */
+  hintText: string;
+};
+
+export type AnimatedStatusSettings = HeaderConfig & LoadCopy & AnimatedStatusCopy & Record<AnimatedStatusSlot, string> & {
+  /** Colour of every word on the white scenes, the square and the dots. Hex, rgb(), rgba() or a hue token. */
+  textColor: string;
+  /** Colour of the end card: the emblem, the rule and the glow. */
+  accentColor: string;
+  /** The emblem's icon — one of `ANIMATED_STATUS_ICONS`. */
+  emblemIcon: string;
+  /** Play as soon as it shows. Default false: the card waits for Play. */
+  autoplay?: boolean;
+  ship?: string;
+};
+
+export const ANIMATED_STATUS_PRESETS = presetsJson as unknown as PresetsFile<AnimatedStatusSettings>;
+/** How long one playthrough takes: 271 frames at 24 fps. */
+export const ANIMATED_STATUS_SECONDS = 11.3;
+
+/* Colours are content here: see `shared/configColor`. */
+export { COLOR_TOKENS, parseColor, type Rgba } from '../shared/configColor';
+
+/* ─── validation ──────────────────────────────────────────────────────────────────────────── */
+
+const words = (s: string) => s.trim().split(/\s+/).filter(Boolean);
+const plural = (n: number, one: string) => `${n} ${one}${n === 1 ? '' : 's'}`;
+
+/**
+ * The config's problems, each with its field. Text over a limit is refused and says which limit;
+ * it is never shortened. Never throws, whatever it is given.
+ */
+export function validateAnimatedStatus(c: AnimatedStatusSettings): OnboardingIssue[] {
+  const issues: OnboardingIssue[] = [];
+  for (const key of ANIMATED_STATUS_SLOT_KEYS) {
+    const rule = ANIMATED_STATUS_SLOTS[key];
+    const text = c?.[key];
+    if (typeof text !== 'string' || !text.trim()) { issues.push({ path: key, message: `${key} needs text: ${rule.shows}.` }); continue; }
+    if ([...text].some(ch => ch.charCodeAt(0) < 32 || ch.charCodeAt(0) === 127)) { issues.push({ path: key, message: `${key} is one line of plain text.` }); continue; }
+    const ws = words(text);
+    const [min, max] = rule.words;
+    const exact = min === max;
+    if (ws.length > max) issues.push({ path: key, message: `${key} takes ${exact ? 'exactly' : 'at most'} ${plural(max, 'word')} (${rule.shows}); it has ${ws.length}.` });
+    else if (ws.length < min) issues.push({ path: key, message: `${key} takes ${exact ? 'exactly' : 'at least'} ${plural(min, 'word')} (${rule.shows}); it has ${ws.length}.` });
+    if (text.trim().length > rule.maxChars) issues.push({ path: key, message: `${key} takes at most ${rule.maxChars} characters; it has ${text.trim().length}.` });
+    const long = rule.maxWordChars ? ws.filter(w => w.length > rule.maxWordChars!) : [];
+    if (long.length) issues.push({ path: key, message: `Each word of ${key} is at most ${rule.maxWordChars} characters: ${long.join(', ')} is too long.` });
+  }
+  for (const key of ['textColor', 'accentColor'] as const) {
+    // eslint-disable-next-line comppack/no-raw-colour -- the message names the colour formats the config may supply
+    if (!parseColor(c?.[key])) issues.push({ path: key, message: `${key} is a colour: #RGB, #RRGGBB, #RRGGBBAA, rgb(), rgba() or a hue token (${Object.keys(COLOR_TOKENS).slice(0, 4).join(', ')}…).` });
+  }
+  if (!(ANIMATED_STATUS_ICONS as readonly string[]).includes(c?.emblemIcon as string)) {
+    issues.push({ path: 'emblemIcon', message: `emblemIcon is one of ${ANIMATED_STATUS_ICONS.join(', ')}.` });
+  }
+  if (c?.autoplay !== undefined && typeof c.autoplay !== 'boolean') issues.push({ path: 'autoplay', message: 'autoplay is yes or no.' });
+  return issues;
+}

package/src/components/onboarding/animated-status/engine.ts

@@ -0,0 +1,49 @@
+import {
+  ANIMATED_STATUS_ICONS, ANIMATED_STATUS_SLOT_KEYS,
+  type AnimatedStatusScene, type AnimatedStatusSettings, type AnimatedStatusStatus,
+} from './contract';
+import { argb } from '../shared/configColor';
+
+export { cssColor } from '../shared/configColor';
+
+/** A demo scene's starting point: where playback is when the card shows. */
+export type AnimatedStatusSeed = { status: AnimatedStatusStatus };
+
+export function animatedStatusSeed(_config: AnimatedStatusSettings, scene: AnimatedStatusScene | string): AnimatedStatusSeed {
+  return { status: scene === 'playing' ? 'playing' : scene === 'done' ? 'done' : 'idle' };
+}
+
+/** The config's words, as the animation shows them. */
+export type AnimatedStatusWords = Record<(typeof ANIMATED_STATUS_SLOT_KEYS)[number], string>;
+export const wordsOf = (c: AnimatedStatusSettings): AnimatedStatusWords =>
+  Object.fromEntries(ANIMATED_STATUS_SLOT_KEYS.map(k => [k, c[k].trim().split(/\s+/).join(' ')])) as AnimatedStatusWords;
+
+/** Everything the animation says, in order — its accessible name (a canvas has no text of its own). */
+export function spokenText(w: AnimatedStatusWords): string {
+  return [w.scene1Text, w.scene2Text, w.scene3Text, `${w.scene4Text}.`, w.scene5Text, w.scene6Text].join(' · ');
+}
+
+
+export type RiveWrite = { kind: 'string' | 'color' | 'number'; name: string; value: string | number };
+
+/**
+ * **The words and appearance as the Rive file's view model takes them.** The one place its names
+ * appear: scene 3's words go one per line (`scene3Line1–6`), scene 4's one per cut
+ * (`scene4Word1–3`), and the icon by its index in the file (`iconIndex`).
+ */
+export function riveWrites(w: AnimatedStatusWords, textColor: string, accentColor: string, icon: string): RiveWrite[] {
+  const s3 = w.scene3Text.split(' ');
+  const s4 = w.scene4Text.split(' ');
+  return [
+    { kind: 'string', name: 'scene1Text', value: w.scene1Text },
+    { kind: 'string', name: 'scene2Text', value: w.scene2Text },
+    ...s3.map((v, i): RiveWrite => ({ kind: 'string', name: `scene3Line${i + 1}`, value: v })),
+    ...s4.map((v, i): RiveWrite => ({ kind: 'string', name: `scene4Word${i + 1}`, value: v })),
+    { kind: 'string', name: 'scene5Text', value: w.scene5Text },
+    { kind: 'string', name: 'scene6Text', value: w.scene6Text },
+    { kind: 'color', name: 'textColor', value: argb(textColor) },
+    { kind: 'color', name: 'accentColor', value: argb(accentColor) },
+    { kind: 'number', name: 'iconIndex', value: Math.max(0, (ANIMATED_STATUS_ICONS as readonly string[]).indexOf(icon)) },
+  ];
+}
+

package/src/components/onboarding/animated-status/index.ts

@@ -0,0 +1,8 @@
+export {
+  ANIMATED_STATUS_ICONS, ANIMATED_STATUS_IN_FLIGHT, ANIMATED_STATUS_PRESETS, ANIMATED_STATUS_SCENES, ANIMATED_STATUS_SECONDS, ANIMATED_STATUS_SLOTS,
+  COLOR_TOKENS as ANIMATED_STATUS_COLOR_TOKENS, parseColor as parseAnimatedStatusColor, validateAnimatedStatus,
+  type AnimatedStatusIcon, type AnimatedStatusScene, type AnimatedStatusSettings, type AnimatedStatusStatus,
+} from './contract';
+export { animatedStatusSeed, riveWrites as animatedStatusRiveWrites, spokenText as animatedStatusSpokenText, type AnimatedStatusSeed } from './engine';
+export { AnimatedStatus, type AnimatedStatusProps } from './AnimatedStatusView';
+export type { AnimatedStageProps, AnimatedStageCommand } from './AnimatedStage.types';