@appinternalleads/ui 0.4.0 → 0.4.1

package/src/agent/manifests.ts

@@ -5,6 +5,8 @@ import { FIELD_KEY, RECEIPT_MAX_AMOUNT, RECEIPT_MAX_FIELDS, RECEIPT_MAX_ITEMS, R
 import { HEATMAP_REVEALS } from '../components/onboarding/activity-heatmap/contract';
 import { FEED_BLOCK_KINDS } from '../components/onboarding/expandable-feed/contract';
 import { MAX_SLIDES } from '../components/onboarding/carousel/contract';
+import { SEND_COMPLETION_ICONS, SEND_COMPLETION_LIMITS } from '../components/onboarding/send-completion/contract';
+import { COLOR_FORMATS, COLOR_HINT, COLOR_PATTERN } from '../components/onboarding/shared/configColor';
 import { bool, json, list, map, num, obj, text } from './spec';
 import type { AgentCapability, CapabilityAction, CapabilityCard, CapabilityEvent, CopySpec, FieldSpec } from './types';
 
@@ -531,4 +533,84 @@ const completion: NewManifest = {
   system: ['partialStats', 'successStats', 'partialItems', 'successItems', 'demoSkipped', 'ship'],
 };
 
-export const NEW_MANIFESTS: readonly NewManifest[] = [receiptPrinter, budgetTracker, activityHeatmap, criteriaSpider, expandableFeed, fallback, seatAllocation, carousel, completion];
+const colour = (c: OnboardingComponent, key: string, what: string) =>
+  text(`${what} A colour: ${COLOR_FORMATS}.`, {
+    format: 'color', pattern: COLOR_PATTERN.source, patternHint: COLOR_HINT, default: base(c)[key], owners: ['agent', 'builder', 'developer'],
+  });
+const sendCompletion: NewManifest = {
+  family: 'new',
+  component: 'send-completion',
+  name: 'Send Completion',
+  kind: 'interactive',
+  purpose: 'A single send button that shows the send happening: pressed, its icon launches, the button becomes a check, and a pill confirms ("Sent!") — once the host\'s send has really succeeded.',
+  signals: ['send button', 'sent', 'submit', 'submitted', 'send button', 'confirm', 'upload', 'save', 'message sent', 'done button', 'send animation', 'success animation'],
+  useWhen: [
+    'One action the person triggers — send, submit, upload, confirm, save — whose success should be shown as it happens.',
+    'The host can run the action (the send operation) and say whether it succeeded.',
+  ],
+  avoidWhen: [
+    'A form with fields to fill — this is the one button, not the form.',
+    'Making a receipt, invoice or document to send someone — that is the document\'s own component; this is only the button that sends.',
+    'Several steps or a summary of what was set up — use completion.',
+    'Progress over time (percent, many items) — the circle only waits, it does not count.',
+  ],
+  related: [
+    { component: 'completion', distinction: 'Completion summarises a finished flow; Send Completion is the one press that finishes it.' },
+  ],
+  states: [
+    { state: 'idle', description: 'The button, ready; the tap cue shows first when behavior.showTapCue.' },
+    { state: 'sending', description: 'Pressed: the host\'s send runs while the icon flies; the circle waits (breathing) for it.' },
+    { state: 'sent', description: 'The send succeeded: the check and the completed label. This is the task\'s result, not just the animation\'s end.' },
+    { state: 'failed', description: 'The send failed: the button returns and an alert says why; pressing again retries.' },
+    ...LOAD_STATES,
+  ],
+  actions: [
+    { id: 'send', description: 'The person presses the button (or Enter / Space on it). Runs the host\'s send operation.', hostOperation: true },
+    { id: 'reset', description: 'Brings the button back, after sent or failed.' },
+  ],
+  events: [
+    { event: 'sendStarted', description: 'The person pressed the button; the send is running.', data: '{}' },
+    { event: 'sent', description: 'The send succeeded and "Sent!" is showing.', data: '{}' },
+    { event: 'reset', description: 'The person pressed Reset.', data: '{}' },
+    { event: 'statusChanged', description: 'Playback moved on.', data: '{ status: "idle" | "pressed" | "launching" | "transforming" | "sent" }' },
+  ],
+  requiresInput: false,
+  rules: [
+    'data.label is what the button does (Send, Submit, Upload…); data.completedLabel what it says when done (Sent!, Submitted!…). Each at most 3 words and 16 characters: longer text shrinks inside the fixed button.',
+    'The motion, its timing and the layout are fixed: there are no keys for them.',
+    '"sent" is reported only after the host\'s send operation succeeds; a failure never shows the check.',
+    'behavior.loop is decorative: it replays forever and never calls the host\'s send.',
+  ],
+  askFor: {
+    label: 'What does the button do — Send, Submit, Upload, Save?',
+  },
+  data: {
+    label: text('What the button says: the action (Send, Submit, Upload, Confirm, Save…).', { required: true, maxLength: SEND_COMPLETION_LIMITS.label.chars, origin: 'invent' }),
+    completedLabel: text('What the pill says once it is done (Sent!, Submitted!, Uploaded…).', { required: true, maxLength: SEND_COMPLETION_LIMITS.completedLabel.chars, origin: 'invent' }),
+  },
+  behavior: {
+    showTapCue: bool('Show "TAP/CLICK" and a fingertip before the press.', { default: base('send-completion').showTapCue, owners: ['agent', 'builder', 'developer'] }),
+    autoplay: bool('Press on its own as soon as it shows (and run the send).', { default: false, owners: ['agent', 'builder', 'developer'] }),
+    loop: bool('Replay forever as a decoration; the host\'s send is never called.', { default: false, owners: ['agent', 'builder', 'developer'] }),
+  },
+  presentation: {
+    ...presentation('send-completion'),
+    backgroundColor: colour('send-completion', 'backgroundColor', 'Behind everything.'),
+    buttonColor: colour('send-completion', 'buttonColor', 'The button, the circle and the pill.'),
+    textColor: colour('send-completion', 'textColor', 'The button\'s label.'),
+    iconColor: colour('send-completion', 'iconColor', 'The icon while it sits in the button.'),
+    completionColor: colour('send-completion', 'completionColor', 'The check and the completed label.'),
+    trailColor: colour('send-completion', 'trailColor', 'The icon in flight, its trail and the tap cue.'),
+    sendIcon: text('The icon the button carries and launches.', { enum: SEND_COMPLETION_ICONS, default: base('send-completion').sendIcon, owners: ['agent', 'builder', 'developer'] }),
+    iconScale: num('The icon\'s size (1 is the design\'s).', { min: SEND_COMPLETION_LIMITS.iconScale[0], max: SEND_COMPLETION_LIMITS.iconScale[1], default: 1, owners: ['agent', 'builder', 'developer'] }),
+    cornerRadius: num('The button\'s corner radius, in points.', { min: SEND_COMPLETION_LIMITS.cornerRadius[0], max: SEND_COMPLETION_LIMITS.cornerRadius[1], default: base('send-completion').cornerRadius, owners: ['agent', 'builder', 'developer'] }),
+    width: num('The animation\'s widest, in points; it keeps 4:3 and shrinks with its container.', { min: SEND_COMPLETION_LIMITS.width[0], max: SEND_COMPLETION_LIMITS.width[1], default: base('send-completion').width, owners: ['agent', 'builder', 'developer'] }),
+  },
+  system: ['ship'],
+  copyExtra: {
+    ...HEADER,
+    tapHint: { maxLength: SEND_COMPLETION_LIMITS.tapHint.chars },
+  },
+};
+
+export const NEW_MANIFESTS: readonly NewManifest[] = [receiptPrinter, budgetTracker, activityHeatmap, criteriaSpider, expandableFeed, fallback, seatAllocation, carousel, completion, sendCompletion];

package/src/agent/result.ts

@@ -40,6 +40,12 @@ export const RESULT_EVENTS: Record<string, Record<string, [string, Mapper]>> = {
     onContinue: ['continued', (() => ({})) as Mapper],
     onFinishLater: ['finishLater', (() => ({})) as Mapper],
   },
+  'send-completion': {
+    onSend: ['sendStarted', (() => ({})) as Mapper],
+    onSent: ['sent', (() => ({})) as Mapper],
+    onReset: ['reset', (() => ({})) as Mapper],
+    onStatusChange: ['statusChanged', ((status: string) => ({ status })) as Mapper],
+  },
   directory: { onSelect: ['selected', ((id: string) => ({ id })) as Mapper] },
   checklist: { onChange: ['changed', ((checklist: unknown, change: unknown) => ({ checklist, change })) as Mapper] },
   'threshold-flow': {

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';