@wireai/activation 0.8.0 → 0.9.0

package/src/haptics/expo-haptics.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Ambient type for the OPTIONAL peer `expo-haptics`.
+ *
+ * The kit never hard-depends on it: it is loaded lazily via a guarded dynamic import
+ * and externalized from the build, so the core kit installs nothing. This declaration
+ * lets the module typecheck whether or not the host has the package installed. When the
+ * host does install it, Metro/the bundler resolves the real module at runtime; when it
+ * doesn't, the guarded import rejects and every haptic becomes a silent no-op.
+ *
+ * Mirrors `src/reviews/expo-store-review.d.ts` exactly — same optional-peer contract.
+ */
+declare module "expo-haptics" {
+  /** Impact strengths (a physical "tap" against the UI). */
+  export enum ImpactFeedbackStyle {
+    Light = "light",
+    Medium = "medium",
+    Heavy = "heavy",
+  }
+  /** Notification tones (the outcome of a task). */
+  export enum NotificationFeedbackType {
+    Success = "success",
+    Warning = "warning",
+    Error = "error",
+  }
+  /** The "value changed" tick — used for picking a star. */
+  export function selectionAsync(): Promise<void>;
+  /** A physical impact tap of the given strength. */
+  export function impactAsync(style?: ImpactFeedbackStyle): Promise<void>;
+  /** The task-outcome tone — used for the submit payoff. */
+  export function notificationAsync(type?: NotificationFeedbackType): Promise<void>;
+}

package/src/haptics/haptics.ts

@@ -0,0 +1,58 @@
+/**
+ * haptics.ts — the physical half of the kit's feedback layer: a tap you feel.
+ *
+ * `expo-haptics` is an OPTIONAL peer, loaded lazily via a guarded dynamic import so the
+ * core kit never depends on it — the exact contract `reviews/storeReview.ts` uses for
+ * `expo-store-review`. A host that has not installed it (or a platform without a taptic
+ * engine) simply feels nothing: every call resolves to `false` and NOTHING throws. A
+ * missed haptic must never break a gate.
+ *
+ * The module is deliberately fire-and-forget. Callers `void play(...)` from a press
+ * handler and never await it, so a slow/absent native module can't delay a tap.
+ *
+ * Tones map to intent, not to a device API:
+ *   • "selection" — a value changed (picking a star).
+ *   • "light"     — a light impact (moving to the next question).
+ *   • "success"   — a task completed (the submit payoff, under the done check).
+ *
+ * NOT gated on reduce-motion: `prefers-reduced-motion` is a VESTIBULAR accommodation about
+ * on-screen movement. Haptics are a non-visual channel and are often the accessibility
+ * affordance a reduce-motion user relies on, so silencing them here would be the wrong
+ * trade. Hosts that want no haptics leave `expo-haptics` uninstalled.
+ */
+
+/** What a haptic is for, in product terms. Mapped to the native API inside `play`. */
+export type HapticTone = "selection" | "light" | "success";
+
+/**
+ * Play a haptic when the optional peer is available. Resolves `true` when a haptic was
+ * actually requested, `false` when the peer is absent or the native call failed. NEVER
+ * throws and never rejects — the result is advisory (tests/analytics), not control flow.
+ */
+export const play = async (tone: HapticTone): Promise<boolean> => {
+  try {
+    const mod = await import("expo-haptics");
+    if (!mod) return false;
+    if (tone === "selection") {
+      await mod.selectionAsync();
+      return true;
+    }
+    if (tone === "light") {
+      await mod.impactAsync(mod.ImpactFeedbackStyle.Light);
+      return true;
+    }
+    await mod.notificationAsync(mod.NotificationFeedbackType.Success);
+    return true;
+  } catch {
+    // Peer not installed, unsupported platform, or the native call failed — stay silent.
+    return false;
+  }
+};
+
+/**
+ * Fire-and-forget `play`. The call site reads as the intent ("a star was tapped"), and a
+ * rejected/absent native module can never surface as an unhandled rejection.
+ */
+export const playHaptic = (tone: HapticTone): void => {
+  void play(tone);
+};

