@wireai/activation 0.8.0 → 0.9.1

package/src/components/ModalPaneHost.tsx

@@ -0,0 +1,141 @@
+/**
+ * ModalPaneHost — "slide between panes inside a CenteredModal", the shared primitive
+ * behind BOTH the review gate's phase changes and the questionnaire's step changes.
+ * One primitive, two call sites: the two gates must never drift apart on feel.
+ *
+ * It does NOT reimplement the slide. `CardHandoff` already owns the design's
+ * "cards hand off, they don't cut" motion (exit left 180ms / enter right 220ms, 80ms
+ * lead, reduce-motion crossfade), so this delegates to it in `layout="auto"` mode and
+ * adds the ONE thing a modal needs that a full-screen flow does not: a card that
+ * resizes instead of snapping.
+ *
+ * WHY the height animation exists: the CenteredModal card is auto-height, so the moment
+ * a taller/shorter pane mounts, the card would jump to its new height in a single frame
+ * while the old pane is still sliding out — the exact "jarring change" the slide was
+ * added to remove. Measuring the pane and easing the card to it keeps one continuous
+ * surface.
+ *
+ * WHY it is the only non-native-driven value in the kit: height is a layout prop, so it
+ * cannot ride the native driver. That is a deliberate, bounded exception — ONE property
+ * on ONE small card, for ~220ms, while nothing is scrolling. The panes' own opacity and
+ * translate (inside CardHandoff) stay on the native driver, and the two values live on
+ * different views, so they never contend. Everything else in the kit stays transform/
+ * opacity-only.
+ *
+ * Height is eased ONLY on a pane change. A multiline box growing as the user types also
+ * fires onLayout, and animating that would make typing feel laggy — those resize
+ * instantly. Reduce motion: the height snaps too (movement removed, crossfade kept).
+ *
+ * `header` is the STATIC slot: chrome that belongs to the card rather than to any one pane
+ * (the questionnaire's back icon + step dots). It sits inside the measured container but
+ * OUTSIDE the CardHandoff, which buys two things a caller cannot get by rendering it above
+ * the host:
+ *   1. It never slides, so it is never DUPLICATED mid-handoff. Anything inside CardHandoff
+ *      exists twice for ~300ms (the outgoing layer and the incoming one) — fine for a
+ *      question that is genuinely changing, wrong for chrome that is not. Two dot rows
+ *      cross-fading past each other is a bug, not a transition.
+ *   2. Its size is part of the measured height, so dropping the header (form → thanks)
+ *      rides the same eased resize as the pane swap instead of snapping the card.
+ */
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { Animated, Easing, StyleSheet, View, type LayoutChangeEvent } from "react-native";
+
+import { CARD_ENTER_MS, WIRE_BEZIER, scaledMs } from "../motion/motionSpec";
+import { useReducedMotion } from "../motion/useReducedMotion";
+import { CardHandoff, type CardHandoffDirection } from "./CardHandoff";
+
+const easeWire = Easing.bezier(...WIRE_BEZIER);
+
+export type ModalPaneHostProps = {
+  /** Identity of the pane on screen (phase name / step key). A change runs the handoff. */
+  paneKey: string;
+  /** Travel direction — "backward" mirrors the slide when the user steps back. */
+  direction?: CardHandoffDirection;
+  /**
+   * Card-level chrome pinned above the sliding pane: measured with it, but never moved
+   * and never duplicated by the handoff. Omit it (or pass null) and nothing renders —
+   * dropping it between pane changes animates the card's height rather than snapping it.
+   * The node owns its own bottom spacing; the host adds none (it has no theme).
+   */
+  header?: React.ReactNode;
+  children: React.ReactNode;
+};
+
+const _ModalPaneHost: React.FC<ModalPaneHostProps> = ({
+  paneKey,
+  direction = "forward",
+  header,
+  children,
+}) => {
+  const reduced = useReducedMotion();
+  const height = useRef(new Animated.Value(0)).current;
+  /** Last height we settled on. null until the first real measurement lands. */
+  const measured = useRef<number | null>(null);
+  /** Drives the height style on only AFTER a real measurement, so nothing renders at 0. */
+  const [sized, setSized] = useState(false);
+  /** Set when the pane changed, cleared by the next measurement it causes. */
+  const paneChanged = useRef(false);
+  const running = useRef<Animated.CompositeAnimation | null>(null);
+
+  // Runs on mount and on every pane change, always BEFORE the resulting onLayout (which
+  // arrives from native after the commit) — so the next measurement knows why it fired.
+  useEffect(() => {
+    paneChanged.current = true;
+  }, [paneKey]);
+
+  useEffect(() => () => running.current?.stop(), []);
+
+  const onLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      const next = Math.round(event.nativeEvent.layout.height);
+      if (!next) return;
+      const previous = measured.current;
+      if (previous !== null && Math.abs(previous - next) < 1) return;
+
+      const first = previous === null;
+      const ease = !first && !reduced && paneChanged.current;
+      paneChanged.current = false;
+      measured.current = next;
+      running.current?.stop();
+
+      // First measurement, a reduce-motion user, or a plain content resize (typing):
+      // take the new height immediately.
+      if (!ease) {
+        height.setValue(next);
+        if (first) setSized(true);
+        return;
+      }
+
+      const anim = Animated.timing(height, {
+        toValue: next,
+        duration: scaledMs(CARD_ENTER_MS),
+        easing: easeWire,
+        // height is layout, not transform — see the header note.
+        useNativeDriver: false,
+      });
+      running.current = anim;
+      anim.start();
+    },
+    [height, reduced],
+  );
+
+  return (
+    <Animated.View style={sized ? { height, overflow: "hidden" } : undefined}>
+      <View onLayout={onLayout} style={styles.pane}>
+        {header}
+        <CardHandoff transitionKey={paneKey} direction={direction} layout="auto" variant="slide">
+          {children}
+        </CardHandoff>
+      </View>
+    </Animated.View>
+  );
+};
+
+export const ModalPaneHost = React.memo(_ModalPaneHost);
+ModalPaneHost.displayName = "ModalPaneHost";
+
+const styles = StyleSheet.create({
+  pane: { width: "100%" },
+});
+
+export default ModalPaneHost;

