@wireai/activation 0.7.0 → 0.9.0

package/src/context/deviceId.ts

@@ -0,0 +1,43 @@
+/**
+ * deviceId — mint a stable, NON-PII, per-install device id the kit owns when the host supplies
+ * none. This is the headline of "device fully automatic": the analytics façade auto-mints ONE id,
+ * persists it via the host's `storage` abstraction, and reuses it on every subsequent open — so
+ * `user_context.device_key` is ALWAYS present and the server's review/questionnaire gating +
+ * A/B stickiness (both key on `device_key`) work out of the box, with zero host wiring.
+ *
+ * WHY it is NOT PII and adds NO dependency (the kit's hard rules):
+ *   The id is a random token generated from `Date.now()` + `Math.random()` — it carries NO hardware
+ *   identifier, NO IDFA/GAID, NO fingerprint. It is a first-party per-install correlation key, the
+ *   same privacy category as a first-party cookie: it groups a single install's sessions and cannot
+ *   identify a person or be joined across apps. There is NO `uuid` (or any) dependency — a
+ *   time+random scheme is sufficient because the id is minted ONCE and then persisted, so global
+ *   uniqueness across the fleet is not required (a per-install collision is astronomically unlikely
+ *   and inconsequential — worst case two installs share a bucket).
+ *
+ * A host that wants its OWN device id still wins: pass `WireUserContext.deviceKey` and the kit uses
+ * that verbatim and never mints/persists an auto id.
+ */
+
+/** Prefix so an auto-minted id is visibly the kit's (distinguishable from a host-supplied `deviceKey`). */
+export const AUTO_DEVICE_ID_PREFIX = "wdev_";
+
+/** The storage key the façade persists the auto-minted id under (namespaced per `appId`). */
+export const deviceIdStorageKey = (appId?: string): string =>
+  `wireai:analytics:deviceKey:${appId ?? "default"}`;
+
+/** One 32-bit base-36 chunk of randomness. Two chunks are concatenated for a wider token. */
+const randomChunk = (): string =>
+  Math.floor(Math.random() * 0x100000000)
+    .toString(36)
+    .padStart(6, "0");
+
+/**
+ * Mint a fresh per-install device id. Dependency-free (`Date.now()` + `Math.random()`), never
+ * throws, and returns a NEW value on every call — the façade mints ONCE and persists, so this is
+ * called at most once per install (then the persisted value is reused). Two random chunks plus the
+ * timestamp keep the token wide enough that a per-install collision is not a practical concern.
+ */
+export const mintDeviceId = (): string => {
+  const time = Date.now().toString(36);
+  return `${AUTO_DEVICE_ID_PREFIX}${time}_${randomChunk()}${randomChunk()}`;
+};

package/src/device/appVersion.ts

