@appinternalleads/ui 0.3.0 → 0.4.1

package/src/components/onboarding/presets.ts

@@ -46,6 +46,8 @@ import { SPIDER_PRESETS, validateSpider } from './criteria-spider/contract';
 import { HEATMAP_PRESETS, validateHeatmap } from './activity-heatmap/contract';
 import { TAG_CLOUD_PRESETS, validateTagCloud } from './tag-cloud/contract';
 import { RECEIPT_PRINTER_PRESETS, validateReceiptPrinter } from './receipt-printer/contract';
+import { ANIMATED_STATUS_PRESETS, validateAnimatedStatus } from './animated-status/contract';
+import { SEND_COMPLETION_PRESETS, validateSendCompletion } from './send-completion/contract';
 import { validateAchievement } from './achievement/contract';
 import { validateBrandKit } from './brand-kit/contract';
 import { validateBudget } from './budget-allocation/contract';
@@ -143,6 +145,8 @@ export const ONBOARDING_PRESETS: Record<OnboardingComponent, PresetsFile<object>
   'activity-heatmap': HEATMAP_PRESETS,
   'tag-cloud': TAG_CLOUD_PRESETS,
   'receipt-printer': RECEIPT_PRINTER_PRESETS,
+  'animated-status': ANIMATED_STATUS_PRESETS,
+  'send-completion': SEND_COMPLETION_PRESETS,
 };
 
 /**
@@ -199,6 +203,8 @@ const RAW_VALIDATORS = {
   'activity-heatmap': validateHeatmap,
   'tag-cloud': validateTagCloud,
   'receipt-printer': validateReceiptPrinter,
+  'animated-status': validateAnimatedStatus,
+  'send-completion': validateSendCompletion,
 } as unknown as Record<OnboardingComponent, (config: Record<string, unknown>) => OnboardingIssue[]>;
 
 /* A validator is public API — an agent or a route calls it with anything. It never throws (R2): a

package/src/components/onboarding/receipt-printer/ReceiptStage.tsx

@@ -1,15 +1,54 @@
-import { useEffect } from 'react';
+import { useEffect, type ComponentType } from 'react';
+import { createRiveReceiptStage, type RiveRuntime } from '../../../native/riveReceiptStageFactory';
 import { ReceiptPaper } from './ReceiptPaper';
 import type { ReceiptStageProps } from './ReceiptStage.types';
 
 export type { ReceiptStageProps };
 
-/**
- * **The native half: the receipt as a still.** The Rive runtime this component animates with on
- * the web (`@rive-app/react-canvas`) is a browser runtime, so it is never imported here — native
- * apps resolve this file and bundle none of it. A print lands at rest at once.
- */
-export function ReceiptStage({ lines, job, phase, onPrinted, label, maxWidth, testID }: ReceiptStageProps) {
+/** The receipt as a still. A print lands at rest at once. */
+function StillReceiptStage({ lines, job, phase, onPrinted, label, maxWidth, testID }: ReceiptStageProps) {
   useEffect(() => { if (phase === 'printing') onPrinted(job); }, [phase, job]);
   return <ReceiptPaper lines={lines} phase={phase} maxWidth={maxWidth} label={label} testID={testID} />;
 }
+
+/**
+ * **The native half: the Rive printer when the app has the runtime, the still when it does not.**
+ *
+ * The product call (29 Sep 2026): React Native should print the way the web does, not show a
+ * still, by default. The Rive runtime (`@rive-app/react-native`, with `react-native-nitro-modules`
+ * and a `pod install`) is still NOT something every app must install. A static import here would
+ * make Metro resolve it on the first import of anything from this package, and an app without it
+ * would red-screen with `Unable to resolve module`. That already happened once with the slider's
+ * peer (`tests/peers.test.ts`).
+ *
+ * So the runtime is loaded with a `require` inside `try`. React Native's Metro config
+ * (`@react-native/metro-config`) sets `allowOptionalDependencies: true`, so a `require` in a `try`
+ * that cannot be resolved is left out of the bundle instead of failing it. At run time it throws
+ * and the still is drawn. If the runtime is installed but its native half is not linked, the Rive
+ * stage itself falls back to the still when the file cannot load.
+ *
+ * The specifier must stay a string literal inside the `try`: that is what Metro recognises as
+ * optional. The Rive stage (`native/riveReceiptStageFactory.tsx`) is imported normally. It takes the
+ * runtime as an argument and names it only in `import type`, which is erased, so importing it
+ * resolves nothing native. It does bring the `.riv` bytes (about 280 kB) into every React Native
+ * bundle, as they already are on the web.
+ */
+function loadRiveRuntime(): unknown {
+  try {
+    // @ts-ignore -- `require` is typed only when Node's types are loaded; Metro provides it at run time.
+    return require('@rive-app/react-native');
+  } catch {
+    return null;
+  }
+}
+
+/** The stage for a runtime, or the still without one. Exported for tests; apps use `ReceiptStage`. */
+export function nativeReceiptStageFor(runtime: unknown): ComponentType<ReceiptStageProps> {
+  return runtime ? createRiveReceiptStage(runtime as RiveRuntime) : StillReceiptStage;
+}
+
+const Stage = nativeReceiptStageFor(loadRiveRuntime());
+
+export function ReceiptStage(props: ReceiptStageProps) {
+  return <Stage {...props} />;
+}

package/src/components/onboarding/send-completion/SendCompletionView.tsx

@@ -0,0 +1,164 @@
+import { useEffect, useRef, useState, type ComponentType } from 'react';
+import { Box, useReduceMotion } from '../../../core';
+import { Callout } from '../../../ds';
+import type { DensityName } from '../../../tokens';
+import { useOperationRunner } from '../../../runtime/operations';
+import { fill, resolveConfig, type OnboardingPreset, type OnboardingResult, type PatternStatus } from '../shared/contract';
+import { ONBOARDING_TIMING, type OnboardingOperation } from '../shared/mock';
+import { InvalidConfig } from '../shared/InvalidConfig';
+import { OnboardingCard } from '../shared/OnboardingCard';
+import { Hidden } from '../shared/parts';
+import { runOutcome, useDefaultOperation, usePatternStatus, useSceneReport } from '../shared/runtime';
+import { guarded } from '../shared/guard';
+import { SEND_COMPLETION_PRESETS, validateSendCompletion, type SendCompletionSettings, type SendCompletionStatus } from './contract';
+import type { SendCompletionSeed, SendPhase } from './engine';
+import { SendStage } from './SendStage';
+import type { SendStageCommand, SendStageProps } from './SendStage.types';
+
+export type SendCompletionOperations = {
+  /**
+   * Do the send for real — a message, a form, an upload. The button launches while it runs and the
+   * check is drawn only once it succeeds; a failure returns the button and says so. Default:
+   * succeeds after 900 ms (or fails, with `result="error"`).
+   */
+  send?: OnboardingOperation<{ label: string }>;
+};
+
+export type SendCompletionProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<SendCompletionSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  /** Demo: `error` makes the default send fail. */
+  result?: OnboardingResult;
+  operations?: SendCompletionOperations;
+  reload?: OnboardingOperation<void>;
+  /** A demo scene's starting point — see `sendCompletionSeed`. */
+  initial?: SendCompletionSeed;
+  /** What draws the animation. Default: Rive on the web, a still on native. */
+  stage?: ComponentType<SendStageProps>;
+  /** The button was pressed and the send started. */
+  onSend?: () => void;
+  /** The send succeeded and the animation reached "Sent!". */
+  onSent?: () => void;
+  /** Reset was pressed. */
+  onReset?: () => void;
+  /** Playback moved on: idle · pressed · launching · transforming · sent. */
+  onStatusChange?: (status: SendCompletionStatus) => void;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/**
+ * **Send Completion** — the animation on a card. The animated button is the control: press it
+ * (or Enter / Space on it) and the host's `send` runs while the icon flies; the check draws once it
+ * has succeeded. Reset brings the button back. With reduced motion a successful send lands on the
+ * finished frame.
+ */
+function SendCompletionView(props: SendCompletionProps) {
+  const config = resolveConfig(SEND_COMPLETION_PRESETS, props.preset, props.config);
+  const issues = validateSendCompletion(config);
+  if (issues.length) return <InvalidConfig title={config.title} issues={issues} testID={props.testID} />;
+  return <Valid {...props} config={config} />;
+}
+
+function Valid({
+  config, density, status, result, operations, reload, initial, stage: Stage = SendStage, onSend, onSent, onReset, onStatusChange, onScene, testID,
+}: Omit<SendCompletionProps, 'config'> & { config: SendCompletionSettings }) {
+  const pattern = usePatternStatus(status ?? 'ready', reload);
+  const reduceMotion = useReduceMotion();
+  const runner = useOperationRunner();
+  const send = useDefaultOperation(operations?.send, ONBOARDING_TIMING.send, () => result === 'error');
+
+  const [phase, setPhase] = useState<SendPhase>('idle');
+  const [message, setMessage] = useState<string | undefined>();
+  const [delivered, setDelivered] = useState(true);
+  const [command, setCommand] = useState<SendStageCommand | null>(null);
+  const n = useRef(0);
+  const run = (kind: SendStageCommand['kind']) => setCommand({ kind, n: ++n.current });
+  const phaseRef = useRef(phase);
+  phaseRef.current = phase;
+
+  const start = () => {
+    if (phaseRef.current === 'sending' || phaseRef.current === 'sent') return;
+    setMessage(undefined);
+    if (config.loop) { setDelivered(true); run('send'); return; } // decorative: nothing is sent
+    setPhase('sending');
+    onSend?.();
+    setDelivered(false);
+    /* With reduced motion nothing flies: the finished frame appears once the send has succeeded. */
+    if (!reduceMotion) run('send');
+    runOutcome(runner, 'send', send, { label: config.label }, {
+      ok: () => { setDelivered(true); if (reduceMotion) run('reveal'); },
+      fail: (m) => { setPhase('failed'); setMessage(m); setDelivered(true); run('reset'); },
+    });
+  };
+  const reset = () => {
+    runner.cancel('send');
+    setPhase('idle');
+    setMessage(undefined);
+    setDelivered(true);
+    run('reset');
+    onReset?.();
+  };
+
+  /* A scene's seed, or autoplay / loop, starts things once the card shows. */
+  useEffect(() => {
+    const seed = initial?.phase ?? (config.autoplay || config.loop ? 'sending' : 'idle');
+    if (seed === 'sending') start();
+    else if (seed === 'sent') { setPhase('sent'); run('reveal'); }
+    else if (seed === 'failed') { setPhase('failed'); }
+    return () => runner.cancel('send');
+  }, [initial?.phase, config.autoplay, config.loop]);
+
+  const changed = useRef(onStatusChange);
+  changed.current = onStatusChange;
+  const last = useRef<SendCompletionStatus>('idle');
+  const heard = (s: SendCompletionStatus) => {
+    if (last.current === s) return;
+    last.current = s;
+    changed.current?.(s);
+    if (s === 'sent' && phaseRef.current === 'sending') { setPhase('sent'); onSent?.(); }
+    if (s === 'idle' && config.loop) setPhase('idle');
+  };
+
+  useSceneReport(pattern.status === 'ready' ? (phase === 'idle' ? 'default' : phase) : pattern.status, onScene);
+  const chip = phase === 'sending'
+    ? { tone: 'attention' as const, label: config.sendingChip, dot: true }
+    : phase === 'sent' ? { tone: 'success' as const, label: config.sentChip } : { tone: 'neutral' as const, label: config.idleChip };
+
+  return (
+    <OnboardingCard
+      testID={testID}
+      header={config}
+      copy={config}
+      density={density}
+      status={pattern.status}
+      onRetry={pattern.retry}
+      onEmptyAction={pattern.retry}
+      chip={chip}
+      secondary={phase === 'sent' || phase === 'failed' || (config.loop && phase !== 'idle') ? { label: config.resetLabel, onPress: reset } : undefined}>
+      <Box gap="s3" align="center">
+        <Box style={{ width: '100%', maxWidth: config.width }}>
+          <Stage
+            config={config}
+            delivered={delivered}
+            command={command}
+            onStatus={heard}
+            onPress={start}
+            pressDisabled={phase === 'sending' || phase === 'sent'}
+            label={phase === 'sent' ? config.completedLabel : config.label}
+            testID={testID ? `${testID}-stage` : undefined}
+          />
+        </Box>
+        {phase === 'failed' ? <Box style={{ alignSelf: 'stretch' }}><Callout alert title={config.failTitle}>{message || config.failBody}</Callout></Box> : null}
+        <Box role="status" aria-live="polite">
+          {phase === 'sent' ? <Hidden>{fill(config.doneAnnouncement, { completedLabel: config.completedLabel })}</Hidden> : null}
+        </Box>
+      </Box>
+    </OnboardingCard>
+  );
+}
+
+/** Send Completion, guarded: a wrong-kind config is refused by name and a render error is caught (`shared/guard`). */
+export const SendCompletion = guarded(SendCompletionView, SEND_COMPLETION_PRESETS, 'SendCompletion');

package/src/components/onboarding/send-completion/SendStage.tsx

@@ -0,0 +1,27 @@
+import { useEffect, useState } from 'react';
+import { Pressable } from '../../../core';
+import { SendStill } from './SendStill';
+import type { SendStageProps } from './SendStage.types';
+
+export type { SendStageProps };
+
+/**
+ * **The native half: a still.** The Rive runtime this component plays on the web is a browser
+ * runtime, so it is never imported here. A send lands on `sent` as soon as the host says it is
+ * delivered; reset returns to `idle`.
+ */
+export function SendStage({ config, delivered, command, onStatus, onPress, pressDisabled, label, testID }: SendStageProps) {
+  const [sent, setSent] = useState(false);
+  useEffect(() => {
+    if (!command) return;
+    if (command.kind === 'reset') { setSent(false); onStatus('idle'); return; }
+    if (command.kind === 'reveal') { setSent(true); onStatus('sent'); return; }
+    onStatus('launching');
+  }, [command?.n]);
+  useEffect(() => { if (delivered && command?.kind === 'send' && !sent) { setSent(true); onStatus('sent'); } }, [delivered, command?.n]);
+  return (
+    <Pressable role="button" aria-label={label} onPress={pressDisabled ? undefined : onPress} testID={testID}>
+      <SendStill config={config} sent={sent} />
+    </Pressable>
+  );
+}

package/src/components/onboarding/send-completion/SendStage.types.ts

@@ -0,0 +1,32 @@
+import type { SendCompletionSettings, SendCompletionStatus } from './contract';
+
+/**
+ * **The animation — the one boundary between the component and how it is drawn.**
+ *
+ * The component hands over the config, whether the host's send has succeeded (`delivered`) and a
+ * command, and hears back the playback status and presses. The web half (`SendStage.web.tsx`)
+ * plays the Rive file; the native half, and the web half when the runtime cannot load, draw a still
+ * (`SendStill`) that settles at once. Nothing about Rive crosses this line.
+ */
+export type SendStageCommand = { kind: 'send' | 'reset' | 'reveal'; n: number };
+
+export type SendStageProps = {
+  config: SendCompletionSettings;
+  /** The host's send has succeeded: the check may draw. False holds the circle, breathing. */
+  delivered: boolean;
+  command: SendStageCommand | null;
+  onStatus: (status: SendCompletionStatus) => void;
+  /** The button was pressed (click, tap, Enter or Space). */
+  onPress: () => void;
+  /**
+   * Pressing does nothing: a send is under way, or done. Presses are ignored rather than the control
+   * disabled — a disabled control dims, and the animation draws its own state.
+   */
+  pressDisabled: boolean;
+  /** The control's accessible name: the label, or the completed label once sent. */
+  label: string;
+  testID?: string;
+};
+
+/** The artboard's 4:3 (720 × 540). */
+export const STAGE_ASPECT = 720 / 540;

package/src/components/onboarding/send-completion/SendStage.web.tsx

@@ -0,0 +1,116 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Alignment, Fit, Layout, useRive } from '@rive-app/react-canvas';
+import { Box, Pressable } from '../../../core';
+import type { SendCompletionStatus } from './contract';
+import { riveWrites } from './engine';
+import { SendStill } from './SendStill';
+import { SEND_COMPLETION_RIV } from './riv';
+import { STAGE_ASPECT, type SendStageProps } from './SendStage.types';
+
+export type { SendStageProps };
+
+/**
+ * **The web half: the Rive animation.**
+ *
+ * The Rive file (`rive/send-completion/`) owns the artwork, the flight, the morph and every frame
+ * of timing. This owns only the conversation with it, through the `SendCompletion` view model: the
+ * config is written whenever it changes (it never restarts playback); `delivered` gates the check;
+ * `send`, `reset` and `reveal` are triggers; `status` is written by the file's own machine.
+ *
+ * The press is taken here, by an accessible button around the canvas (Enter and Space included),
+ * not by the file's own click listener — the canvas takes no pointer events, so nothing fires twice.
+ * If the runtime or the file cannot load, the stage shows the still and a send settles at once.
+ */
+
+const ARTBOARD = 'SendCompletion';
+const MACHINE = 'SendCompletionMachine';
+
+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(SEND_COMPLETION_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 | boolean };
+type Instance = {
+  string(p: string): (Prop & { value: string; on(cb: () => void): void; off(cb?: () => void): void }) | null;
+  number(p: string): Prop | null;
+  color(p: string): Prop | null;
+  boolean(p: string): Prop | null;
+  trigger(p: string): { trigger(): void } | null;
+};
+
+export function SendStage({ config, delivered, command, onStatus, onPress, pressDisabled, label, testID }: SendStageProps) {
+  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 config, whenever it changes. */
+  const writes = riveWrites(config);
+  const signature = JSON.stringify(writes);
+  useEffect(() => {
+    if (!vm) return;
+    for (const w of writes) {
+      const p = vm[w.kind](w.name);
+      if (p && p.value !== w.value) p.value = w.value;
+    }
+  }, [vm, signature]);
+
+  /* 2 · Whether the host's send has succeeded — before any command, so a send reads it. */
+  useEffect(() => {
+    const p = vm?.boolean('delivered');
+    if (p && p.value !== delivered) p.value = delivered;
+  }, [vm, delivered]);
+
+  /* 3 · Commands, as triggers. */
+  useEffect(() => {
+    if (!vm || !command) return;
+    vm.trigger(command.kind)?.trigger();
+    rive?.play();
+  }, [vm, command?.n]);
+
+  /* 4 · The file says where playback is. */
+  useEffect(() => {
+    const status = vm?.string('status');
+    if (!status) return;
+    const report = () => heard.current(status.value as SendCompletionStatus);
+    status.on(report);
+    return () => status.off(report);
+  }, [vm]);
+
+  /* Without the runtime, the still: a delivered send settles at once, as on native. */
+  const [stillSent, setStillSent] = useState(false);
+  useEffect(() => {
+    if (!failed || !command) return;
+    if (command.kind === 'reset') { setStillSent(false); heard.current('idle'); }
+    else if (command.kind === 'reveal' || delivered) { setStillSent(true); heard.current('sent'); }
+    else heard.current('launching');
+  }, [failed, command?.n, delivered]);
+
+  return (
+    <Pressable role="button" aria-label={label} onPress={pressDisabled ? undefined : onPress} testID={testID} style={{ width: '100%' }}>
+      {failed ? <SendStill config={config} sent={stillSent} /> : (
+        /* `data-rive` says whether the artboard has painted — a screenshot (the visual gate) waits for `ready`. */
+        <Box style={{ width: '100%', aspectRatio: STAGE_ASPECT, overflow: 'hidden' }}>
+          <RiveComponent aria-hidden="true" data-rive={rive ? 'ready' : 'loading'} style={{ width: '100%', height: '100%', display: 'block', pointerEvents: 'none' }} />
+        </Box>
+      )}
+    </Pressable>
+  );
+}