package/src/icons/IconRegistry.tsx

@@ -0,0 +1,53 @@
+/**
+ * Icon registry — the host's escape hatch, and the FIRST step of icon resolution.
+ *
+ * Deliberately the same shape and philosophy as the `illustrations` registry
+ * (components/Illustration.tsx): name → ReactNode, held in context, so an app can ship brand
+ * SVG / Lottie / Image nodes the kit never imports. Here it means a host can:
+ *
+ *   • override any vocabulary name with its own brand mark (`{ instagram: <MyIgGlyph/> }`), or
+ *   • supply icons WITHOUT installing `@expo/vector-icons` at all, or
+ *   • extend the vocabulary with names of its own — the AI emits `"my-thing"`, the host renders
+ *     it, and the kit needs no release.
+ *
+ *   <WireOnboarding icons={{ instagram: <BrandIg/> }} ... />
+ *
+ * A name the registry doesn't have falls through to `@expo/vector-icons`, then to no icon at
+ * all. See `WireIcon`.
+ */
+import React, { createContext, useContext, useMemo } from "react";
+
+export type WireIconRegistry = Record<string, React.ReactNode>;
+
+/** One shared empty registry so an unconfigured provider never allocates a fresh {} per render. */
+const EMPTY_REGISTRY: WireIconRegistry = {};
+
+const IconContext = createContext<WireIconRegistry>(EMPTY_REGISTRY);
+
+export type IconRegistryProviderProps = {
+  registry?: WireIconRegistry;
+  children: React.ReactNode;
+};
+
+export const IconRegistryProvider: React.FC<IconRegistryProviderProps> = ({
+  registry,
+  children,
+}) => {
+  const value = useMemo(() => registry ?? EMPTY_REGISTRY, [registry]);
+  return <IconContext.Provider value={value}>{children}</IconContext.Provider>;
+};
+
+/**
+ * Look up a host-supplied icon node by name. Returns undefined if absent.
+ *
+ * The OWN-property check matters here for the same reason it does in `vocabulary.ts`: the name
+ * is LLM-authored, and a bare `registry[name]` answers `"toString"` with an inherited function
+ * — which is truthy, so it would be handed to React as a child and blow up the card. An icon
+ * name must never be able to do that.
+ */
+export const useHostIcon = (name?: string): React.ReactNode | undefined => {
+  const registry = useContext(IconContext);
+  if (!name) return undefined;
+  if (!Object.prototype.hasOwnProperty.call(registry, name)) return undefined;
+  return registry[name];
+};

package/src/icons/WireIcon.tsx