@@ -9,10 +9,20 @@
  * so the breakdown works out of the box. An explicit `config.appVersion` always WINS over this.
  *
  * WHY it adds NO dependency (the kit's hard rule): `expo-constants` / `expo-application` are read
- * through a GUARDED, VARIABLE-specifier `require`. Passing a variable (not a string literal) keeps
- * Metro/esbuild from statically resolving the module, so a host that does NOT have it installed
- * (e.g. bare React Native) never fails to bundle — the require simply throws at runtime and is
- * swallowed. Nothing is added to `package.json`; nothing is forced on the host.
+ * through a GUARDED require with a STRING-LITERAL specifier, inside a try/catch. Both halves are
+ * required: the literal is what lets Metro COLLECT the dep, and the try/catch is what marks it
+ * OPTIONAL, so an absent module becomes a `null` dependencyMap entry whose require throws "Cannot
+ * find module" straight into the catch. (`withWireOnboarding` in metro/index.js adds a stub-to-
+ * empty-module safety net for hosts that disable Metro's `allowOptionalDependencies`.) Nothing is
+ * added to `package.json`; nothing is forced on the host.
+ *
+ * The specifier MUST stay a literal. A variable specifier (`const req = require; req(name)`) is not
+ * "lazier" — it is broken: Metro collects dependencies statically, so a variable collects NOTHING,
+ * the module never enters the bundle, and the aliased `require` is Metro's own numeric-id-keyed
+ * `metroRequire`, which can never resolve a package-name string. That shape is why this function
+ * returned `undefined` on every host despite `expo-constants` being installed, which silently
+ * emptied the `by_app_version` breakdown this module exists to fill. See icons/expoIcons.ts for
+ * the full autopsy, and reviews/storeReview.ts for the literal-specifier counter-example.
  *
  * PRIVACY: an app version string is not PII and identifies no user or device, so surfacing it
  * changes no App Privacy / Data Safety declaration (same guarantee as the rest of deviceContext).
@@ -36,13 +46,24 @@ export const coerceVersion = (value: unknown): string | undefined => {
 };
 
 /**
- * Guarded runtime require. `moduleName` is a VARIABLE (a parameter), so bundlers cannot statically
- * resolve it — a host without the module never fails to build; the call just throws and is caught.
+ * Guarded runtime require.
+ *
+ * Every specifier below is a STRING LITERAL, because that is the only shape Metro's dependency
+ * collector matches (callee literally `require`, argument literally a string). The `moduleName`
+ * parameter exists only to keep the `OptionalRequire` seam shape for tests; an unrecognised name
+ * resolves to undefined. See the header for why the old variable-specifier shape could not work.
  */
 const runtimeRequire: OptionalRequire = (moduleName) => {
+  if (typeof require !== "function") return undefined;
   try {
-    if (typeof require !== "function") return undefined;
-    return require(moduleName);
+    switch (moduleName) {
+      case "expo-constants":
+        return require("expo-constants");
+      case "expo-application":
+        return require("expo-application");
+      default:
+        return undefined;
+    }
   } catch {
     return undefined;
   }

package/src/device/deviceContext.ts

@@ -21,6 +21,7 @@
 import { Dimensions, I18nManager, Platform } from "react-native";
 
 import { detectAppVersion } from "./appVersion";
+import { detectNativeModel } from "./deviceModel";
 
 /** Coarse device class. iOS uses the reported interface idiom; else a screen-size heuristic. */
 export type DeviceFormFactor = "phone" | "tablet";
@@ -36,7 +37,15 @@ export type DeviceContext = {
   osVersion?: string;
   /** Android device brand (e.g. "samsung"). Android only. */
   brand?: string;
-  /** Android device model (e.g. "SM-G991B"). Android only. */
+  /**
+   * Device model. On Android it is read directly from `Platform.constants.Model` (e.g. "SM-G991B").
+   * iOS `Platform.constants` exposes NO model, so on iOS it is a BEST-EFFORT read of `expo-device`'s
+   * `modelName` ("iPhone 14 Pro"), falling back to `modelId` ("iPhone15,2") — dependency-free via a
+   * guarded require (see device/deviceModel.ts). ASYMMETRY: without `expo-device` installed, iOS
+   * `model` is omitted (there is no dependency-free iOS model in the already-used RN surface, and the
+   * kit will not add a native dep for it); Android needs no extra module. Not PII (a device class,
+   * not a unique id), so it changes no privacy-label declaration.
+   */
   model?: string;
   /** iOS interface idiom ("phone" | "pad" | …), when reported. iOS only. */
   interfaceIdiom?: string;
@@ -125,6 +134,10 @@ export const collectDeviceContext = (): DeviceContext => {
         ctx.interfaceIdiom = idiom;
         iosIdiom = idiom;
       }
+      // iOS has no model in `Platform.constants`; best-effort via `expo-device` (adds no dep,
+      // omitted when the module is absent — see device/deviceModel.ts).
+      const iosModel = detectNativeModel();
+      if (iosModel) ctx.model = iosModel;
     }
   } catch {
     // ignore per-OS constant reads

package/src/device/deviceModel.ts

@@ -0,0 +1,106 @@
+/**
+ * deviceModel — best-effort, DEPENDENCY-FREE detection of the device MODEL on iOS.
+ *
+ * WHY this exists (the asymmetry it closes): `collectDeviceContext` already reports `device.model`
+ * on Android straight from `Platform.constants.Model` (e.g. "SM-G991B"), but iOS `Platform.constants`
+ * exposes NO model — only `osVersion` / `interfaceIdiom`. So the analytics `by_model` breakdown was
+ * Android-only. This module fills the iOS gap with the SAME zero-dependency technique the kit already
+ * uses for `appVersion` (see device/appVersion.ts): a GUARDED, STRING-LITERAL `require` of the common
+ * Expo `expo-device` module, inside a try/catch — the literal is what lets Metro COLLECT the dep and
+ * the try/catch is what marks it OPTIONAL, so an absent module degrades instead of failing the build.
+ * (`withWireOnboarding` in metro/index.js adds a stub-to-empty-module safety net for hosts that
+ * disable Metro's `allowOptionalDependencies`.) If the host has it, iOS gets a model out of the box;
+ * if not, the read yields `undefined` and iOS `model` stays omitted — nothing is forced, and nothing
+ * is added to `package.json`.
+ *
+ * The specifier MUST stay a literal. A variable specifier (`const req = require; req(name)`) collects
+ * NOTHING under Metro's static dependency collector, so the module never enters the bundle and the
+ * aliased `require` — really Metro's numeric-id-keyed `metroRequire` — can never resolve a package
+ * name. See icons/expoIcons.ts for the full autopsy.
+ *
+ * WHY it is NOT PII: `expo-device`'s `modelName` ("iPhone 14 Pro") and `modelId` ("iPhone15,2") are a
+ * device CLASS shared by millions of units — the same privacy category as the Android `Model` the kit
+ * already sends. It is NOT a unique device id / IDFA / fingerprint, so surfacing it changes no App
+ * Privacy / Data Safety declaration (identical guarantee to the rest of deviceContext). It deliberately
+ * does NOT read `expo-device`'s `deviceName` (that is the user-set name, e.g. "Malik's iPhone", and IS
+ * personal data).
+ *
+ * NEVER THROWS: every read is guarded; a missing/odd value yields `undefined`, never an exception.
+ */
+
+// Metro injects a module-scoped `require`; it is ABSENT in a pure-ESM runtime. 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 runtime require. */
+export type OptionalRequire = (moduleName: string) => unknown;
+
+/** Trim + reject non-strings/empties so we only ever emit a real model string. */
+const coerceModel = (value: unknown): string | undefined => {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+};
+
+/**
+ * Guarded runtime require.
+ *
+ * The specifier is a STRING LITERAL, because that is the only shape Metro's dependency collector
+ * matches (callee literally `require`, argument literally a string). The `moduleName` parameter
+ * exists only to keep the `OptionalRequire` seam shape for tests; an unrecognised name resolves to
+ * undefined. (See the twin guard in ./appVersion.ts.)
+ */
+const runtimeRequire: OptionalRequire = (moduleName) => {
+  if (moduleName !== "expo-device") return undefined;
+  if (typeof require !== "function") return undefined;
+  try {
+    return require("expo-device");
+  } catch {
+    return undefined;
+  }
+};
+
+/** Read a module's `default` (Expo modules are often 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;
+  if (def && typeof def === "object") return def as Record<string, unknown>;
+  return mod as Record<string, unknown>;
+};
+
+/** Resolve a module namespace, swallowing a throwing require (an uninstalled module throws). */
+const safeInterop = (
+  requireModule: OptionalRequire,
+  moduleName: string,
+): Record<string, unknown> | undefined => {
+  try {
+    return interop(requireModule(moduleName));
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Detect the device model via `expo-device`, preferring the human-readable `modelName`
+ * ("iPhone 14 Pro") and falling back to the identifier `modelId` ("iPhone15,2"). Returns the first
+ * real string, or `undefined` when `expo-device` is absent. Pure and never throws.
+ *
+ * `requireModule` is injectable so tests can exercise the "found" path without the native module;
+ * production defaults to the guarded runtime require above.
+ */
+export const detectNativeModel = (
+  requireModule: OptionalRequire = runtimeRequire,
+): string | undefined => {
+  try {
+    const device = safeInterop(requireModule, "expo-device");
+    if (device) {
+      const modelName = coerceModel(device.modelName);
+      if (modelName) return modelName;
+      const modelId = coerceModel(device.modelId);
+      if (modelId) return modelId;
+    }
+  } catch {
+    // Any unexpected read error → undefined; analytics must never crash onboarding.
+  }
+  return undefined;
+};

package/src/features/cache.ts

@@ -21,7 +21,7 @@ export const DEFAULT_FEATURES_TTL_MS = 300_000;
 /** Ceiling on the storage read so a hung adapter degrades to defaults, never a stuck resolve. */
 const READ_TIMEOUT_MS = 1_500;
 
-/** Storage key for a tenant's cached flags, e.g. `wireai:features:myelino`. */
+/** Storage key for a tenant's cached flags, e.g. `wireai:features:acme`. */
 export const featuresCacheKey = (appId?: string): string =>
   `wireai:features:${appId && appId.length > 0 ? appId : "default"}`;
 

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;
+  }
+};