package/src/components/onboarding/send-completion/SendStill.tsx

@@ -0,0 +1,19 @@
+import { Box, Icon, Text } from '../../../core';
+import { cssColor } from '../shared/configColor';
+import { STAGE_ASPECT, type SendStageProps } from './SendStage.types';
+
+/**
+ * **The animation as a still** — native, and the web when the Rive runtime cannot load: the button
+ * with its label, or, once sent, the check and the completed label. Same words, colours and radius.
+ */
+export function SendStill({ config: c, sent, testID }: { config: SendStageProps['config']; sent: boolean; testID?: string }) {
+  const button = cssColor(c.buttonColor);
+  return (
+    <Box testID={testID} style={{ width: '100%', aspectRatio: STAGE_ASPECT, backgroundColor: cssColor(c.backgroundColor), alignItems: 'center', justifyContent: 'center' }}>
+      <Box style={{ flexDirection: 'row', alignItems: 'center', gap: 10, paddingVertical: 12, paddingHorizontal: 20, borderRadius: c.cornerRadius, backgroundColor: button }}>
+        <Icon name={sent ? 'check' : 'send'} size={20} color={cssColor(sent ? c.completionColor : c.iconColor)} />
+        <Text numberOfLines={1} style={{ fontSize: 18, fontWeight: '800', color: cssColor(sent ? c.completionColor : c.textColor) }}>{sent ? c.completedLabel : c.label}</Text>
+      </Box>
+    </Box>
+  );
+}

