@wireai/activation 0.7.0 → 0.9.0

package/dist/{types-CMuOexw0.d.ts → types-CKFhyrMu.d.ts}

@@ -13,7 +13,7 @@ type WireOnboardingStorage = {
  * this can't be resumed server-side anyway, so the client mints fresh past it.
  */
 declare const DEFAULT_SESSION_TTL_MS = 3600000;
-/** Storage key for an app's cached session, e.g. `wireai:session:myelino`. */
+/** Storage key for an app's cached session, e.g. `wireai:session:acme`. */
 declare const sessionStorageKey: (appId: string) => string;
 /** Resolved session for a mount: the id to use + whether it was restored from storage. */
 type LoadedSession = {

package/dist/{types-A6pTxIZV.d.mts → types-CNUqMK0D.d.mts}

@@ -1,6 +1,6 @@
 import { O as OnboardingTheme } from './types-BKfpdZzX.mjs';
-import { C as CoachmarkStorage } from './types-GL_hQ0TN.mjs';
-import { W as WireFeatures, a as WireFeaturesConfig } from './types-CMuOexw0.mjs';
+import { C as CoachmarkStorage } from './types-BcmagF6K.mjs';
+import { W as WireFeatures, a as WireFeaturesConfig } from './types-CKFhyrMu.mjs';
 
 /**
  * The firing verdict — the SAME contract on both sides of the seam. `decideReview`
@@ -11,6 +11,18 @@ interface ReviewDecision {
     fire: boolean;
     reason?: string;
 }
+/**
+ * The `GET /v1/reviews/decision` response: `ReviewDecision` plus the additive `arm`.
+ *
+ * `arm` is the firing experiment's sticky assignment for this device/session. Echo it back in
+ * the submission's `meta.firing_arm` and the server keeps it verbatim (`_stamp_firing_arm`:
+ * "an arm the kit already echoed is left as-is"); omit it and the server recomputes from the
+ * sticky hash. Echoing is what makes per-arm attribution survive a later reweighting of the
+ * experiment, so a host running one should pass it through.
+ */
+interface ReviewDecisionResponse extends ReviewDecision {
+    arm?: string | null;
+}
 /** Where to route a rating: 5 stars → the store, 1-4 → the feedback form. */
 type RatingRoute = "store" | "feedback";
 /**
@@ -149,4 +161,4 @@ interface ReviewGateController {
     markResolved: () => void;
 }
 
-export type { ReviewGateProps as R, UseReviewGateOptions as U, ReviewPresentation as a, ReviewGateController as b, ReviewDecision as c, ReviewStoreConfig as d, RatingRoute as e, ReviewConfig as f, ReviewGateEvent as g, ReviewGateEventName as h, ReviewSubmission as i, ReviewTarget as j };
+export type { ReviewGateProps as R, UseReviewGateOptions as U, ReviewPresentation as a, ReviewGateController as b, ReviewDecision as c, ReviewStoreConfig as d, RatingRoute as e, ReviewConfig as f, ReviewDecisionResponse as g, ReviewGateEvent as h, ReviewGateEventName as i, ReviewSubmission as j, ReviewTarget as k };

package/metro/index.d.ts

@@ -16,12 +16,20 @@ export interface WithWireOnboardingOptions {
    * When omitted, the kit resolves from the installed package.
    */
   source?: string;
+  /**
+   * Extra specifiers to treat as optional, i.e. resolve to an EMPTY module instead of
+   * failing the build when they are not installed. Added to the kit's own
+   * `OPTIONAL_MODULES` list, never replacing it.
+   */
+  optionalModules?: string[];
 }
 
 /**
  * Non-destructively wire the @wireai/activation kit into an existing Metro config:
  * pins single-instance deps to the app's copy, optionally maps the kit specifier
- * to source + watches it. Mutates and returns the same config object.
+ * to source + watches it, and makes the kit's optional modules genuinely optional
+ * (an absent one resolves to an empty module instead of breaking the build).
+ * Mutates and returns the same config object.
  */
 export function withWireOnboarding<TConfig extends Record<string, any>>(
   config: TConfig,
@@ -30,3 +38,12 @@ export function withWireOnboarding<TConfig extends Record<string, any>>(
 
 /** The deps pinned to the app's single copy. */
 export const SINGLE_INSTANCE_DEPS: readonly ['react', 'react-native', 'wireai-rn', 'zod'];
+
+/**
+ * The modules the kit reads through a guarded require and can live without. When one of
+ * these does not resolve, `withWireOnboarding` maps it to an empty module so the host
+ * still bundles and the feature degrades (icon → null, analytics field omitted, native
+ * review → store-URL fallback). Modules the kit imports statically are deliberately NOT
+ * in this list — stubbing those would hide a real build error.
+ */
+export const OPTIONAL_MODULES: readonly string[];

package/metro/index.js

@@ -26,6 +26,8 @@
  * @param {string} [options.source]  Absolute path to the kit's `src/` dir. When
  *   set, the kit specifier maps here (source consumption) and it's added to
  *   watchFolders; when omitted, the kit resolves from the installed package.
+ * @param {string[]} [options.optionalModules]  Extra specifiers to treat as
+ *   optional (see OPTIONAL_MODULES). Added to the kit's list, never replacing it.
  * @returns {object} The same config object, mutated in place and returned.
  */
 'use strict';
@@ -35,6 +37,60 @@ const path = require('path');
 /** Deps that MUST resolve to the app's single copy (a 2nd React instance crashes RN). */
 const SINGLE_INSTANCE_DEPS = ['react', 'react-native', 'wireai-rn', 'zod'];
 
+/**
+ * Modules the kit reads through a GUARDED require/import and is designed to live without.
+ *
+ * ── HOW OPTIONAL DEPS ACTUALLY WORK UNDER METRO (verified, not folklore) ────────────────
+ *
+ * Metro has NO runtime module resolution: every specifier is resolved when the bundle is BUILT.
+ * But it DOES have a first-class optional-dependency mechanism, and it needs two things:
+ *
+ *   1. a STRING-LITERAL specifier — Metro's collector only matches `require("literal")` /
+ *      `import("literal")`. A variable specifier collects NOTHING, so the module never enters
+ *      the bundle at all (that was the 0.8.0 bug; see src/icons/expoIcons.ts), and
+ *   2. the call sitting inside a TRY/CATCH — that is literally how Metro decides a dependency
+ *      is optional (`isOptional`), and it only counts when the transformer has
+ *      `allowOptionalDependencies` enabled. Expo's `getDefaultConfig` enables it; plain
+ *      `metro-config` defaults it to FALSE.
+ *
+ * When both hold and the module is absent, Metro puts `null` in the module's dependencyMap, and
+ * `metroRequire(null, "name")` throws "Cannot find module" — synchronously, from metroRequire
+ * itself, so the caller's own catch swallows it. Verified in a real bundle: haptics' dependencyMap
+ * is `[355,null,1300]` with `expo-haptics` uninstalled. So DO NOT "simplify" a try/catch away from
+ * around a guarded require: the try/catch is load-bearing, and removing it turns an absent peer
+ * into a hard build failure.
+ *
+ * ── WHY THIS LIST STILL EXISTS ─────────────────────────────────────────────────────────
+ *
+ * Mechanism (2) is off by default in bare Metro (`allowOptionalDependencies: false`), and a host
+ * can turn it off. There, an absent optional module fails the BUILD with "Unable to resolve
+ * module". So `resolveRequest` below maps an absent module on this list to an EMPTY module, which
+ * lands on each caller's existing "peer absent" degradation path (no exports on the namespace →
+ * undefined → icon renders null / analytics field omitted / native review → store-URL fallback).
+ * It is a safety net that makes optionality independent of the host's Metro settings — not the
+ * only thing holding it up.
+ *
+ * ONLY modules read through a guarded require/import belong here. A module the kit imports
+ * STATICALLY at module scope (react-native-reanimated, expo-blur,
+ * @blazejkustra/react-native-onboarding) must NOT be stubbed: an empty module would turn a loud
+ * build-time "Unable to resolve module" into a silent `undefined` component that crashes at
+ * render, which is strictly worse. `test/canary/metroResolution.test.tsx` keeps this list in sync
+ * with the source by asking Metro which deps it marks optional.
+ */
+const OPTIONAL_MODULES = [
+  // src/icons/expoIcons.ts — icon families; absent → WireIcon renders null.
+  '@expo/vector-icons',
+  // src/device/appVersion.ts — analytics `by_app_version`; absent → field omitted.
+  'expo-constants',
+  'expo-application',
+  // src/device/deviceModel.ts — analytics iOS `by_model`; absent → field omitted.
+  'expo-device',
+  // src/reviews/storeReview.ts — native review prompt; absent → store-URL fallback.
+  'expo-store-review',
+  // src/haptics/haptics.ts — haptic feedback; absent → silent no-op.
+  'expo-haptics',
+];
+
 function withWireOnboarding(config, options) {
   const opts = options || {};
   const appRoot = opts.appRoot || process.cwd();
@@ -67,6 +123,29 @@ function withWireOnboarding(config, options) {
     ...existingExtra,
   };
 
+  // ── resolveRequest: make the optional modules genuinely optional ────────────
+  // Non-destructive by construction: the app's own resolveRequest (or Metro's default) is asked
+  // FIRST and keeps full authority. We only act on the failure of an OPTIONAL specifier, turning
+  // "Unable to resolve module" into an empty module so a host that never installed the peer still
+  // bundles. A non-optional module's failure is rethrown untouched — a missing `react` must stay
+  // a hard, loud build error.
+  const optional = new Set([...OPTIONAL_MODULES, ...(opts.optionalModules || [])]);
+  const upstream = resolver.resolveRequest;
+
+  resolver.resolveRequest = (context, moduleName, platform) => {
+    const resolve = upstream || context.resolveRequest;
+    try {
+      return resolve(context, moduleName, platform);
+    } catch (error) {
+      // Match the package root and its subpaths ('@expo/vector-icons/build/Icons').
+      const isOptional = [...optional].some(
+        (name) => moduleName === name || moduleName.startsWith(name + '/'),
+      );
+      if (!isOptional) throw error;
+      return { type: 'empty' };
+    }
+  };
+
   // ── watchFolders: add the kit source so Metro reads + HMRs it ───────────────
   if (source) {
     const existingWatch = Array.isArray(config.watchFolders) ? config.watchFolders : [];
@@ -81,3 +160,4 @@ function withWireOnboarding(config, options) {
 module.exports = { withWireOnboarding };
 module.exports.withWireOnboarding = withWireOnboarding;
 module.exports.SINGLE_INSTANCE_DEPS = SINGLE_INSTANCE_DEPS;
+module.exports.OPTIONAL_MODULES = OPTIONAL_MODULES;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "private": false,
   "description": "Premium, fully-themable drop-in AI onboarding kit for React Native / Expo, on top of the open-source wireai-rn SDK.",
   "author": "Malik Chohra <malik@getwireai.com>",
@@ -143,7 +143,9 @@
   },
   "peerDependencies": {
     "@blazejkustra/react-native-onboarding": ">=1",
+    "@expo/vector-icons": ">=14",
     "expo-blur": ">=13",
+    "expo-haptics": ">=13",
     "expo-store-review": ">=6",
     "react": ">=18.0.0",
     "react-native": ">=0.73.0",
@@ -156,12 +158,18 @@
     "zod": {
       "optional": false
     },
+    "@expo/vector-icons": {
+      "optional": true
+    },
     "react-native-reanimated": {
       "optional": true
     },
     "expo-blur": {
       "optional": true
     },
+    "expo-haptics": {
+      "optional": true
+    },
     "expo-store-review": {
       "optional": true
     },

package/src/WireOnboarding.tsx

@@ -16,6 +16,7 @@ import { WireAIProvider, type LocalLLMConfig } from "wireai-rn";
 import { OnboardingThemeProvider } from "./theme/ThemeContext";
 import { IllustrationProvider } from "./components/Illustration";
 import { defaultIllustrations } from "./illustrations/defaultIllustrations";
+import { IconRegistryProvider } from "./icons/IconRegistry";
 import { LoadingScreen } from "./components/LoadingScreen";
 import { OnboardingFlow, DEFAULT_COPY } from "./OnboardingFlow";
 import { onboardingComponents } from "./cards";
@@ -36,6 +37,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   theme,
   components,
   illustrations,
+  icons,
   validators,
   onComplete,
   onSkip,
@@ -229,6 +231,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   return (
     <OnboardingThemeProvider theme={theme}>
       <IllustrationProvider registry={{ ...defaultIllustrations, ...illustrations }}>
+        <IconRegistryProvider registry={icons}>
         <WireAIProvider llm={llm} components={cards}>
           <OnboardingFlow
             validators={validators}
@@ -248,6 +251,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
             clientContext={clientContext}
           />
         </WireAIProvider>
+        </IconRegistryProvider>
       </IllustrationProvider>
     </OnboardingThemeProvider>
   );

package/src/analytics/analyticsFacade.ts

@@ -31,6 +31,7 @@ import { getCurrentSessionId } from "./currentSession";
 import { createEventQueue, type EventQueue, type EventQueueOptions } from "./eventQueue";
 import { makeSessionId, type ClientEvent } from "./reportClientEvent";
 import { resolveUserContext, type WireUserContext } from "../context/userContext";
+import { mintDeviceId, deviceIdStorageKey } from "../context/deviceId";
 import { sanitizeUserId } from "../identity/userIdentity";
 
 /** Arbitrary non-PII event properties. Serialized to the event's `meta` (a JSON string) on the wire. */
@@ -67,8 +68,12 @@ export type CreateAnalyticsConfig = {
   /**
    * The rich {@link WireUserContext} to stamp onto every event's `user_context` (device key, opaque
    * user id, opt-in email, arbitrary `extra`). Passed ONCE here at init; updatable post-mount via
-   * {@link Analytics.setUserContext} (e.g. attach `userId`/`userEmail` at login). Optional — omit it
-   * and events carry only the device context, exactly as before.
+   * {@link Analytics.setUserContext} (e.g. attach `userId`/`userEmail` at login). Optional.
+   *
+   * NOTE on `deviceKey`: you do NOT need to supply one. When omitted, the kit auto-mints a stable,
+   * non-PII per-install `device_key`, persists it via `storage`, and reuses it every open (in-memory
+   * fallback without storage) — so `user_context.device_key` is ALWAYS present for the server's
+   * review/questionnaire gating + A/B stickiness. Supply `deviceKey` only to use your OWN id (it wins).
    */
   userContext?: WireUserContext;
 };
@@ -124,12 +129,47 @@ export const createAnalytics = (
   const resolveSessionId = (): string =>
     config.sessionId ?? getCurrentSessionId() ?? instanceSessionId;
 
-  // A provider (not a fixed value) so `networkType` + the current session id are evaluated fresh
-  // on every enqueue.
+  // The mutable rich user-context: seeded at init, updated via `setUserContext`. Resolved fresh on
+  // every event so a post-mount update (login) takes effect immediately. Declared before the envelope
+  // provider so the provider can read the current `userContext.appVersion` (see below).
+  let userContext: WireUserContext = { ...(config.userContext ?? {}) };
+
+  // Auto device id (the headline: "device" fully automatic). When the host supplies NO `deviceKey`,
+  // the kit mints ONE stable, non-PII per-install id, PERSISTS it via the host `storage`, and reuses it
+  // on every subsequent open — so `user_context.device_key` is ALWAYS present (the server's
+  // review/questionnaire gating + A/B stickiness both key on it) with zero host wiring. A host-supplied
+  // `deviceKey` still wins (see `applyContext`). Falls back to an in-memory id (stable for this
+  // instance) when no storage is available.
+  const hostDeviceKeyAtInit =
+    typeof config.userContext?.deviceKey === "string" && config.userContext.deviceKey.trim()
+      ? config.userContext.deviceKey.trim()
+      : undefined;
+  // Minted synchronously so `device_key` is never missing, even before the async storage read resolves.
+  let autoDeviceKey = mintDeviceId();
+  if (config.storage && !hostDeviceKeyAtInit) {
+    const storage = config.storage;
+    const deviceKey = deviceIdStorageKey(config.appId);
+    void storage
+      .getItem(deviceKey)
+      .then((saved) => {
+        const persisted = typeof saved === "string" && saved.trim() ? saved.trim() : undefined;
+        // Reuse the persisted per-install id across opens; on first run persist the freshly minted one.
+        if (persisted) autoDeviceKey = persisted;
+        else void storage.setItem(deviceKey, autoDeviceKey).catch(() => {});
+      })
+      .catch(() => {});
+  }
+
+  // A provider (not a fixed value) so `networkType`, the current session id, AND the effective app
+  // version are evaluated fresh on every enqueue. An explicit `WireUserContext.appVersion` (a host that
+  // set the version ONLY inside `userContext`) now flows into `device.appVersion` too — not just
+  // `user_context.app_version` — so the server's `by_app_version` breakdown (which reads
+  // `device.appVersion`) agrees. Explicit wins over the auto-detected device version;
+  // `buildContextEnvelope` keeps the auto value when neither is set.
   const envelope = (): ContextEnvelope =>
     buildContextEnvelope({
       sessionId: resolveSessionId(),
-      appVersion: config.appVersion,
+      appVersion: userContext.appVersion ?? config.appVersion,
       appBuild: config.appBuild,
       networkType: config.networkType,
     });
@@ -142,10 +182,6 @@ export const createAnalytics = (
     ...options,
   });
 
-  // The mutable rich user-context: seeded at init, updated via `setUserContext`. Resolved fresh on
-  // every event so a post-mount update (login) takes effect immediately.
-  let userContext: WireUserContext = { ...(config.userContext ?? {}) };
-
   // Per-session, in-memory user binding. Seeded from the init context, then persisted across
   // launches when storage is provided.
   let boundUserId: string | undefined = sanitizeUserId(config.userContext?.userId);
@@ -165,7 +201,16 @@ export const createAnalytics = (
   // opt-in user_email, namespaced `custom.*`) and the top-level opaque `user_id`. Never overwrites a
   // key the caller already set (so `identify`'s explicit `user_id` and any caller `user_context` win).
   const applyContext = (event: ClientEvent): void => {
-    const resolved = resolveUserContext(userContext, { autoAppVersion: config.appVersion });
+    // Host `deviceKey` wins; otherwise the auto-minted/persisted per-install id fills it in so
+    // `user_context.device_key` is always present.
+    const hostDeviceKey =
+      typeof userContext.deviceKey === "string" && userContext.deviceKey.trim()
+        ? userContext.deviceKey
+        : undefined;
+    const resolved = resolveUserContext(
+      { ...userContext, deviceKey: hostDeviceKey ?? autoDeviceKey },
+      { autoAppVersion: config.appVersion },
+    );
     if (resolved.userContext) {
       event.user_context = { ...resolved.userContext, ...(event.user_context ?? {}) };
     }

package/src/analytics/currentSession.ts

@@ -6,7 +6,7 @@
  * post `app.session_started` with it — so the SERVER knows that id. But other client paths
  * (`identify`, host `app_event`s through the analytics façade) used to reference a DIFFERENT id
  * (a frozen per-instance id), which the server had never seen, so it back-filled a synthetic
- * `session_started` — inflating session counts (the Morrow/Myelino "phantom-session" bug).
+ * `session_started` — inflating session counts (the "phantom-session" bug).
  *
  * This registry is the single seam that lets those paths reuse the LIVE per-open session id the
  * server already ingested. `reportSessionStart` writes the current id here on every open; the façade

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" },