@wireai/activation 0.7.0 → 0.9.0

package/src/cards/SelectionCard.tsx

@@ -16,6 +16,8 @@ import { useOnboardingTheme } from "../theme/ThemeContext";
 import { labelStyle } from "../theme/typography";
 import { Button } from "../components/Button";
 import { CardLayout } from "../components/CardLayout";
+import { WireIcon } from "../icons/WireIcon";
+import { normalizeOptions, optionsField, type CardOption } from "./optionSchema";
 import {
   CHECK_SCALE_FROM,
   CHECK_SPRING,
@@ -30,28 +32,17 @@ import { useReducedMotion } from "../motion/useReducedMotion";
 
 const easeWire = Easing.bezier(...WIRE_BEZIER);
 
-const optionObjectSchema = z.object({
-  value: z.string().describe("Option value"),
-  label: z.string().describe("Option display label"),
-});
-
 const schema = z.object({
   title: z.string().describe("Question or prompt for the user"),
-  options: z
-    .preprocess(
-      (arr) =>
-        Array.isArray(arr)
-          ? arr.map((item) => (typeof item === "string" ? { value: item, label: item } : item))
-          : arr,
-      z.array(optionObjectSchema).min(1),
-    )
-    .describe("List of choices"),
+  options: optionsField("List of choices"),
   submitLabel: z.string().optional().describe("Submit button label, default: Continue"),
   multiSelect: z.boolean().optional().describe("Allow multiple selections"),
 });
 
-type Props = z.infer<typeof schema> &
+type Props = Omit<z.infer<typeof schema>, "options"> &
   InjectedProps & {
+    /** Bare strings stay valid (normalized on the way in) — see optionSchema.ts. */
+    options: ReadonlyArray<string | CardOption>;
     onSelect?: (selected: string | string[]) => void;
     /** Fires as the live selection changes (before Continue), so the flow can prefetch the
      *  next turn. Same value shape as onSelect. Optional — injected by OnboardingFlow. */
@@ -59,7 +50,7 @@ type Props = z.infer<typeof schema> &
   };
 
 type OptionRowProps = {
-  opt: z.infer<typeof optionObjectSchema>;
+  opt: CardOption;
   isSelected: boolean;
   multiSelect: boolean;
   onToggle: (value: string) => void;
@@ -182,7 +173,11 @@ const _OptionRow: React.FC<OptionRowProps> = ({ opt, isSelected, multiSelect, on
           ) : null}
         </View>
         {/* Accent discipline: the label keeps the text color in both states; the
-            accent lives on the border, fill, and dot only. */}
+            accent lives on the border, fill, and dot only. The icon obeys the same rule —
+            it holds `text` in BOTH states rather than flipping to the accent, because an
+            icon is not an excuse to invent a second accent. Decorative + unresolvable-safe:
+            an unknown name renders null, so the row lays out exactly as an icon-less one. */}
+        <WireIcon name={opt.icon} size={20} color={t.colors.text} />
         <Text style={[labelStyle(t.fonts), { color: t.colors.text }]}>{opt.label}</Text>
       </Animated.View>
     </Pressable>
@@ -199,6 +194,7 @@ const _SelectionCard: React.FC<Props> = ({
   onSelectionChange,
 }) => {
   const t = useOnboardingTheme();
+  const opts = React.useMemo(() => normalizeOptions(options), [options]);
   const [selected, setSelected] = useState<string[]>([]);
   const [submitted, setSubmitted] = useState(false);
 
@@ -239,7 +235,7 @@ const _SelectionCard: React.FC<Props> = ({
       }
     >
       <View style={{ gap: t.spacing.sm + t.spacing.xs }}>
-        {options.map((opt) => (
+        {opts.map((opt) => (
           <OptionRow
             key={opt.value}
             opt={opt}
@@ -256,7 +252,7 @@ const _SelectionCard: React.FC<Props> = ({
 export const SelectionCard: WireAIComponent = {
   name: "SelectionCard",
   description:
-    "Use for mutually exclusive (radio) or multi-select (checkbox) choices from 2–8 options. Use ChipSelectCard instead when options are short single words.",
+    "Use for mutually exclusive (radio) or multi-select (checkbox) choices from 2–8 options, as a vertical list of rows. Best when options are wordy or need reading. Options may carry an optional `icon` from the vocabulary to make the list scannable. Use ChipSelectCard instead when options are short single words; use CardGridSelectCard when the options are visual and each has an obvious icon (occasions, channels, categories).",
   component: React.memo(_SelectionCard) as WireAIComponent["component"],
   propsSchema: schema,
   defaultProps: { submitLabel: "Continue", multiSelect: false },

package/src/cards/index.ts

@@ -7,16 +7,28 @@ import type { WireAIComponent } from "wireai-rn";
 import { ChipSelectCard } from "./ChipSelectCard";
 import { TextInputCard } from "./TextInputCard";
 import { SelectionCard } from "./SelectionCard";
+import { CardGridSelectCard } from "./CardGridSelectCard";
 import { StatusCard } from "./StatusCard";
 import { NumberStepperCard } from "./NumberStepperCard";
 import { InterstitialCard } from "./InterstitialCard";
 
-export { ChipSelectCard, TextInputCard, SelectionCard, StatusCard, NumberStepperCard, InterstitialCard };
+export {
+  ChipSelectCard,
+  TextInputCard,
+  SelectionCard,
+  CardGridSelectCard,
+  StatusCard,
+  NumberStepperCard,
+  InterstitialCard,
+};
+export { normalizeOptions, optionsField, optionObjectSchema } from "./optionSchema";
+export type { CardOption } from "./optionSchema";
 
 export const onboardingComponents: WireAIComponent[] = [
   ChipSelectCard,
   TextInputCard,
   SelectionCard,
+  CardGridSelectCard,
   StatusCard,
   NumberStepperCard,
   InterstitialCard,

package/src/cards/optionSchema.ts

@@ -0,0 +1,65 @@
+/**
+ * The shared option shape for the choice cards (SelectionCard, CardGridSelectCard).
+ *
+ * ── BACK-COMPAT, IN BOTH DIRECTIONS (the hard gate) ──────────────────────────────────────
+ *
+ * NEW option → OLD kit: `z.object` STRIPS unknown keys, and the SDK renderer mounts
+ * `parsed.data` (not the raw props — see wireai-rn `renderer/ComponentRenderer.tsx`). So a
+ * client on kit 0.7.x that receives `{value, label, icon}` silently drops `icon` and renders
+ * the plain row it always did. No throw, no fallback card. This is what makes it safe to teach
+ * the server `icon` before every host has re-pinned — and it MUST stay true, so never make
+ * this schema `.strict()`.
+ *
+ * OLD option → NEW kit: the `preprocess` still coerces a bare `"Spring"` into
+ * `{value:"Spring", label:"Spring"}`, exactly as before. A bare string and a bare
+ * `{value,label}` both keep working untouched.
+ *
+ * `icon` is a plain `z.string()`, NOT a z.enum of the vocabulary. Deliberate: an unknown name
+ * must degrade to no icon (WireIcon does that), never fail validation. If it were an enum, one
+ * hallucinated or newer-than-this-client icon name would turn the whole card into a
+ * LLM_SCHEMA_ERROR and cost the user their question — a catastrophic trade for a decoration.
+ */
+import { z } from "zod";
+
+import { WIRE_ICON_NAMES } from "../icons/vocabulary";
+
+/**
+ * The icon `.describe()` — an LLM ROUTING INSTRUCTION, not a type label (frequent_rules #4).
+ * The vocabulary is inlined so the model reads the allowed values right where it fills the
+ * field, and the list stays generated from the SSOT rather than drifting in a hand-typed copy.
+ */
+export const ICON_FIELD_DESCRIPTION =
+  "Optional icon for this option, making the choice scannable at a glance. Pick the ONE name " +
+  "whose meaning matches the option (e.g. 'instagram' for an Instagram answer, 'friend' for " +
+  "'A friend told me', 'wedding' for a wedding). Omit it when no name fits — a wrong icon is " +
+  `worse than none. Allowed values: ${WIRE_ICON_NAMES.join(", ")}.`;
+
+export const optionObjectSchema = z.object({
+  value: z.string().describe("Option value"),
+  label: z.string().describe("Option display label"),
+  icon: z.string().optional().describe(ICON_FIELD_DESCRIPTION),
+});
+
+export type CardOption = z.infer<typeof optionObjectSchema>;
+
+/** A bare string stays a valid option: coerce it to `{value, label}` before validating. */
+const coerceOptions = (arr: unknown) =>
+  Array.isArray(arr)
+    ? arr.map((item) => (typeof item === "string" ? { value: item, label: item } : item))
+    : arr;
+
+/** The `options` field, with its card-specific routing description. */
+export const optionsField = (description: string) =>
+  z.preprocess(coerceOptions, z.array(optionObjectSchema).min(1)).describe(description);
+
+/**
+ * Component-level tolerance for the SAME coercion the schema does.
+ *
+ * WHY BOTH: in production the SDK renderer re-parses props and hands the card `parsed.data`, so
+ * options arrive normalized. But a card is a plain exported component — the canary suite and any
+ * host composing it directly mount it with raw props, where a bare string would otherwise read
+ * `opt.value === undefined` and render an empty, unkeyed row. Cheap, total, and keeps the
+ * component honest on its own contract instead of relying on a caller that may not exist.
+ */
+export const normalizeOptions = (options: ReadonlyArray<string | CardOption>): CardOption[] =>
+  options.map((opt) => (typeof opt === "string" ? { value: opt, label: opt } : opt));

package/src/coachmarks/types.ts

@@ -1,7 +1,7 @@
 /**
  * Shared types for the coachmark / guided-tour overlay engine.
  *
- * Lifted from the Myelino app engine and made kit-generic: the app supplies the
+ * Lifted from a host app engine and made kit-generic: the app supplies the
  * anchors + catalog + copy, the kit owns the animation/measure/queue mechanics.
  * Dependency-free on purpose so the type surface can be imported anywhere.
  */

package/src/components/CardHandoff.tsx

@@ -12,6 +12,16 @@
  *   - "fade": loaders — enter/exit as a plain 120ms fade so the "thinking"
  *     state hands off to the first card without a hard cut.
  *
+ * `direction` mirrors the whole slide for BACK navigation, so a step the user
+ * returns to comes back from the side it left toward. Spatial consistency: if
+ * "next" pushes left, "back" must pull right, or the stack loses its geography.
+ *
+ * `layout` picks how the moving surface is sized. "fill" (default) is the
+ * full-screen flow, where the pane owns the viewport. "auto" is for a pane
+ * inside an auto-height container (the CenteredModal card): `flex: 1` there
+ * resolves to a ZERO-height child under Yoga — flex-basis 0 with no free space
+ * to grow into — so the in-flow layer must size to its own content instead.
+ *
  * Reduce motion: every handoff becomes a 120ms crossfade, no translate/scale.
  * All values run on the native driver (transform/opacity only); in-flight
  * animations are stopped when superseded and on unmount.
@@ -40,11 +50,21 @@ const easeWire = Easing.bezier(...WIRE_BEZIER);
 
 export type CardHandoffVariant = "slide" | "spring" | "fade";
 
+/** Which way the stack is moving. "backward" mirrors the slide (see the header note). */
+export type CardHandoffDirection = "forward" | "backward";
+
+/** How the moving surface is sized. "auto" = a pane in an auto-height container. */
+export type CardHandoffLayout = "fill" | "auto";
+
 export type CardHandoffProps = {
   /** Identity of the current child (e.g. the message id). A change runs the handoff. */
   transitionKey: string;
   /** How the CURRENT child enters (and, snapshotted, how it will later exit). */
   variant?: CardHandoffVariant;
+  /** Travel direction of THIS transition. Default "forward". */
+  direction?: CardHandoffDirection;
+  /** Sizing mode. Default "fill" (the full-screen flow). */
+  layout?: CardHandoffLayout;
   children: React.ReactNode;
 };
 
@@ -53,6 +73,8 @@ type Snapshot = { key: string; node: React.ReactNode; variant: CardHandoffVarian
 const _CardHandoff: React.FC<CardHandoffProps> = ({
   transitionKey,
   variant = "slide",
+  direction = "forward",
+  layout = "fill",
   children,
 }) => {
   const reduced = useReducedMotion();
@@ -118,7 +140,7 @@ const _CardHandoff: React.FC<CardHandoffProps> = ({
 
   const enterStyle = {
     opacity: enterT,
-    transform: transformFor(variant, enterT, reduced, "enter"),
+    transform: transformFor(variant, enterT, reduced, "enter", direction),
   };
 
   return (
@@ -130,14 +152,17 @@ const _CardHandoff: React.FC<CardHandoffProps> = ({
             StyleSheet.absoluteFill,
             {
               opacity: exitT.interpolate({ inputRange: [0, 1], outputRange: [1, 0] }),
-              transform: transformFor(leaving.variant, exitT, reduced, "exit"),
+              // The CURRENT direction drives BOTH layers: one transition, one geography.
+              transform: transformFor(leaving.variant, exitT, reduced, "exit", direction),
             },
           ]}
         >
           {leaving.node}
         </Animated.View>
       ) : null}
-      <Animated.View key={variant} style={[styles.fill, enterStyle]}>{children}</Animated.View>
+      <Animated.View key={variant} style={[layout === "fill" ? styles.fill : null, enterStyle]}>
+        {children}
+      </Animated.View>
     </>
   );
 };
@@ -180,22 +205,29 @@ const startEnter = (
   return anim;
 };
 
-/** Transform track per variant/direction; reduce motion = opacity-only crossfade. */
+/**
+ * Transform track per variant/layer; reduce motion = opacity-only crossfade.
+ *
+ * `travel` mirrors the X axis: forward pushes the stack left (new arrives from the
+ * right), backward pulls it right (new arrives from the left).
+ */
 const transformFor = (
   variant: CardHandoffVariant,
   t: Animated.Value,
   reduced: boolean,
-  direction: "enter" | "exit",
+  layer: "enter" | "exit",
+  travel: CardHandoffDirection,
 ) => {
   if (reduced || variant === "fade") return [];
-  if (variant === "spring" && direction === "enter") {
+  if (variant === "spring" && layer === "enter") {
     return [{ scale: t.interpolate({ inputRange: [0, 1], outputRange: [CARD_ENTER_SCALE_FROM, 1] }) }];
   }
+  const slide = travel === "forward" ? CARD_SLIDE_PX : -CARD_SLIDE_PX;
   return [
     {
       translateX: t.interpolate({
         inputRange: [0, 1],
-        outputRange: direction === "enter" ? [CARD_SLIDE_PX, 0] : [0, -CARD_SLIDE_PX],
+        outputRange: layer === "enter" ? [slide, 0] : [0, -slide],
       }),
     },
   ];

package/src/components/DoneCheck.tsx

@@ -0,0 +1,94 @@
+/**
+ * DoneCheck — the animated "done" payoff glyph shared by the review gate's and the
+ * questionnaire's thank-you panes. One component, two call sites, one feel.
+ *
+ * The beat is the house success beat, lifted from StatusCard (design-refs/
+ * EXTRACTED-SPEC.md rows 14/16): the glyph springs in with a slight overshoot
+ * (STATUS_POP_SPRING, scale STATUS_POP_SCALE_FROM→1) while the ring settles behind it.
+ * No new motion values are invented here — every number comes from motionSpec.
+ *
+ * It is a Text glyph in a themed circle, NOT an SVG path: `react-native-svg` is not a
+ * peer of this kit, and adding a NATIVE dependency to draw a checkmark would force every
+ * host into a rebuild. The five review stars are already glyphs, so this matches the
+ * house idiom.
+ *
+ * Reduce motion: the final frame, instantly — never a frozen mid-pop.
+ *
+ * Accessibility: purely decorative. The thank-you copy next to it carries the meaning,
+ * so the glyph is hidden from screen readers rather than announced as "heavy check mark".
+ */
+import React, { useEffect, useRef } from "react";
+import { Animated, StyleSheet } from "react-native";
+
+import { STATUS_POP_SCALE_FROM, STATUS_POP_SPRING } from "../motion/motionSpec";
+import { useReducedMotion } from "../motion/useReducedMotion";
+import type { OnboardingTheme } from "../theme/types";
+
+export type DoneCheckProps = {
+  /** The (already merged) active theme — the ring reads `colors.success`. */
+  theme: OnboardingTheme;
+  /** Diameter of the ring. Defaults to a size that balances the modal heading. */
+  size?: number;
+};
+
+const _DoneCheck: React.FC<DoneCheckProps> = ({ theme, size = 48 }) => {
+  const reduced = useReducedMotion();
+  const pop = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+
+  useEffect(() => {
+    if (reduced) {
+      pop.setValue(1);
+      return;
+    }
+    const anim = Animated.spring(pop, {
+      toValue: 1,
+      friction: STATUS_POP_SPRING.friction,
+      tension: STATUS_POP_SPRING.tension,
+      useNativeDriver: true,
+    });
+    anim.start();
+    return () => anim.stop();
+  }, [pop, reduced]);
+
+  const scale = pop.interpolate({
+    inputRange: [0, 1],
+    outputRange: [STATUS_POP_SCALE_FROM, 1],
+  });
+
+  return (
+    <Animated.View
+      accessibilityElementsHidden
+      importantForAccessibility="no-hide-descendants"
+      style={[
+        styles.ring,
+        {
+          width: size,
+          height: size,
+          borderRadius: theme.radius.full,
+          backgroundColor: theme.colors.success,
+          opacity: pop,
+          transform: [{ scale }],
+        },
+      ]}
+    >
+      <Animated.Text
+        style={[
+          styles.glyph,
+          { color: theme.colors.onPrimary, fontSize: Math.round(size * 0.5), fontFamily: theme.fonts.bold },
+        ]}
+      >
+        ✓
+      </Animated.Text>
+    </Animated.View>
+  );
+};
+
+export const DoneCheck = React.memo(_DoneCheck);
+DoneCheck.displayName = "DoneCheck";
+
+const styles = StyleSheet.create({
+  ring: { alignItems: "center", justifyContent: "center", alignSelf: "center" },
+  glyph: { includeFontPadding: false, textAlign: "center" },
+});
+
+export default DoneCheck;

package/src/components/ModalPaneHost.tsx

@@ -0,0 +1,141 @@
+/**
+ * ModalPaneHost — "slide between panes inside a CenteredModal", the shared primitive
+ * behind BOTH the review gate's phase changes and the questionnaire's step changes.
+ * One primitive, two call sites: the two gates must never drift apart on feel.
+ *
+ * It does NOT reimplement the slide. `CardHandoff` already owns the design's
+ * "cards hand off, they don't cut" motion (exit left 180ms / enter right 220ms, 80ms
+ * lead, reduce-motion crossfade), so this delegates to it in `layout="auto"` mode and
+ * adds the ONE thing a modal needs that a full-screen flow does not: a card that
+ * resizes instead of snapping.
+ *
+ * WHY the height animation exists: the CenteredModal card is auto-height, so the moment
+ * a taller/shorter pane mounts, the card would jump to its new height in a single frame
+ * while the old pane is still sliding out — the exact "jarring change" the slide was
+ * added to remove. Measuring the pane and easing the card to it keeps one continuous
+ * surface.
+ *
+ * WHY it is the only non-native-driven value in the kit: height is a layout prop, so it
+ * cannot ride the native driver. That is a deliberate, bounded exception — ONE property
+ * on ONE small card, for ~220ms, while nothing is scrolling. The panes' own opacity and
+ * translate (inside CardHandoff) stay on the native driver, and the two values live on
+ * different views, so they never contend. Everything else in the kit stays transform/
+ * opacity-only.
+ *
+ * Height is eased ONLY on a pane change. A multiline box growing as the user types also
+ * fires onLayout, and animating that would make typing feel laggy — those resize
+ * instantly. Reduce motion: the height snaps too (movement removed, crossfade kept).
+ *
+ * `header` is the STATIC slot: chrome that belongs to the card rather than to any one pane
+ * (the questionnaire's back icon + step dots). It sits inside the measured container but
+ * OUTSIDE the CardHandoff, which buys two things a caller cannot get by rendering it above
+ * the host:
+ *   1. It never slides, so it is never DUPLICATED mid-handoff. Anything inside CardHandoff
+ *      exists twice for ~300ms (the outgoing layer and the incoming one) — fine for a
+ *      question that is genuinely changing, wrong for chrome that is not. Two dot rows
+ *      cross-fading past each other is a bug, not a transition.
+ *   2. Its size is part of the measured height, so dropping the header (form → thanks)
+ *      rides the same eased resize as the pane swap instead of snapping the card.
+ */
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { Animated, Easing, StyleSheet, View, type LayoutChangeEvent } from "react-native";
+
+import { CARD_ENTER_MS, WIRE_BEZIER, scaledMs } from "../motion/motionSpec";
+import { useReducedMotion } from "../motion/useReducedMotion";
+import { CardHandoff, type CardHandoffDirection } from "./CardHandoff";
+
+const easeWire = Easing.bezier(...WIRE_BEZIER);
+
+export type ModalPaneHostProps = {
+  /** Identity of the pane on screen (phase name / step key). A change runs the handoff. */
+  paneKey: string;
+  /** Travel direction — "backward" mirrors the slide when the user steps back. */
+  direction?: CardHandoffDirection;
+  /**
+   * Card-level chrome pinned above the sliding pane: measured with it, but never moved
+   * and never duplicated by the handoff. Omit it (or pass null) and nothing renders —
+   * dropping it between pane changes animates the card's height rather than snapping it.
+   * The node owns its own bottom spacing; the host adds none (it has no theme).
+   */
+  header?: React.ReactNode;
+  children: React.ReactNode;
+};
+
+const _ModalPaneHost: React.FC<ModalPaneHostProps> = ({
+  paneKey,
+  direction = "forward",
+  header,
+  children,
+}) => {
+  const reduced = useReducedMotion();
+  const height = useRef(new Animated.Value(0)).current;
+  /** Last height we settled on. null until the first real measurement lands. */
+  const measured = useRef<number | null>(null);
+  /** Drives the height style on only AFTER a real measurement, so nothing renders at 0. */
+  const [sized, setSized] = useState(false);
+  /** Set when the pane changed, cleared by the next measurement it causes. */
+  const paneChanged = useRef(false);
+  const running = useRef<Animated.CompositeAnimation | null>(null);
+
+  // Runs on mount and on every pane change, always BEFORE the resulting onLayout (which
+  // arrives from native after the commit) — so the next measurement knows why it fired.
+  useEffect(() => {
+    paneChanged.current = true;
+  }, [paneKey]);
+
+  useEffect(() => () => running.current?.stop(), []);
+
+  const onLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      const next = Math.round(event.nativeEvent.layout.height);
+      if (!next) return;
+      const previous = measured.current;
+      if (previous !== null && Math.abs(previous - next) < 1) return;
+
+      const first = previous === null;
+      const ease = !first && !reduced && paneChanged.current;
+      paneChanged.current = false;
+      measured.current = next;
+      running.current?.stop();
+
+      // First measurement, a reduce-motion user, or a plain content resize (typing):
+      // take the new height immediately.
+      if (!ease) {
+        height.setValue(next);
+        if (first) setSized(true);
+        return;
+      }
+
+      const anim = Animated.timing(height, {
+        toValue: next,
+        duration: scaledMs(CARD_ENTER_MS),
+        easing: easeWire,
+        // height is layout, not transform — see the header note.
+        useNativeDriver: false,
+      });
+      running.current = anim;
+      anim.start();
+    },
+    [height, reduced],
+  );
+
+  return (
+    <Animated.View style={sized ? { height, overflow: "hidden" } : undefined}>
+      <View onLayout={onLayout} style={styles.pane}>
+        {header}
+        <CardHandoff transitionKey={paneKey} direction={direction} layout="auto" variant="slide">
+          {children}
+        </CardHandoff>
+      </View>
+    </Animated.View>
+  );
+};
+
+export const ModalPaneHost = React.memo(_ModalPaneHost);
+ModalPaneHost.displayName = "ModalPaneHost";
+
+const styles = StyleSheet.create({
+  pane: { width: "100%" },
+});
+
+export default ModalPaneHost;

package/src/components/StepDots.tsx

@@ -0,0 +1,112 @@
+/**
+ * StepDots — the "how many steps, and which one am I on" row for a multi-step modal.
+ *
+ * It replaces the questionnaire's textual counter ("Question 2 of 3"). Malik's device
+ * feedback 2026-07-16: "instead of 1 out of 3 or 2-3, had points on top to explain the
+ * number of steps". A dot row says the same two things — how long this is, how far in you
+ * are — without spending a line of copy next to the question the user should be reading.
+ *
+ * NOT the same component as `StepProgress`: that one is the ONBOARDING flow's bar, and it
+ * deliberately refuses to show a count because the flow's length is model-decided and a
+ * number would be a promise the model may not keep. The questionnaire is the opposite
+ * case — a fixed 3-field server contract — so here the count is knowable and honest.
+ *
+ * Motion: a dot fills by crossfading a `colors.primary` layer over a `colors.border` base,
+ * at the design system's selection-fill duration (SELECT_FILL_MS, spec rows 2/3/5/6 — the
+ * same token every other "this is now selected" fill in the kit uses). Opacity only, on the
+ * native driver: no color interpolation (that would force `useNativeDriver: false`, and the
+ * kit keeps its one non-native exception in ModalPaneHost's height).
+ *
+ * Reduce motion: `stateChangeDuration` collapses the fill to 0ms, so the state snaps —
+ * the house convention for state changes (see StepProgress).
+ *
+ * Accessibility: sighted users read the dots; screen readers must not be handed three
+ * unlabelled circles. The ROW is one progressbar node carrying "Step 2 of 3" plus the
+ * numeric value, and the dots themselves are hidden as decoration.
+ */
+import React, { useEffect, useRef } from "react";
+import { Animated, Easing, StyleSheet, View } from "react-native";
+
+import { SELECT_FILL_MS, WIRE_BEZIER, scaledMs, stateChangeDuration } from "../motion/motionSpec";
+import { useReducedMotion } from "../motion/useReducedMotion";
+import type { OnboardingTheme } from "../theme/types";
+
+const easeWire = Easing.bezier(...WIRE_BEZIER);
+
+export type StepDotsProps = {
+  /** The (already merged) active theme — dots read `colors.border` / `colors.primary`. */
+  theme: OnboardingTheme;
+  /** How many steps there are (how many dots to draw). */
+  count: number;
+  /** 0-based index of the step on screen. */
+  index: number;
+};
+
+type DotProps = {
+  theme: OnboardingTheme;
+  /** True for the current step and every step behind it — the row reads as progress. */
+  filled: boolean;
+  size: number;
+};
+
+const Dot: React.FC<DotProps> = ({ theme, filled, size }) => {
+  const reduced = useReducedMotion();
+  const fill = useRef(new Animated.Value(filled ? 1 : 0)).current;
+
+  useEffect(() => {
+    const anim = Animated.timing(fill, {
+      toValue: filled ? 1 : 0,
+      duration: scaledMs(stateChangeDuration(reduced, SELECT_FILL_MS)),
+      easing: easeWire,
+      useNativeDriver: true,
+    });
+    anim.start();
+    return () => anim.stop();
+  }, [fill, filled, reduced]);
+
+  return (
+    <View
+      style={{
+        width: size,
+        height: size,
+        borderRadius: theme.radius.full,
+        backgroundColor: theme.colors.border,
+      }}
+    >
+      <Animated.View
+        style={[
+          StyleSheet.absoluteFill,
+          {
+            borderRadius: theme.radius.full,
+            backgroundColor: theme.colors.primary,
+            opacity: fill,
+          },
+        ]}
+      />
+    </View>
+  );
+};
+
+const _StepDots: React.FC<StepDotsProps> = ({ theme, count, index }) => (
+  <View
+    style={[styles.row, { gap: theme.spacing.sm }]}
+    accessibilityRole="progressbar"
+    accessibilityLabel={`Step ${index + 1} of ${count}`}
+    accessibilityValue={{ min: 1, max: count, now: index + 1 }}
+  >
+    {Array.from({ length: count }, (_, i) => (
+      <View key={i} accessibilityElementsHidden importantForAccessibility="no-hide-descendants">
+        <Dot theme={theme} filled={i <= index} size={theme.spacing.sm} />
+      </View>
+    ))}
+  </View>
+);
+
+export const StepDots = React.memo(_StepDots);
+StepDots.displayName = "StepDots";
+
+const styles = StyleSheet.create({
+  row: { flexDirection: "row", alignItems: "center", justifyContent: "center" },
+});
+
+export default StepDots;