@wireai/activation 0.1.0

package/src/cards/ChipSelectCard.tsx

@@ -0,0 +1,265 @@
+/**
+ * Themed ChipSelectCard — drop-in replacement for the OSS SDK's ChipSelectCard.
+ * Identical `name`, `propsSchema`, `defaultProps`, and `onSelect` callback contract
+ * so the SDK's ComponentRenderer drives it transparently. Only the look is themed.
+ *
+ * Motion (design-refs/EXTRACTED-SPEC.md rows 4-6): chips tick on press (scale
+ * 0.94 spring), the selected accent fill crossfades in over 160ms (native-driver
+ * opacity overlay) with the label flipping to `onPrimary` and a check popping in.
+ * Deselect reverses. Reduce motion: color swap only, check shown instantly.
+ */
+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 { captionStyle } from "../theme/typography";
+import { Button } from "../components/Button";
+import { CardLayout } from "../components/CardLayout";
+import {
+  CHECK_SCALE_FROM,
+  CHECK_SPRING,
+  CHIP_FILL_MS,
+  CHIP_PRESS_SCALE,
+  PRESS_SPRING,
+  WIRE_BEZIER,
+  scaledMs,
+  stateChangeDuration,
+} from "../motion/motionSpec";
+import { useReducedMotion } from "../motion/useReducedMotion";
+
+const easeWire = Easing.bezier(...WIRE_BEZIER);
+
+// Mirror of the SDK schema — must stay identical so the registry + validator agree.
+const schema = z.object({
+  title: z.string().describe("Question or section header, e.g. 'Which season?'"),
+  chips: z
+    .array(z.string())
+    .min(1)
+    .describe("List of option labels shown as chips, e.g. ['Spring','Summer','Autumn','Winter']"),
+  multiSelect: z.boolean().optional().describe("Allow multiple chips selected at once, default true"),
+  submitLabel: z.string().optional().describe("Confirm button label, default: Continue"),
+  maxSelections: z.number().optional().describe("Maximum number of chips the user can select at once"),
+});
+
+type Props = z.infer<typeof schema> &
+  InjectedProps & {
+    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 ChipItemProps = {
+  chip: string;
+  isSelected: boolean;
+  multiSelect: boolean;
+  onToggle: (chip: string) => void;
+};
+
+const _ChipItem: React.FC<ChipItemProps> = ({ chip, isSelected, multiSelect, onToggle }) => {
+  const t = useOnboardingTheme();
+  const reduced = useReducedMotion();
+  const handlePress = useCallback(() => onToggle(chip), [chip, onToggle]);
+
+  // Press tick: scale 1→0.94, 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(CHIP_PRESS_SCALE), [pressTo]);
+  const handlePressOut = useCallback(() => pressTo(1), [pressTo]);
+
+  // Selected fill: full accent pill, crossfaded in over 160ms on a native-driver
+  // opacity overlay (EXTRACTED-SPEC.md D7). Reduce motion: instant swap.
+  const fillT = useRef(new Animated.Value(isSelected ? 1 : 0)).current;
+  useEffect(() => {
+    const anim = Animated.timing(fillT, {
+      toValue: isSelected ? 1 : 0,
+      duration: scaledMs(stateChangeDuration(reduced, CHIP_FILL_MS)),
+      easing: easeWire,
+      useNativeDriver: true,
+    });
+    anim.start();
+    return () => anim.stop();
+  }, [isSelected, reduced, fillT]);
+
+  // Check pop on select (the width-slide of the canvas is a layout animation the
+  // native driver can't express — see EXTRACTED-SPEC.md D4).
+  const checkT = useRef(new Animated.Value(isSelected ? 1 : 0)).current;
+  useEffect(() => {
+    if (!isSelected) {
+      checkT.setValue(0);
+      return;
+    }
+    if (reduced) {
+      checkT.setValue(1);
+      return;
+    }
+    checkT.setValue(0);
+    const anim = Animated.spring(checkT, {
+      toValue: 1,
+      friction: CHECK_SPRING.friction,
+      tension: CHECK_SPRING.tension,
+      useNativeDriver: true,
+    });
+    anim.start();
+    return () => anim.stop();
+  }, [isSelected, reduced, checkT]);
+
+  const checkScale = checkT.interpolate({ inputRange: [0, 1], outputRange: [CHECK_SCALE_FROM, 1] });
+
+  return (
+    <Pressable
+      onPress={handlePress}
+      onPressIn={handlePressIn}
+      onPressOut={handlePressOut}
+      accessibilityRole={multiSelect ? "checkbox" : "radio"}
+      accessibilityState={multiSelect ? { checked: isSelected } : { selected: isSelected }}
+      accessibilityLabel={chip}
+    >
+      <Animated.View
+        style={[
+          styles.chip,
+          {
+            borderRadius: t.radius.full,
+            paddingHorizontal: t.spacing.md,
+            paddingVertical: t.spacing.sm,
+            borderColor: t.colors.border,
+            backgroundColor: t.colors.background,
+            transform: [{ scale: pressScale }],
+          },
+        ]}
+      >
+        <Animated.View
+          pointerEvents="none"
+          style={[
+            StyleSheet.absoluteFill,
+            styles.fillOverlay,
+            {
+              borderRadius: t.radius.full,
+              borderColor: t.colors.primary,
+              backgroundColor: t.colors.primary,
+              opacity: fillT,
+            },
+          ]}
+        />
+        {isSelected ? (
+          <Animated.Text
+            style={[
+              styles.check,
+              { color: t.colors.onPrimary, opacity: checkT, transform: [{ scale: checkScale }] },
+            ]}
+          >
+            ✓
+          </Animated.Text>
+        ) : null}
+        <Text
+          style={[
+            captionStyle(t.fonts),
+            styles.chipLabel,
+            { color: isSelected ? t.colors.onPrimary : t.colors.textMuted },
+          ]}
+        >
+          {chip}
+        </Text>
+      </Animated.View>
+    </Pressable>
+  );
+};
+const ChipItem = React.memo(_ChipItem);
+
+const _ChipSelectCard: React.FC<Props> = ({
+  title,
+  chips,
+  multiSelect = true,
+  submitLabel = "Continue",
+  maxSelections,
+  onSelect,
+  onSelectionChange,
+}) => {
+  const t = useOnboardingTheme();
+  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(
+    (chip: string) => {
+      if (submitted) return;
+      if (multiSelect) {
+        setSelected((prev) => {
+          if (prev.includes(chip)) return prev.filter((c) => c !== chip);
+          if (maxSelections && prev.length >= maxSelections) return prev;
+          return [...prev, chip];
+        });
+      } else {
+        setSelected([chip]);
+      }
+    },
+    [submitted, multiSelect, maxSelections],
+  );
+
+  const handleSubmit = useCallback(() => {
+    if (!selected.length || !onSelect || submitted) return;
+    setSubmitted(true);
+    onSelect(multiSelect ? selected : selected[0]!);
+  }, [selected, onSelect, submitted, multiSelect]);
+
+  return (
+    <CardLayout
+      title={title}
+      subtitle={maxSelections ? `Select up to ${maxSelections}` : undefined}
+      footer={
+        <Button
+          title={submitLabel}
+          onPress={handleSubmit}
+          variant="primary"
+          disabled={selected.length === 0 || submitted}
+        />
+      }
+    >
+      <View style={[styles.chipsRow, { gap: t.spacing.sm + t.spacing.xs }]}>
+        {chips.map((chip) => (
+          <ChipItem
+            key={chip}
+            chip={chip}
+            isSelected={selected.includes(chip)}
+            multiSelect={multiSelect}
+            onToggle={toggle}
+          />
+        ))}
+      </View>
+    </CardLayout>
+  );
+};
+
+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.",
+  component: React.memo(_ChipSelectCard) as WireAIComponent["component"],
+  propsSchema: schema,
+  defaultProps: { multiSelect: true, submitLabel: "Continue" },
+};
+
+const styles = StyleSheet.create({
+  chipsRow: { flexDirection: "row", flexWrap: "wrap" },
+  chip: { borderWidth: 1.5, flexDirection: "row", alignItems: "center", gap: 6, overflow: "hidden" },
+  fillOverlay: { borderWidth: 1.5 },
+  chipLabel: { fontWeight: "600" },
+  check: { fontSize: 13, fontWeight: "800", lineHeight: 15 },
+});