package/src/components/onboarding/send-completion/contract.ts

@@ -0,0 +1,127 @@
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import { COLOR_FORMATS, parseColor } from '../shared/configColor';
+import presetsJson from './presets.json';
+
+/**
+ * **Send Completion** — a send button that finishes its own story. Pressed, its icon launches on a
+ * looping flight, the button balls up into a circle, a check draws in, and a pill slides out with
+ * the completed label ("Send" → "Sent!"). Rive owns every frame of it
+ * (`rive/send-completion/`); the config owns the words, the colours, the icon, the shape and the
+ * behaviour — never the motion.
+ *
+ * The press runs the host's `send` operation. The check is not drawn until it has succeeded: a
+ * slow send holds the circle (it breathes) and a failed one returns the button and says so. So
+ * `sent` means the send is done — the one component here whose last frame IS the task's result,
+ * because it waits for it.
+ */
+
+export const SEND_COMPLETION_SCENES = ['default', 'sending', 'sent', 'failed', 'loading', 'empty', 'error'] as const;
+export type SendCompletionScene = (typeof SEND_COMPLETION_SCENES)[number];
+/** Scenes that are the send in flight — see `sceneProps`. */
+export const SEND_COMPLETION_IN_FLIGHT: readonly string[] = ['sending'];
+
+/** The icons the button can carry and launch, in the order the Rive file holds them. */
+export const SEND_COMPLETION_ICONS = ['plane', 'arrow', 'chevron'] as const;
+export type SendCompletionIcon = (typeof SEND_COMPLETION_ICONS)[number];
+
+/** Where playback is, as the Rive file reports it. */
+export type SendCompletionStatus = 'idle' | 'pressed' | 'launching' | 'transforming' | 'sent';
+
+export type SendCompletionColors = {
+  /** Behind everything. */
+  backgroundColor: string;
+  /** The button, the circle and the pill. */
+  buttonColor: string;
+  /** The button's label. */
+  textColor: string;
+  /** The icon while it sits in the button. */
+  iconColor: string;
+  /** The check and the completed label. */
+  completionColor: string;
+  /** The icon in flight, its trail, and the tap cue's words. */
+  trailColor: string;
+};
+
+/** Every word the card shows around the animation. */
+export type SendCompletionCopy = {
+  /** The button's words — what the send does. Up to 3 words, 16 characters; longer type shrinks to fit. */
+  label: string;
+  /** What the pill says when it is done. Up to 3 words, 16 characters. */
+  completedLabel: string;
+  /** The tap cue above the button (when `showTapCue`). */
+  tapHint: string;
+  resetLabel: string;
+  /** The status chip. */
+  idleChip: string;
+  sendingChip: string;
+  sentChip: string;
+  /** A failed send: the alert, and its default body when the host gives no message. */
+  failTitle: string;
+  failBody: string;
+  /** What a screen reader hears once it is done: "{completedLabel}". */
+  doneAnnouncement: string;
+};
+
+export type SendCompletionSettings = HeaderConfig & LoadCopy & SendCompletionCopy & SendCompletionColors & {
+  /** The icon in the button — one of `SEND_COMPLETION_ICONS`. */
+  sendIcon: string;
+  /** The icon's size, 0.6–1.4 (1 is the design's). */
+  iconScale: number;
+  /** The button's corner radius, 0–40. The circle it becomes is always round. */
+  cornerRadius: number;
+  /** The animation's widest, in points (160–960). It keeps its 4:3 and shrinks with its container. */
+  width: number;
+  /** Show "TAP/CLICK" and a fingertip before the press, as the reference does. */
+  showTapCue: boolean;
+  /** Press on its own as soon as it shows. */
+  autoplay?: boolean;
+  /** Replay forever: press, send, hold "Sent!", reset. Decorative — the host's `send` is not called. */
+  loop?: boolean;
+  ship?: string;
+};
+
+export const SEND_COMPLETION_PRESETS = presetsJson as unknown as PresetsFile<SendCompletionSettings>;
+
+/** Limits that keep the words legible inside the fixed button and pill. */
+export const SEND_COMPLETION_LIMITS = {
+  label: { words: 3, chars: 16 },
+  completedLabel: { words: 3, chars: 16 },
+  tapHint: { words: 3, chars: 20 },
+  iconScale: [0.6, 1.4],
+  cornerRadius: [0, 40],
+  width: [160, 960],
+} as const;
+/** One playthrough, press to "Sent!": 65 frames at 24 fps; the reference then holds it 2.3 s. */
+export const SEND_COMPLETION_SECONDS = 2.7;
+
+const COLOR_KEYS = ['backgroundColor', 'buttonColor', 'textColor', 'iconColor', 'completionColor', 'trailColor'] as const;
+const isText = (v: unknown): v is string => typeof v === 'string' && v.trim() !== '';
+const words = (s: string) => s.trim().split(/\s+/).filter(Boolean).length;
+const inRange = (v: unknown, [lo, hi]: readonly [number, number]) => typeof v === 'number' && Number.isFinite(v) && v >= lo && v <= hi;
+
+/**
+ * The config's problems, each with its field. Words over a limit are refused, never shortened.
+ * Never throws, whatever it is given.
+ */
+export function validateSendCompletion(c: SendCompletionSettings): OnboardingIssue[] {
+  const issues: OnboardingIssue[] = [];
+  for (const key of ['label', 'completedLabel', 'tapHint'] as const) {
+    const v = c?.[key];
+    const lim = SEND_COMPLETION_LIMITS[key];
+    if (!isText(v)) { issues.push({ path: key, message: `${key} needs text.` }); continue; }
+    if ([...v].some(ch => ch.charCodeAt(0) < 32 || ch.charCodeAt(0) === 127)) { issues.push({ path: key, message: `${key} is one line of plain text.` }); continue; }
+    if (words(v) > lim.words) issues.push({ path: key, message: `${key} takes at most ${lim.words} words; it has ${words(v)}.` });
+    if (v.trim().length > lim.chars) issues.push({ path: key, message: `${key} takes at most ${lim.chars} characters; it has ${v.trim().length}.` });
+  }
+  for (const key of COLOR_KEYS) {
+    if (!parseColor(c?.[key])) issues.push({ path: key, message: `${key} is a colour: ${COLOR_FORMATS}.` });
+  }
+  if (!(SEND_COMPLETION_ICONS as readonly string[]).includes(c?.sendIcon as string)) issues.push({ path: 'sendIcon', message: `sendIcon is one of ${SEND_COMPLETION_ICONS.join(', ')}.` });
+  if (!inRange(c?.iconScale, SEND_COMPLETION_LIMITS.iconScale)) issues.push({ path: 'iconScale', message: 'iconScale is a number from 0.6 to 1.4.' });
+  if (!inRange(c?.cornerRadius, SEND_COMPLETION_LIMITS.cornerRadius)) issues.push({ path: 'cornerRadius', message: 'cornerRadius is a number from 0 to 40.' });
+  if (!inRange(c?.width, SEND_COMPLETION_LIMITS.width)) issues.push({ path: 'width', message: 'width is a number of points from 160 to 960.' });
+  for (const key of ['showTapCue', 'autoplay', 'loop'] as const) {
+    if (c?.[key] !== undefined && typeof c[key] !== 'boolean') issues.push({ path: key, message: `${key} is yes or no.` });
+  }
+  return issues;
+}