package/src/components/StepDots.tsx

@@ -0,0 +1,112 @@
+/**
+ * StepDots — the "how many steps, and which one am I on" row for a multi-step modal.
+ *
+ * It replaces the questionnaire's textual counter ("Question 2 of 3"). Malik's device
+ * feedback 2026-07-16: "instead of 1 out of 3 or 2-3, had points on top to explain the
+ * number of steps". A dot row says the same two things — how long this is, how far in you
+ * are — without spending a line of copy next to the question the user should be reading.
+ *
+ * NOT the same component as `StepProgress`: that one is the ONBOARDING flow's bar, and it
+ * deliberately refuses to show a count because the flow's length is model-decided and a
+ * number would be a promise the model may not keep. The questionnaire is the opposite
+ * case — a fixed 3-field server contract — so here the count is knowable and honest.
+ *
+ * Motion: a dot fills by crossfading a `colors.primary` layer over a `colors.border` base,
+ * at the design system's selection-fill duration (SELECT_FILL_MS, spec rows 2/3/5/6 — the
+ * same token every other "this is now selected" fill in the kit uses). Opacity only, on the
+ * native driver: no color interpolation (that would force `useNativeDriver: false`, and the
+ * kit keeps its one non-native exception in ModalPaneHost's height).
+ *
+ * Reduce motion: `stateChangeDuration` collapses the fill to 0ms, so the state snaps —
+ * the house convention for state changes (see StepProgress).
+ *
+ * Accessibility: sighted users read the dots; screen readers must not be handed three
+ * unlabelled circles. The ROW is one progressbar node carrying "Step 2 of 3" plus the
+ * numeric value, and the dots themselves are hidden as decoration.
+ */
+import React, { useEffect, useRef } from "react";
+import { Animated, Easing, StyleSheet, View } from "react-native";
+
+import { SELECT_FILL_MS, WIRE_BEZIER, scaledMs, stateChangeDuration } from "../motion/motionSpec";
+import { useReducedMotion } from "../motion/useReducedMotion";
+import type { OnboardingTheme } from "../theme/types";
+
+const easeWire = Easing.bezier(...WIRE_BEZIER);
+
+export type StepDotsProps = {
+  /** The (already merged) active theme — dots read `colors.border` / `colors.primary`. */
+  theme: OnboardingTheme;
+  /** How many steps there are (how many dots to draw). */
+  count: number;
+  /** 0-based index of the step on screen. */
+  index: number;
+};
+
+type DotProps = {
+  theme: OnboardingTheme;
+  /** True for the current step and every step behind it — the row reads as progress. */
+  filled: boolean;
+  size: number;
+};
+
+const Dot: React.FC<DotProps> = ({ theme, filled, size }) => {
+  const reduced = useReducedMotion();
+  const fill = useRef(new Animated.Value(filled ? 1 : 0)).current;
+
+  useEffect(() => {
+    const anim = Animated.timing(fill, {
+      toValue: filled ? 1 : 0,
+      duration: scaledMs(stateChangeDuration(reduced, SELECT_FILL_MS)),
+      easing: easeWire,
+      useNativeDriver: true,
+    });
+    anim.start();
+    return () => anim.stop();
+  }, [fill, filled, reduced]);
+
+  return (
+    <View
+      style={{
+        width: size,
+        height: size,
+        borderRadius: theme.radius.full,
+        backgroundColor: theme.colors.border,
+      }}
+    >
+      <Animated.View
+        style={[
+          StyleSheet.absoluteFill,
+          {
+            borderRadius: theme.radius.full,
+            backgroundColor: theme.colors.primary,
+            opacity: fill,
+          },
+        ]}
+      />
+    </View>
+  );
+};
+
+const _StepDots: React.FC<StepDotsProps> = ({ theme, count, index }) => (
+  <View
+    style={[styles.row, { gap: theme.spacing.sm }]}
+    accessibilityRole="progressbar"
+    accessibilityLabel={`Step ${index + 1} of ${count}`}
+    accessibilityValue={{ min: 1, max: count, now: index + 1 }}
+  >
+    {Array.from({ length: count }, (_, i) => (
+      <View key={i} accessibilityElementsHidden importantForAccessibility="no-hide-descendants">
+        <Dot theme={theme} filled={i <= index} size={theme.spacing.sm} />
+      </View>
+    ))}
+  </View>
+);
+
+export const StepDots = React.memo(_StepDots);
+StepDots.displayName = "StepDots";
+
+const styles = StyleSheet.create({
+  row: { flexDirection: "row", alignItems: "center", justifyContent: "center" },
+});
+
+export default StepDots;

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/deviceModel.ts

@@ -5,10 +5,18 @@
  * 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, VARIABLE-specifier `require` of the
- * common Expo `expo-device` module. If the host has it, iOS gets a model out of the box; if not, the
- * require simply throws and is swallowed and iOS `model` stays omitted — nothing is forced, nothing
- * is added to `package.json`, and a host without `expo-device` never fails to bundle.
+ * 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
@@ -35,13 +43,18 @@ const coerceModel = (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.
+ *
+ * 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 {
-    if (typeof require !== "function") return undefined;
-    return require(moduleName);
+    return require("expo-device");
   } catch {
     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: {},
+});