@@ -0,0 +1,85 @@
+/**
+ * WireIcon — render one semantic icon name, or nothing at all.
+ *
+ * RESOLUTION ORDER (each step falls through to the next, never throws):
+ *   1. the host `icons` registry  — brand artwork, zero kit deps (IconRegistry.tsx)
+ *   2. `@expo/vector-icons`       — if the optional peer resolves (expoIcons.ts)
+ *   3. NOTHING                    — render null
+ *
+ * Step 3 is a FEATURE, not a failure mode. The AI emits icon names from a vocabulary that will
+ * keep growing, against production apps that ship on their own schedule (new store builds only,
+ * never OTA, so they cannot be force-updated). So an unknown, misspelled, hallucinated, or
+ * simply newer-than-this-client name MUST be a no-op: no crash, no broken-glyph tofu box, and
+ * no layout shift. Returning `null` (rather than a spacer or a placeholder) is what gives the
+ * last property — a row with an unresolvable icon lays out EXACTLY like a row with no icon,
+ * because the parent's flex `gap` adds no space for a null child.
+ *
+ * An icon is always DECORATIVE: the label carries the meaning, so the icon is hidden from
+ * assistive tech and never becomes the accessible name of its option.
+ */
+import React from "react";
+import { StyleSheet, View } from "react-native";
+
+import { resolveIconFamily, type OptionalRequire } from "./expoIcons";
+import { useHostIcon } from "./IconRegistry";
+import { lookupIconGlyph } from "./vocabulary";
+
+export type WireIconProps = {
+  /** A semantic name from the vocabulary (see vocabulary.ts). Unknown → renders nothing. */
+  name?: string;
+  /** Glyph size in px. */
+  size?: number;
+  /** Glyph color. Callers pass a THEME token — never a raw hex. */
+  color?: string;
+  /** Injectable resolver. TEST-ONLY seam; production uses the guarded runtime require. */
+  requireModule?: OptionalRequire;
+};
+
+const _WireIcon: React.FC<WireIconProps> = ({ name, size = 20, color, requireModule }) => {
+  // 1) Host artwork wins — it can also cover names outside the vocabulary entirely.
+  const hostIcon = useHostIcon(name);
+  if (hostIcon) {
+    return (
+      <View
+        style={styles.decorative}
+        accessible={false}
+        importantForAccessibility="no-hide-descendants"
+      >
+        {hostIcon}
+      </View>
+    );
+  }
+
+  // 2) The vocabulary → a concrete glyph, then the optional peer. Both may miss; both degrade.
+  const glyph = lookupIconGlyph(name);
+  if (!glyph) return null;
+
+  const Family = resolveIconFamily(glyph.family, requireModule);
+  if (!Family) return null;
+
+  return (
+    <View
+      style={styles.decorative}
+      accessible={false}
+      importantForAccessibility="no-hide-descendants"
+    >
+      <Family
+        name={glyph.name}
+        size={size}
+        color={color}
+        // Icons are sized by the layout, not the text scale — a large accessibility font must
+        // not blow up a card grid. The LABEL still scales, which is what carries the meaning.
+        allowFontScaling={false}
+      />
+    </View>
+  );
+};
+
+export const WireIcon = React.memo(_WireIcon);
+WireIcon.displayName = "WireIcon";
+
+const styles = StyleSheet.create({
+  // No size/margin of its own: the glyph decides its footprint, so an absent icon and a
+  // present one differ by exactly the glyph — never by a wrapper.
+  decorative: {},
+});

package/src/icons/expoIcons.ts

