@wireai/activation 0.8.0 → 0.9.1

package/src/cards/CardGridSelectCard.tsx

@@ -0,0 +1,253 @@
+/**
+ * CardGridSelectCard — icon-led choices as a two-column grid of small cards.
+ *
+ * The shape Malik asked for (2026-07-16): "the multi select needs to be a small card like this
+ * one, with an icon on top, it is much better." Icon top-left, short label beneath, the whole
+ * card is the tap target, selection lives on the card itself.
+ *
+ *   ┌──────────────┐ ┌──────────────┐
+ *   │ ◇            │ │ ▣            │     ← icon on top
+ *   │ Wedding day  │ │ Birthday     │     ← label beneath
+ *   └──────────────┘ └──────────────┘
+ *
+ * WHY A NEW CARD RATHER THAN A `display` MODE ON SelectionCard: the card's `description` IS the
+ * router — it is the only thing the model reads when choosing (frequent_rules #4). SelectionCard
+ * already carries two modes behind one description; a third ("a list, but sometimes a grid, and
+ * then the icons matter") cannot be stated honestly in one string, and a muddy description makes
+ * the model pick the wrong card. The kit already has the precedent: ChipSelectCard exists ONLY
+ * because "compact vs. descriptive" is a presentation difference worth its own name, over the
+ * very same pick-from-options job. Back-compat costs nothing here — `supportedComponents`
+ * (WireOnboarding.tsx) means an already-shipped client never advertises this name, so the server
+ * intersects it away and can never emit it to the apps already in the stores. See the CHANGELOG.
+ *
+ * Layout is percentage flex, never a measured width: `flexBasis` ~47% + `flexGrow` makes exactly
+ * two per row that fill the width, with no Dimensions read, no onLayout, and no re-render on
+ * rotation. An odd last card stretches the row — deliberate, and the same thing every native
+ * grid does.
+ *
+ * Motion mirrors SelectionCard's OptionRow exactly (press tick spring + a native-driver opacity
+ * crossfade of the selected overlay), so the two cards feel like one system.
+ */
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { Animated, Easing, Pressable, StyleSheet, Text, View } from "react-native";
+import { z } from "zod";
+import type { InjectedProps, WireAIComponent } from "wireai-rn";
+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 {
+  PRESS_SPRING,
+  ROW_PRESS_SCALE,
+  SELECT_FILL_MS,
+  WIRE_BEZIER,
+  scaledMs,
+  stateChangeDuration,
+} from "../motion/motionSpec";
+import { useReducedMotion } from "../motion/useReducedMotion";
+
+const easeWire = Easing.bezier(...WIRE_BEZIER);
+
+const schema = z.object({
+  title: z.string().describe("Question or prompt for the user, e.g. 'What brings you here?'"),
+  options: optionsField(
+    "The choices, 2-6 of them. Give EVERY option an `icon` from the vocabulary — the icon is " +
+      "the point of this card, and an option without one renders as a bare label next to " +
+      "icon-bearing neighbours. Keep labels short (1-3 words) so they fit a half-width card.",
+  ),
+  submitLabel: z.string().optional().describe("Submit button label, default: Continue"),
+  multiSelect: z
+    .boolean()
+    .optional()
+    .describe("Allow multiple cards selected at once, default true"),
+});
+
+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. */
+    onSelectionChange?: (selected: string | string[]) => void;
+  };
+
+type OptionCardProps = {
+  opt: CardOption;
+  isSelected: boolean;
+  multiSelect: boolean;
+  onToggle: (value: string) => void;
+};
+
+const _OptionCard: React.FC<OptionCardProps> = ({ opt, isSelected, multiSelect, onToggle }) => {
+  const t = useOnboardingTheme();
+  const reduced = useReducedMotion();
+  const handlePress = useCallback(() => onToggle(opt.value), [opt.value, onToggle]);
+
+  // Press tick: scale 1→0.975, spring, native driver. Skipped under reduce motion.
+  const pressScale = useRef(new Animated.Value(1)).current;
+  const pressTo = useCallback(
+    (to: number) => {
+      if (reduced) return;
+      Animated.spring(pressScale, {
+        toValue: to,
+        friction: PRESS_SPRING.friction,
+        tension: PRESS_SPRING.tension,
+        useNativeDriver: true,
+      }).start();
+    },
+    [pressScale, reduced],
+  );
+  const handlePressIn = useCallback(() => pressTo(ROW_PRESS_SCALE), [pressTo]);
+  const handlePressOut = useCallback(() => pressTo(1), [pressTo]);
+
+  // Selected fill: accent border + tinted wash on an absolute overlay whose opacity crossfades
+  // (native driver — see EXTRACTED-SPEC.md D7). Reduce motion: snap.
+  const selectT = useRef(new Animated.Value(isSelected ? 1 : 0)).current;
+  useEffect(() => {
+    const anim = Animated.timing(selectT, {
+      toValue: isSelected ? 1 : 0,
+      duration: scaledMs(stateChangeDuration(reduced, SELECT_FILL_MS)),
+      easing: easeWire,
+      useNativeDriver: true,
+    });
+    anim.start();
+    return () => anim.stop();
+  }, [isSelected, reduced, selectT]);
+
+  return (
+    <Pressable
+      onPress={handlePress}
+      onPressIn={handlePressIn}
+      onPressOut={handlePressOut}
+      accessibilityRole={multiSelect ? "checkbox" : "radio"}
+      accessibilityState={multiSelect ? { checked: isSelected } : { selected: isSelected }}
+      accessibilityLabel={opt.label}
+      style={styles.cell}
+    >
+      <Animated.View
+        style={[
+          styles.card,
+          {
+            padding: t.spacing.md,
+            borderRadius: t.radius.lg,
+            gap: t.spacing.sm,
+            borderColor: t.colors.border,
+            backgroundColor: t.colors.surface,
+            transform: [{ scale: pressScale }],
+          },
+        ]}
+      >
+        <Animated.View
+          pointerEvents="none"
+          style={[
+            StyleSheet.absoluteFill,
+            styles.selectedOverlay,
+            {
+              borderRadius: t.radius.lg,
+              borderColor: t.colors.primary,
+              backgroundColor: t.colors.primarySoft,
+              opacity: selectT,
+            },
+          ]}
+        />
+        {/* Accent discipline (same rule as SelectionCard's rows): label AND icon keep the text
+            color in both states; the accent lives on the border and fill only. An unresolvable
+            icon renders null, so a card with a bad name lays out like one with no icon. */}
+        <WireIcon name={opt.icon} size={24} color={t.colors.text} />
+        <Text style={[labelStyle(t.fonts), { color: t.colors.text }]}>{opt.label}</Text>
+      </Animated.View>
+    </Pressable>
+  );
+};
+const OptionCard = React.memo(_OptionCard);
+
+const _CardGridSelectCard: React.FC<Props> = ({
+  title,
+  options,
+  submitLabel = "Continue",
+  multiSelect = true,
+  onSelect,
+  onSelectionChange,
+}) => {
+  const t = useOnboardingTheme();
+  const opts = React.useMemo(() => normalizeOptions(options), [options]);
+  const [selected, setSelected] = useState<string[]>([]);
+  const [submitted, setSubmitted] = useState(false);
+
+  // Report the settled selection upward (before Continue) so the flow can prefetch the next
+  // turn. Debouncing lives in the flow; here we just emit on every change once something's picked.
+  useEffect(() => {
+    if (!submitted && selected.length) onSelectionChange?.(multiSelect ? selected : selected[0]!);
+  }, [selected, submitted, multiSelect, onSelectionChange]);
+
+  const toggle = useCallback(
+    (value: string) => {
+      if (submitted) return;
+      if (multiSelect) {
+        setSelected((prev) =>
+          prev.includes(value) ? prev.filter((v) => v !== value) : [...prev, value],
+        );
+      } else {
+        setSelected([value]);
+      }
+    },
+    [submitted, multiSelect],
+  );
+
+  const handleSubmit = useCallback(() => {
+    if (!selected.length || !onSelect || submitted) return;
+    setSubmitted(true);
+    onSelect(multiSelect ? selected : selected[0]!);
+  }, [selected, onSelect, submitted, multiSelect]);
+
+  return (
+    <CardLayout
+      title={title}
+      footer={
+        <Button
+          title={submitLabel}
+          onPress={handleSubmit}
+          variant="primary"
+          disabled={selected.length === 0 || submitted}
+        />
+      }
+    >
+      <View style={[styles.grid, { gap: t.spacing.sm }]}>
+        {opts.map((opt) => (
+          <OptionCard
+            key={opt.value}
+            opt={opt}
+            isSelected={selected.includes(opt.value)}
+            multiSelect={multiSelect}
+            onToggle={toggle}
+          />
+        ))}
+      </View>
+    </CardLayout>
+  );
+};
+
+export const CardGridSelectCard: WireAIComponent = {
+  name: "CardGridSelectCard",
+  description:
+    "Use for VISUAL, icon-led choices shown as a 2-column grid of tappable cards (icon on top, " +
+    "short label beneath). Ideal for 2–6 concrete options that each have an obvious icon — " +
+    "occasions, channels, goals, categories — e.g. 'What brings you here?' or 'Where did you " +
+    "hear about us?'. Multi-select by default. Every option should carry an `icon`. Use " +
+    "SelectionCard instead when options need descriptions or have no natural icon; use " +
+    "ChipSelectCard for many short word-like tags.",
+  component: React.memo(_CardGridSelectCard) as WireAIComponent["component"],
+  propsSchema: schema,
+  defaultProps: { submitLabel: "Continue", multiSelect: true },
+};
+
+const styles = StyleSheet.create({
+  grid: { flexDirection: "row", flexWrap: "wrap" },
+  // Two per row: ~47% basis leaves room for the gap, flexGrow fills the remainder exactly.
+  cell: { flexBasis: "47%", flexGrow: 1 },
+  card: { borderWidth: 1.5, alignItems: "flex-start", overflow: "hidden" },
+  selectedOverlay: { borderWidth: 1.5 },
+});

package/src/cards/ChipSelectCard.tsx

@@ -250,7 +250,7 @@ const _ChipSelectCard: React.FC<Props> = ({
 export const ChipSelectCard: WireAIComponent = {
   name: "ChipSelectCard",
   description:
-    "Use for compact short labels: seasons, activities, travel styles, moods, categories. Ideal for 4–12 single-word or two-word options. Use SelectionCard instead when options need descriptions.",
+    "Use for compact short labels: seasons, activities, travel styles, moods, categories. Ideal for 4–12 single-word or two-word options. Use SelectionCard instead when options need descriptions; use CardGridSelectCard for a smaller set (2–6) of visual choices that each deserve an icon.",
   component: React.memo(_ChipSelectCard) as WireAIComponent["component"],
   propsSchema: schema,
   defaultProps: { multiSelect: true, submitLabel: "Continue" },

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;