package/src/components/onboarding/send-completion/engine.ts

@@ -0,0 +1,37 @@
+import { argb } from '../shared/configColor';
+import { SEND_COMPLETION_ICONS, type SendCompletionScene, type SendCompletionSettings } from './contract';
+
+/** Where the send is — the host's truth, which the animation follows. */
+export type SendPhase = 'idle' | 'sending' | 'sent' | 'failed';
+
+/** A demo scene's starting point. */
+export type SendCompletionSeed = { phase: SendPhase; message?: string };
+
+export function sendCompletionSeed(_config: SendCompletionSettings, scene: SendCompletionScene | string): SendCompletionSeed {
+  return { phase: scene === 'sending' ? 'sending' : scene === 'sent' ? 'sent' : scene === 'failed' ? 'failed' : 'idle' };
+}
+
+export type RiveWrite = { kind: 'string' | 'color' | 'number' | 'boolean'; name: string; value: string | number | boolean };
+
+/**
+ * **The config as the Rive file's view model takes it.** The one place its names appear
+ * (`rive/send-completion/README.md`); the icon goes by its index in the file.
+ */
+export function riveWrites(c: SendCompletionSettings): RiveWrite[] {
+  return [
+    { kind: 'string', name: 'label', value: c.label.trim() },
+    { kind: 'string', name: 'completedLabel', value: c.completedLabel.trim() },
+    { kind: 'string', name: 'tapHint', value: c.tapHint.trim() },
+    { kind: 'color', name: 'backgroundColor', value: argb(c.backgroundColor) },
+    { kind: 'color', name: 'buttonColor', value: argb(c.buttonColor) },
+    { kind: 'color', name: 'textColor', value: argb(c.textColor) },
+    { kind: 'color', name: 'iconColor', value: argb(c.iconColor) },
+    { kind: 'color', name: 'completionColor', value: argb(c.completionColor) },
+    { kind: 'color', name: 'trailColor', value: argb(c.trailColor) },
+    { kind: 'number', name: 'iconIndex', value: Math.max(0, (SEND_COMPLETION_ICONS as readonly string[]).indexOf(c.sendIcon)) },
+    { kind: 'number', name: 'iconScale', value: c.iconScale },
+    { kind: 'number', name: 'cornerRadius', value: c.cornerRadius },
+    { kind: 'boolean', name: 'showTapCue', value: c.showTapCue },
+    { kind: 'boolean', name: 'loop', value: !!c.loop },
+  ];
+}

package/src/components/onboarding/send-completion/index.ts

@@ -0,0 +1,10 @@
+export {
+  SEND_COMPLETION_ICONS, SEND_COMPLETION_IN_FLIGHT, SEND_COMPLETION_LIMITS, SEND_COMPLETION_PRESETS, SEND_COMPLETION_SCENES, SEND_COMPLETION_SECONDS,
+  validateSendCompletion,
+  type SendCompletionColors, type SendCompletionCopy, type SendCompletionIcon, type SendCompletionScene, type SendCompletionSettings, type SendCompletionStatus,
+} from './contract';
+export { riveWrites as sendCompletionRiveWrites, sendCompletionSeed, type SendCompletionSeed, type SendPhase } from './engine';
+export { SendCompletion, type SendCompletionOperations, type SendCompletionProps } from './SendCompletionView';
+/* Colours a config may give — hex, rgb(), rgba(), hue tokens, transparent — for builders' colour controls. */
+export { COLOR_TOKENS as CONFIG_COLOR_TOKENS, configColorHex, parseColor as parseConfigColor } from '../shared/configColor';
+export type { SendStageCommand, SendStageProps } from './SendStage.types';