@@ -0,0 +1,165 @@
+/**
+ * expoIcons — resolve an `@expo/vector-icons` family, lazily and optionally.
+ *
+ * ── WHY THIS DOES NOT BREAK THE NO-NATIVE-DEPENDENCY POLICY ──────────────────────────────
+ *
+ * The policy (see `questionnaire/QuestionnaireGate.tsx`'s back-chevron note, `AnimatedSparkle`,
+ * `coachmarks/GestureHint`, `cards/StatusCard`'s Unicode STATUS_ICONS) says: no vector library
+ * is worth FORCING EVERY HOST INTO A NATIVE REBUILD. Read it precisely — what it forbids is
+ * forcing hosts, not the existence of an icon.
+ *
+ * `@expo/vector-icons` is an OPTIONAL peer:
+ *
+ *   • A host WITHOUT it installs the kit fine (optional peer → npm never fetches it) and renders
+ *     fine (icon → null, layout unchanged). To BUNDLE fine it must let Metro know the module is
+ *     allowed to be missing — see "OPTIONALITY IS A BUILD-TIME CONTRACT" below.
+ *   • A host WITH it gets real brand icons. Both live host apps already ship it
+ *     (`@expo/vector-icons ^15.0.3`), so neither needs a rebuild — which matters because
+ *     neither can be force-updated: both ship new store builds only and never OTA.
+ *   • A host that wants neither can override every name with its own artwork through the
+ *     `icons` registry, so the library is never on the critical path at all.
+ *
+ * ── THE SPECIFIER MUST BE A STRING LITERAL — THIS IS THE WHOLE BUG ───────────────────────
+ *
+ * DO NOT "restore" the old `const req = require; req(moduleName)` shape. It could never work,
+ * and it shipped broken in 0.8.0. What that shape actually did, proven in a real `expo export`
+ * bundle and in Expo SDK 55's runtime:
+ *
+ *   1. Metro collects dependencies STATICALLY, by matching a call whose callee is literally the
+ *      identifier `require` and whose argument is a STRING LITERAL. Aliasing `require` to a local
+ *      hid the call from the collector, so this module's dependencyMap was emitted EMPTY (`[]`)
+ *      and `@expo/vector-icons` was never put in the bundle at all.
+ *   2. At runtime the alias did NOT point at Node's `require`. Metro renames the free `require`
+ *      identifier to the module factory's require param, so `req` WAS `metroRequire`, whose
+ *      module registry is keyed by NUMERIC module ids. Handing it the string "@expo/vector-icons"
+ *      could never match a key, so it threw `Requiring unknown module "@expo/vector-icons"` —
+ *      even in a bundle that contained the module.
+ *   3. That throw never reached the `catch` below. Metro's own `guardedLoadModule` wraps the
+ *      load, catches the error FIRST, and routes it to `global.ErrorUtils.reportFatalError(e)`
+ *      instead of rethrowing (Expo SDK 55: `@expo/cli/build/metro-require/require.js:151-165`).
+ *      So the call returned `undefined` — icon silently null — AND logged a red fatal error. A
+ *      try/catch cannot guard a require that Metro never lets throw.
+ *
+ * A LITERAL `require("@expo/vector-icons")` is collected, is bundled, and resolves SYNCHRONOUSLY
+ * through the numeric dependencyMap — the same reason `reviews/storeReview.ts`'s literal
+ * `await import("expo-store-review")` has always worked. (The old comment here claimed the alias
+ * worked "exactly like expo-store-review". It was the opposite: storeReview's specifier is a
+ * literal, and that is precisely why it resolves and this one did not.)
+ *
+ * ── OPTIONALITY IS A BUILD-TIME CONTRACT, AND THE TRY/CATCH IS LOAD-BEARING ──────────────
+ *
+ * Metro has NO runtime resolution: every specifier is resolved when the bundle is built. It does
+ * have a real optional-dependency mechanism, and it needs BOTH halves of what is written below:
+ * a LITERAL specifier (so the dep is collected at all) AND the call inside a TRY/CATCH — that is
+ * literally how Metro marks a dependency `isOptional`. When the peer is absent, Metro then puts
+ * `null` in this module's dependencyMap and `metroRequire(null, "@expo/vector-icons")` throws
+ * "Cannot find module" from its own `moduleId === null` branch, BEFORE `guardedLoadModule` — so
+ * unlike the string-id path in the autopsy above, that throw really does land in the catch below.
+ * So do NOT "simplify" the try/catch away: it is what keeps the peer optional, not just tidy.
+ *
+ * That mechanism rides on the transformer's `allowOptionalDependencies`, which Expo enables by
+ * default but bare `metro-config` defaults to FALSE. For hosts in the second camp, the kit ships
+ * a safety net: `withWireOnboarding` (metro/index.js) installs a `resolveRequest` that maps an
+ * absent optional peer to an EMPTY module, landing on exactly the degradation path below (no
+ * families on the namespace → `undefined` → icon renders null).
+ */
+import type { WireIconFamily } from "./vocabulary";
+
+// Metro injects a module-scoped `require`; it is ABSENT in a pure-ESM runtime (the kit's own
+// tests run under `node --test` as ESM). Declared locally so this type-checks without ambient
+// Node types; the `typeof` guard keeps the reference ESM-safe.
+declare const require: ((id: string) => unknown) | undefined;
+
+/** A `require`-like resolver. Injectable in tests; production uses the guarded literal require. */
+export type OptionalRequire = (moduleName: string) => unknown;
+
+/**
+ * The minimal shape the kit uses from a vector-icons family. A COMPONENT TYPE, not a plain
+ * function: these are real React components (createIconSet output) and must be mounted via
+ * JSX/createElement, never invoked directly — calling one bypasses the reconciler and breaks
+ * the moment the family uses hooks or is a class.
+ */
+export type IconComponent = import("react").ComponentType<{
+  name: string;
+  size?: number;
+  color?: string;
+  allowFontScaling?: boolean;
+}>;
+
+/**
+ * The production resolver. The specifier is a LITERAL so Metro collects it (see the header); the
+ * `moduleName` parameter exists only to keep the `OptionalRequire` seam shape, so anything other
+ * than the one module this file owns resolves to undefined.
+ */
+const runtimeRequire: OptionalRequire = (moduleName) => {
+  if (moduleName !== "@expo/vector-icons") return undefined;
+  if (typeof require !== "function") return undefined;
+  try {
+    return require("@expo/vector-icons");
+  } catch {
+    return undefined;
+  }
+};
+
+/** Read a module's `default` (Expo modules are consumed as default exports) or the namespace. */
+const interop = (mod: unknown): Record<string, unknown> | undefined => {
+  if (!mod || typeof mod !== "object") return undefined;
+  const def = (mod as { default?: unknown }).default;
+  // `@expo/vector-icons` exposes the families as NAMED exports; prefer the namespace when it
+  // already carries them, and only fall back to `default` for a CJS-interop wrapper.
+  const ns = mod as Record<string, unknown>;
+  if (ns.MaterialCommunityIcons || ns.Ionicons) return ns;
+  if (def && typeof def === "object") return def as Record<string, unknown>;
+  return ns;
+};
+
+/**
+ * Narrow an unknown export to something mountable. A vector-icons family is either a function
+ * component or a class (`createIconSet` has returned both across versions), and React.memo /
+ * forwardRef wrappers are objects — so accept an object carrying a `$$typeof` too, and reject
+ * anything else rather than handing the reconciler a non-component.
+ */
+const asComponent = (value: unknown): IconComponent | undefined => {
+  if (typeof value === "function") return value as IconComponent;
+  if (value && typeof value === "object" && "$$typeof" in (value as object)) {
+    return value as IconComponent;
+  }
+  return undefined;
+};
+
+/**
+ * Module-level memo. `null` = "we looked and it is not there" (distinct from "not looked yet"),
+ * so an absent peer costs exactly one failed require per process, not one per rendered icon.
+ */
+let cached: Record<string, unknown> | null | undefined;
+
+/** Reset the memo. TEST-ONLY seam — production never calls it. */
+export const resetIconModuleCache = (): void => {
+  cached = undefined;
+};
+
+/**
+ * Resolve one icon family component, or undefined when the peer is absent/unresolvable.
+ * Never throws: an icon is decorative, so it must never be able to break a card.
+ *
+ * `requireModule` is injectable so tests can exercise BOTH the found and absent paths without
+ * installing the native peer (same convention as `detectAppVersion`).
+ */
+export const resolveIconFamily = (
+  family: WireIconFamily,
+  requireModule: OptionalRequire = runtimeRequire,
+): IconComponent | undefined => {
+  try {
+    if (cached === undefined || requireModule !== runtimeRequire) {
+      const resolved = interop(requireModule("@expo/vector-icons"));
+      // Don't poison the module memo from an injected test require.
+      if (requireModule === runtimeRequire) cached = resolved ?? null;
+      if (!resolved) return undefined;
+      return asComponent(resolved[family]);
+    }
+    if (cached === null) return undefined;
+    return asComponent(cached[family]);
+  } catch {
+    return undefined;
+  }
+};