package/src/cards/InterstitialCard.tsx

@@ -0,0 +1,299 @@
+/**
+ * InterstitialCard — a mid-flow "value" screen (the Duolingo / Cal-AI beat): an
+ * illustration + a short motivational line + a single Continue button. It is NOT a
+ * question — it builds momentum and reinforces what the user is committing to,
+ * which is one of the biggest retention levers in great onboarding.
+ *
+ * Artwork resolves in order so the screen is NEVER a blank box: the host's named
+ * `illustration` (brand SVG/Lottie, keeping the kit dependency-free) → a
+ * backend-supplied `imageUrl` via RN <Image> (which self-heals to art on load
+ * error) → a named `illustrationFallback` (defaults to "momentum", always present
+ * in the kit's default registry).
+ *
+ * A minimum display window keeps the momentum beat from flashing past when the next
+ * card is already cached: Continue is disabled for MIN_DISPLAY_MS after mount.
+ *
+ * Motion (design-refs/EXTRACTED-SPEC.md rows 11-13): art and title fade-up in
+ * sequence (500ms ease-wire, 100ms stagger); the optional `items` (short lines
+ * referencing what the user already said) tick on one by one (90ms stagger),
+ * each check popping 200ms after its row — "work being done", not a slideshow.
+ * Reduce motion: everything rendered at its final frame at once.
+ *
+ * On Continue it sends "continue" back to the backend so the flow advances; the
+ * submitted-state guard makes the tap idempotent.
+ */
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { Animated, Easing, Image, StyleSheet, Text, View } from "react-native";
+import { z } from "zod";
+import type { InjectedProps, WireAIComponent } from "wireai-rn";
+import { useOnboardingTheme } from "../theme/ThemeContext";
+import { bodyStyle, headingStyle } from "../theme/typography";
+import { useIllustration } from "../components/Illustration";
+import { Button } from "../components/Button";
+import { CardLayout } from "../components/CardLayout";
+import {
+  CHECK_SPRING,
+  INTERSTITIAL_CHECK_SCALE_FROM,
+  INTERSTITIAL_HEAD_MS,
+  INTERSTITIAL_HEAD_STAGGER_MS,
+  INTERSTITIAL_ITEM_MS,
+  WIRE_BEZIER,
+  interstitialCheckDelay,
+  scaledMs,
+  interstitialItemDelay,
+} from "../motion/motionSpec";
+import { useReducedMotion } from "../motion/useReducedMotion";
+
+const easeWire = Easing.bezier(...WIRE_BEZIER);
+const RISE_PX = 10;
+
+const schema = z.object({
+  title: z.string().describe("Short, warm headline for the value/momentum moment"),
+  body: z
+    .string()
+    .optional()
+    .describe("One or two supporting lines that reflect the user's answers back and build momentum"),
+  items: z
+    .array(z.string())
+    .max(4)
+    .optional()
+    .describe(
+      "2-3 very short 'work being done' lines that each reference something the user already answered (e.g. 'Sized for a small team'). Shown as ticked items appearing in sequence. Prefer these over `body` when you have concrete answers to reflect back.",
+    ),
+  illustration: z
+    .string()
+    .optional()
+    .describe(
+      "Name of an app-provided illustration to show (the app's registry decides the artwork). Prefer this over imageUrl.",
+    ),
+  imageUrl: z
+    .string()
+    .url()
+    .refine((v) => v.startsWith("https://"), "imageUrl must be an https URL")
+    .optional()
+    .describe(
+      "Fallback remote HTTPS image URL, used only when no named illustration is registered. A non-https or malformed value is rejected and degrades to the named-illustration fallback.",
+    ),
+  illustrationFallback: z
+    .string()
+    .optional()
+    .describe(
+      "Named illustration to show when neither `illustration` nor `imageUrl` resolves (or the image fails to load). Defaults to the kit's always-present 'momentum' art so the screen is never blank.",
+    ),
+  ctaLabel: z.string().optional().describe("Continue button label, default: Continue"),
+});
+
+// Minimum time the momentum screen stays interactive-locked, so it never flashes past
+// when the next card is already prefetched/cached.
+const MIN_DISPLAY_MS = 500;
+
+type Props = z.infer<typeof schema> &
+  InjectedProps & {
+    onSubmit?: (value: string) => void;
+    onPress?: (label: string) => void;
+  };
+
+/** One ticked "work" row: fades up on its stagger slot, then the check pops. */
+const _WorkItem: React.FC<{ text: string; index: number; reduced: boolean }> = ({
+  text,
+  index,
+  reduced,
+}) => {
+  const t = useOnboardingTheme();
+  const rowT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+  const checkT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+
+  useEffect(() => {
+    if (reduced) {
+      rowT.setValue(1);
+      checkT.setValue(1);
+      return;
+    }
+    const anims = [
+      Animated.timing(rowT, {
+        toValue: 1,
+        duration: scaledMs(INTERSTITIAL_ITEM_MS),
+        delay: scaledMs(interstitialItemDelay(index)),
+        easing: easeWire,
+        useNativeDriver: true,
+      }),
+      Animated.spring(checkT, {
+        toValue: 1,
+        delay: scaledMs(interstitialCheckDelay(index)),
+        friction: CHECK_SPRING.friction,
+        tension: CHECK_SPRING.tension,
+        useNativeDriver: true,
+      }),
+    ];
+    anims.forEach((a) => a.start());
+    return () => anims.forEach((a) => a.stop());
+  }, [reduced, index, rowT, checkT]);
+
+  const rise = rowT.interpolate({ inputRange: [0, 1], outputRange: [RISE_PX, 0] });
+  const checkScale = checkT.interpolate({
+    inputRange: [0, 1],
+    outputRange: [INTERSTITIAL_CHECK_SCALE_FROM, 1],
+  });
+
+  return (
+    <Animated.View
+      style={[styles.itemRow, { gap: t.spacing.sm + t.spacing.xs, opacity: rowT, transform: [{ translateY: rise }] }]}
+    >
+      <View
+        style={[
+          styles.itemBadge,
+          { backgroundColor: t.colors.primarySoft, borderRadius: t.radius.full },
+        ]}
+      >
+        <Animated.Text
+          style={[
+            styles.itemCheck,
+            { color: t.colors.primary, opacity: checkT, transform: [{ scale: checkScale }] },
+          ]}
+        >
+          ✓
+        </Animated.Text>
+      </View>
+      <Text style={[bodyStyle(t.fonts), styles.itemText, { color: t.colors.text }]}>{text}</Text>
+    </Animated.View>
+  );
+};
+const WorkItem = React.memo(_WorkItem);
+
+const _InterstitialCard: React.FC<Props> = ({
+  title,
+  body,
+  items,
+  illustration,
+  imageUrl,
+  illustrationFallback,
+  ctaLabel = "Continue",
+  onSubmit,
+  onPress,
+}) => {
+  const t = useOnboardingTheme();
+  const reduced = useReducedMotion();
+  const node = useIllustration(illustration);
+  const fallbackNode = useIllustration(illustrationFallback);
+  const [submitted, setSubmitted] = useState(false);
+  const [imgFailed, setImgFailed] = useState(false);
+  // Keep the momentum beat on screen for at least MIN_DISPLAY_MS before Continue is tappable.
+  const [canAdvance, setCanAdvance] = useState(false);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setCanAdvance(true), MIN_DISPLAY_MS);
+    return () => clearTimeout(timer);
+  }, []);
+
+  // Head reveal: art then title (then body) fade-up, 500ms ease-wire, 100ms stagger.
+  // Reduce motion: final frame immediately (the shell handoff supplies the short fade).
+  const artT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+  const titleT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+  const bodyT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+  useEffect(() => {
+    if (reduced) {
+      artT.setValue(1);
+      titleT.setValue(1);
+      bodyT.setValue(1);
+      return;
+    }
+    const rise = (value: Animated.Value, delay: number) =>
+      Animated.timing(value, {
+        toValue: 1,
+        duration: scaledMs(INTERSTITIAL_HEAD_MS),
+        delay,
+        easing: easeWire,
+        useNativeDriver: true,
+      });
+    const anims = [
+      rise(artT, 0),
+      rise(titleT, scaledMs(INTERSTITIAL_HEAD_STAGGER_MS)),
+      rise(bodyT, scaledMs(INTERSTITIAL_HEAD_STAGGER_MS * 2)),
+    ];
+    anims.forEach((a) => a.start());
+    return () => anims.forEach((a) => a.stop());
+  }, [reduced, artT, titleT, bodyT]);
+
+  const riseStyle = (value: Animated.Value) => ({
+    opacity: value,
+    transform: [{ translateY: value.interpolate({ inputRange: [0, 1], outputRange: [RISE_PX, 0] }) }],
+  });
+
+  const handleContinue = useCallback(() => {
+    if (submitted || !canAdvance) return;
+    setSubmitted(true);
+    if (onSubmit) onSubmit("continue");
+    else if (onPress) onPress(ctaLabel);
+  }, [submitted, canAdvance, onSubmit, onPress, ctaLabel]);
+
+  // Resolution order — a broken/missing image must never leave a blank box:
+  // named illustration → remote image (until it errors) → named fallback art.
+  const showImage = !node && !!imageUrl && !imgFailed;
+  const art = node ?? (showImage ? undefined : fallbackNode);
+
+  return (
+    <CardLayout
+      align="center"
+      footer={
+        <Button
+          title={ctaLabel}
+          onPress={handleContinue}
+          variant="primary"
+          disabled={submitted || !canAdvance}
+        />
+      }
+    >
+      <View style={[styles.center, { gap: t.spacing.md }]}>
+        <Animated.View style={[styles.fullWidth, riseStyle(artT)]}>
+          {showImage ? (
+            <Image
+              source={{ uri: imageUrl }}
+              style={styles.image}
+              resizeMode="contain"
+              onError={() => setImgFailed(true)}
+            />
+          ) : art ? (
+            <View style={styles.art}>{art}</View>
+          ) : null}
+        </Animated.View>
+
+        <Animated.View style={riseStyle(titleT)}>
+          <Text style={[headingStyle(t.fonts), { color: t.colors.text, textAlign: "center" }]}>{title}</Text>
+        </Animated.View>
+
+        {items?.length ? (
+          <View style={[styles.items, { gap: t.spacing.md, marginTop: t.spacing.sm }]}>
+            {items.map((item, i) => (
+              <WorkItem key={item} text={item} index={i} reduced={reduced} />
+            ))}
+          </View>
+        ) : body ? (
+          <Animated.View style={riseStyle(bodyT)}>
+            <Text style={[bodyStyle(t.fonts), { color: t.colors.textMuted, textAlign: "center" }]}>{body}</Text>
+          </Animated.View>
+        ) : null}
+      </View>
+    </CardLayout>
+  );
+};
+
+export const InterstitialCard: WireAIComponent = {
+  name: "InterstitialCard",
+  description:
+    "Use ONCE mid-flow (never first, never last) as a momentum/value screen between questions — an illustration + a warm line that reflects answers back, like Duolingo/Cal-AI. NOT a question; the user just taps Continue. Set `illustration` to an app-registered artwork name. Prefer `items` (2-3 short ticked lines, each reflecting a real answer) when you have the signal. Skip it if you don't have enough signal to make the line specific.",
+  component: React.memo(_InterstitialCard) as WireAIComponent["component"],
+  propsSchema: schema,
+  defaultProps: { ctaLabel: "Continue", illustrationFallback: "momentum" },
+};
+
+const styles = StyleSheet.create({
+  center: { width: "100%", alignItems: "center", justifyContent: "center" },
+  fullWidth: { width: "100%", alignItems: "center" },
+  art: { alignItems: "center", justifyContent: "center" },
+  image: { width: "100%", height: 200 },
+  items: { width: "100%", alignSelf: "stretch" },
+  itemRow: { flexDirection: "row", alignItems: "center" },
+  itemBadge: { width: 24, height: 24, alignItems: "center", justifyContent: "center" },
+  itemCheck: { fontSize: 13, fontWeight: "800", lineHeight: 15 },
+  itemText: { flex: 1 },
+});