package/src/icons/index.ts

@@ -0,0 +1,18 @@
+/**
+ * The icon module — a named semantic vocabulary the AI emits, resolved to real glyphs through
+ * an OPTIONAL peer, with a host override registry in front and a no-op behind. See
+ * `vocabulary.ts` for the contract and `expoIcons.ts` for why the optional peer honors the
+ * kit's no-forced-native-dependency policy rather than breaking it.
+ */
+export { WireIcon } from "./WireIcon";
+export type { WireIconProps } from "./WireIcon";
+export { IconRegistryProvider, useHostIcon } from "./IconRegistry";
+export type { WireIconRegistry, IconRegistryProviderProps } from "./IconRegistry";
+export {
+  WIRE_ICON_GLYPHS,
+  WIRE_ICON_NAMES,
+  lookupIconGlyph,
+} from "./vocabulary";
+export type { WireIconName, WireIconFamily, WireIconGlyph } from "./vocabulary";
+export { resolveIconFamily, resetIconModuleCache } from "./expoIcons";
+export type { OptionalRequire, IconComponent } from "./expoIcons";

package/src/icons/vocabulary.ts

@@ -0,0 +1,154 @@
+/**
+ * The Wire icon VOCABULARY — the stable, semantic contract between the AI and the kit.
+ *
+ * The model emits a plain semantic string (`"instagram"`, `"friend"`, `"wedding"`), never a
+ * raw icon-library glyph name. That indirection is the whole point:
+ *
+ *   • The model is never coupled to a library version. `@expo/vector-icons` renaming a glyph,
+ *     or a host swapping the library out for brand SVGs, changes THIS map — not the prompt,
+ *     not the server, and not a single stored answer.
+ *   • A host can override any name with its own artwork (see `IconRegistry`), so brand icons
+ *     need no kit change.
+ *   • An unknown name degrades to no icon (see `WireIcon`), which is why the vocabulary can
+ *     grow without a coordinated kit+server release.
+ *
+ * `WIRE_ICON_NAMES` is exported so the server/AI side can be taught the list verbatim — paste
+ * it into the prompt as the allowed `icon` values. Keep names SEMANTIC (what the option means)
+ * rather than visual (what the glyph looks like): the model reasons about meaning.
+ *
+ * Every glyph below was verified to exist in the `@expo/vector-icons` 15.0.3 glyphmaps that
+ * both live host apps already ship. MaterialCommunityIcons is the default family (the broadest
+ * single set); Ionicons covers the few brand logos MCI lacks (TikTok, Discord).
+ */
+
+/** The icon families this kit resolves out of `@expo/vector-icons`. Both are root exports. */
+export type WireIconFamily = "MaterialCommunityIcons" | "Ionicons";
+
+/** One vocabulary entry: the concrete glyph a semantic name resolves to. */
+export interface WireIconGlyph {
+  family: WireIconFamily;
+  /** The library's own glyph name — an INTERNAL detail. The AI never sees or emits this. */
+  name: string;
+}
+
+/**
+ * The semantic name → concrete glyph map. Grouped by the onboarding questions these actually
+ * serve: acquisition channels ("where did you hear about us"), intent/occasion ("what brings
+ * you here"), and a general-purpose set for everything else.
+ */
+export const WIRE_ICON_GLYPHS = {
+  // ── Acquisition channels ("where did you hear about us?") ──────────────────
+  instagram: { family: "MaterialCommunityIcons", name: "instagram" },
+  tiktok: { family: "Ionicons", name: "logo-tiktok" },
+  youtube: { family: "MaterialCommunityIcons", name: "youtube" },
+  facebook: { family: "MaterialCommunityIcons", name: "facebook" },
+  twitter: { family: "MaterialCommunityIcons", name: "twitter" },
+  reddit: { family: "MaterialCommunityIcons", name: "reddit" },
+  linkedin: { family: "MaterialCommunityIcons", name: "linkedin" },
+  discord: { family: "Ionicons", name: "logo-discord" },
+  whatsapp: { family: "MaterialCommunityIcons", name: "whatsapp" },
+  twitch: { family: "MaterialCommunityIcons", name: "twitch" },
+  snapchat: { family: "MaterialCommunityIcons", name: "snapchat" },
+  pinterest: { family: "MaterialCommunityIcons", name: "pinterest" },
+  google: { family: "MaterialCommunityIcons", name: "google" },
+  search: { family: "MaterialCommunityIcons", name: "magnify" },
+  friend: { family: "MaterialCommunityIcons", name: "account-heart" },
+  podcast: { family: "MaterialCommunityIcons", name: "podcast" },
+  blog: { family: "MaterialCommunityIcons", name: "post" },
+  newsletter: { family: "MaterialCommunityIcons", name: "email-outline" },
+  news: { family: "MaterialCommunityIcons", name: "newspaper" },
+  "app-store": { family: "MaterialCommunityIcons", name: "apple" },
+  ad: { family: "MaterialCommunityIcons", name: "bullhorn" },
+
+  // ── Intent / occasion ("what brings you here?") ────────────────────────────
+  wedding: { family: "MaterialCommunityIcons", name: "ring" },
+  birthday: { family: "MaterialCommunityIcons", name: "cake-variant" },
+  baby: { family: "MaterialCommunityIcons", name: "baby-carriage" },
+  travel: { family: "MaterialCommunityIcons", name: "airplane" },
+  work: { family: "MaterialCommunityIcons", name: "briefcase" },
+  celebration: { family: "MaterialCommunityIcons", name: "party-popper" },
+  store: { family: "MaterialCommunityIcons", name: "storefront" },
+  school: { family: "MaterialCommunityIcons", name: "school" },
+  team: { family: "MaterialCommunityIcons", name: "account-multiple" },
+  growth: { family: "MaterialCommunityIcons", name: "trending-up" },
+
+  // ── General purpose ────────────────────────────────────────────────────────
+  sparkle: { family: "MaterialCommunityIcons", name: "star-four-points" },
+  heart: { family: "MaterialCommunityIcons", name: "heart" },
+  star: { family: "MaterialCommunityIcons", name: "star" },
+  fire: { family: "MaterialCommunityIcons", name: "fire" },
+  target: { family: "MaterialCommunityIcons", name: "target" },
+  trophy: { family: "MaterialCommunityIcons", name: "trophy" },
+  rocket: { family: "MaterialCommunityIcons", name: "rocket-launch" },
+  clock: { family: "MaterialCommunityIcons", name: "clock-outline" },
+  calendar: { family: "MaterialCommunityIcons", name: "calendar-star" },
+  camera: { family: "MaterialCommunityIcons", name: "camera" },
+  image: { family: "MaterialCommunityIcons", name: "image" },
+  video: { family: "MaterialCommunityIcons", name: "video" },
+  mic: { family: "MaterialCommunityIcons", name: "microphone" },
+  music: { family: "MaterialCommunityIcons", name: "music" },
+  book: { family: "MaterialCommunityIcons", name: "book-open-variant" },
+  food: { family: "MaterialCommunityIcons", name: "silverware-fork-knife" },
+  coffee: { family: "MaterialCommunityIcons", name: "coffee" },
+  fitness: { family: "MaterialCommunityIcons", name: "dumbbell" },
+  health: { family: "MaterialCommunityIcons", name: "heart-pulse" },
+  meditation: { family: "MaterialCommunityIcons", name: "meditation" },
+  sleep: { family: "MaterialCommunityIcons", name: "sleep" },
+  brain: { family: "MaterialCommunityIcons", name: "brain" },
+  idea: { family: "MaterialCommunityIcons", name: "lightbulb-on" },
+  money: { family: "MaterialCommunityIcons", name: "cash" },
+  shopping: { family: "MaterialCommunityIcons", name: "cart" },
+  gift: { family: "MaterialCommunityIcons", name: "gift" },
+  home: { family: "MaterialCommunityIcons", name: "home" },
+  car: { family: "MaterialCommunityIcons", name: "car" },
+  pet: { family: "MaterialCommunityIcons", name: "paw" },
+  plant: { family: "MaterialCommunityIcons", name: "sprout" },
+  sun: { family: "MaterialCommunityIcons", name: "white-balance-sunny" },
+  moon: { family: "MaterialCommunityIcons", name: "weather-night" },
+  globe: { family: "MaterialCommunityIcons", name: "earth" },
+  "map-pin": { family: "MaterialCommunityIcons", name: "map-marker" },
+  compass: { family: "MaterialCommunityIcons", name: "compass" },
+  flag: { family: "MaterialCommunityIcons", name: "flag" },
+  bookmark: { family: "MaterialCommunityIcons", name: "bookmark" },
+  bell: { family: "MaterialCommunityIcons", name: "bell" },
+  mail: { family: "MaterialCommunityIcons", name: "email" },
+  phone: { family: "MaterialCommunityIcons", name: "phone" },
+  chat: { family: "MaterialCommunityIcons", name: "chat" },
+  user: { family: "MaterialCommunityIcons", name: "account" },
+  users: { family: "MaterialCommunityIcons", name: "account-group" },
+  settings: { family: "MaterialCommunityIcons", name: "cog" },
+  tools: { family: "MaterialCommunityIcons", name: "tools" },
+  puzzle: { family: "MaterialCommunityIcons", name: "puzzle" },
+  chart: { family: "MaterialCommunityIcons", name: "chart-line" },
+  shield: { family: "MaterialCommunityIcons", name: "shield-check" },
+  lock: { family: "MaterialCommunityIcons", name: "lock" },
+  cloud: { family: "MaterialCommunityIcons", name: "cloud" },
+  pencil: { family: "MaterialCommunityIcons", name: "pencil" },
+  check: { family: "MaterialCommunityIcons", name: "check-circle" },
+  plus: { family: "MaterialCommunityIcons", name: "plus-circle" },
+  question: { family: "MaterialCommunityIcons", name: "help-circle" },
+  other: { family: "MaterialCommunityIcons", name: "dots-horizontal-circle" },
+} as const satisfies Record<string, WireIconGlyph>;
+
+/** A name in the vocabulary. The card schemas accept any string and degrade — see `WireIcon`. */
+export type WireIconName = keyof typeof WIRE_ICON_GLYPHS;
+
+/**
+ * Every semantic name, as a plain array — the list to paste into the server/AI prompt as the
+ * allowed `icon` values. Sorted for a stable, diffable prompt.
+ */
+export const WIRE_ICON_NAMES: readonly string[] = Object.keys(WIRE_ICON_GLYPHS).sort();
+
+/**
+ * Look up a semantic name. Returns undefined for anything outside the vocabulary.
+ *
+ * The OWN-property check is load-bearing, not defensive noise: the name comes from an LLM, and
+ * a plain object lookup answers `"toString"` / `"constructor"` / `"valueOf"` with an inherited
+ * `Object.prototype` member. That would hand back a function where a `{family, name}` is
+ * expected — a non-glyph masquerading as one. Caught by the vocabulary canary.
+ */
+export const lookupIconGlyph = (name: string | undefined): WireIconGlyph | undefined => {
+  if (!name) return undefined;
+  if (!Object.prototype.hasOwnProperty.call(WIRE_ICON_GLYPHS, name)) return undefined;
+  return (WIRE_ICON_GLYPHS as Record<string, WireIconGlyph>)[name];
+};

package/src/index.ts

@@ -52,11 +52,31 @@ export {
   ChipSelectCard,
   TextInputCard,
   SelectionCard,
+  CardGridSelectCard,
   StatusCard,
   NumberStepperCard,
   InterstitialCard,
   onboardingComponents,
 } from "./cards";
+export type { CardOption } from "./cards";
+
+// ─── Icons (semantic vocabulary → optional @expo/vector-icons → nothing) ──────
+// WIRE_ICON_NAMES is the list to paste into the server/AI prompt as the allowed `icon` values.
+export {
+  WireIcon,
+  IconRegistryProvider,
+  useHostIcon,
+  WIRE_ICON_GLYPHS,
+  WIRE_ICON_NAMES,
+  lookupIconGlyph,
+} from "./icons";
+export type {
+  WireIconProps,
+  WireIconRegistry,
+  WireIconName,
+  WireIconFamily,
+  WireIconGlyph,
+} from "./icons";
 
 // ─── Flow internals (advanced) ────────────────────────────────────────────────
 export { OnboardingFlow } from "./OnboardingFlow";