package/src/cards/NumberStepperCard.tsx

@@ -0,0 +1,121 @@
+/**
+ * Themed NumberStepperCard — drop-in for the OSS SDK's NumberStepperCard. Same
+ * `name`, `propsSchema`, `defaultProps`, and `onSubmit(value: number)` contract.
+ * Keeps the SDK's defensive numeric coercion so a malformed LLM payload can never
+ * feed NaN/Infinity into layout math.
+ */
+import React, { useCallback, useState } from "react";
+import { Pressable, StyleSheet, Text, View } from "react-native";
+import { z } from "zod";
+import type { InjectedProps, WireAIComponent } from "wireai-rn";
+import { useOnboardingTheme } from "../theme/ThemeContext";
+import { captionStyle, headingStyle } from "../theme/typography";
+import { Button } from "../components/Button";
+import { CardLayout } from "../components/CardLayout";
+
+const schema = z.object({
+  label: z.string().describe("What is being counted, e.g. 'Number of days' or 'Travellers'"),
+  min: z.number().optional().describe("Minimum value, default 1"),
+  max: z.number().optional().describe("Maximum value, default 30"),
+  defaultValue: z.number().optional().describe("Starting value"),
+  step: z.number().optional().describe("Increment per tap, default 1"),
+  unit: z.string().optional().describe("Unit label shown next to value, e.g. 'days' or 'people'"),
+  submitLabel: z.string().optional().describe("Confirm button label, default: Confirm"),
+});
+
+type Props = z.infer<typeof schema> &
+  InjectedProps & {
+    onSubmit?: (value: number) => void;
+  };
+
+const safeNum = (n: unknown, fallback: number): number =>
+  typeof n === "number" && Number.isFinite(n) ? n : fallback;
+
+const _NumberStepperCard: React.FC<Props> = ({
+  label,
+  min,
+  max,
+  defaultValue,
+  step,
+  unit,
+  submitLabel = "Confirm",
+  onSubmit,
+}) => {
+  const t = useOnboardingTheme();
+
+  const safeMin = safeNum(min, 1);
+  const safeMaxRaw = safeNum(max, 30);
+  const safeMax = safeMaxRaw < safeMin ? safeMin : safeMaxRaw;
+  const safeStepRaw = safeNum(step, 1);
+  const safeStep = safeStepRaw > 0 ? safeStepRaw : 1;
+  const safeDefault = safeNum(defaultValue, safeMin);
+
+  const [value, setValue] = useState(Math.min(Math.max(safeDefault, safeMin), safeMax));
+  const [submitted, setSubmitted] = useState(false);
+
+  const handleDecrement = useCallback(() => {
+    if (!submitted) setValue((v) => Math.max(v - safeStep, safeMin));
+  }, [submitted, safeStep, safeMin]);
+
+  const handleIncrement = useCallback(() => {
+    if (!submitted) setValue((v) => Math.min(v + safeStep, safeMax));
+  }, [submitted, safeStep, safeMax]);
+
+  const handleSubmit = useCallback(() => {
+    if (!submitted) {
+      setSubmitted(true);
+      onSubmit?.(value);
+    }
+  }, [submitted, onSubmit, value]);
+
+  const atMin = value <= safeMin;
+  const atMax = value >= safeMax;
+
+  const stepBtnStyle = (disabled: boolean) => [
+    styles.stepBtn,
+    { borderRadius: t.radius.full, backgroundColor: t.colors.background, borderColor: disabled ? t.colors.border : t.colors.primary },
+  ];
+
+  return (
+    <CardLayout
+      title={label}
+      align="center"
+      footer={
+        <Button title={submitLabel} onPress={handleSubmit} variant="primary" disabled={submitted} />
+      }
+    >
+      <View style={{ gap: t.spacing.md, alignItems: "center" }}>
+        <View style={[styles.stepper, { gap: t.spacing.lg }]}>
+          <Pressable onPress={atMin || submitted ? undefined : handleDecrement} disabled={atMin || submitted} style={stepBtnStyle(atMin)}>
+            <Text style={[headingStyle(t.fonts), { color: atMin ? t.colors.textMuted : t.colors.primary }]}>{"−"}</Text>
+          </Pressable>
+          <View style={styles.valueBox}>
+            <Text style={[headingStyle(t.fonts), { color: t.colors.primary }]}>{String(value)}</Text>
+            {unit ? <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted }]}>{unit}</Text> : null}
+          </View>
+          <Pressable onPress={atMax || submitted ? undefined : handleIncrement} disabled={atMax || submitted} style={stepBtnStyle(atMax)}>
+            <Text style={[headingStyle(t.fonts), { color: atMax ? t.colors.textMuted : t.colors.primary }]}>{"+"}</Text>
+          </Pressable>
+        </View>
+        <Text style={[captionStyle(t.fonts), { color: t.colors.textMuted, textAlign: "center" }]}>
+          {`${safeMin} – ${safeMax}${unit ? ` ${unit}` : ""}`}
+        </Text>
+      </View>
+    </CardLayout>
+  );
+};
+
+export const NumberStepperCard: WireAIComponent = {
+  name: "NumberStepperCard",
+  description:
+    "Use for any bounded numeric input: days, people, portions, budget tiers, ratings. Best for ranges 1–99. Set unit (e.g. 'days', 'people') for clarity.",
+  component: React.memo(_NumberStepperCard) as WireAIComponent["component"],
+  propsSchema: schema,
+  defaultProps: { min: 1, max: 30, defaultValue: 1, step: 1, submitLabel: "Confirm" },
+};
+
+const styles = StyleSheet.create({
+  stepper: { flexDirection: "row", alignItems: "center", justifyContent: "center" },
+  stepBtn: { width: 44, height: 44, borderWidth: 2, alignItems: "center", justifyContent: "center" },
+  valueBox: { alignItems: "center", minWidth: 80 },
+});