@wireai/activation 0.8.0 → 0.9.1

package/dist/index.d.mts

@@ -1,13 +1,14 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import { o as WireOnboardingProps, p as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, q as OnboardingEvent, u as OnboardingCopy, a as ClientEventTarget, D as DeviceContext, C as ClientEvent, e as EnvelopeSource } from './currentSession-d9CrBxwe.mjs';
-export { A as AnalyticsEvent, b as ClientEventType, v as DeviceFormFactor, w as EXTRA_KEY_PREFIX, x as OnboardingProgress, R as RESERVED_USER_CONTEXT_KEYS, y as ResolveUserContextOptions, z as ResolvedUserContext, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, W as WireUserContext, B as collectDeviceContext, k as getCurrentSessionId, F as hashEmailFnv1a, G as isWireScalar, m as makeSessionId, H as namespaceExtra, r as reportClientEvent, l as reportClientEvents, n as resetCurrentSessionId, I as resolveUserContext, s as setCurrentSessionId, t as toAnalyticsEvent } from './currentSession-d9CrBxwe.mjs';
+import { o as WireOnboardingProps, p as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, q as OnboardingEvent, u as OnboardingCopy, a as ClientEventTarget, D as DeviceContext, C as ClientEvent, e as EnvelopeSource } from './currentSession-Bs2JfTJ8.mjs';
+export { A as AnalyticsEvent, b as ClientEventType, v as DeviceFormFactor, w as EXTRA_KEY_PREFIX, x as OnboardingProgress, R as RESERVED_USER_CONTEXT_KEYS, y as ResolveUserContextOptions, z as ResolvedUserContext, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, W as WireUserContext, B as collectDeviceContext, k as getCurrentSessionId, F as hashEmailFnv1a, G as isWireScalar, m as makeSessionId, H as namespaceExtra, r as reportClientEvent, l as reportClientEvents, n as resetCurrentSessionId, I as resolveUserContext, s as setCurrentSessionId, t as toAnalyticsEvent } from './currentSession-Bs2JfTJ8.mjs';
 import { O as OnboardingTheme } from './types-BKfpdZzX.mjs';
 export { a as OnboardingButtonStyle, b as OnboardingColors, c as OnboardingFonts, d as OnboardingRadius, e as OnboardingSpacing } from './types-BKfpdZzX.mjs';
 export { C as CenteredModal, a as CenteredModalHandle, b as CenteredModalProps } from './CenteredModal-C3qQBHsA.mjs';
 import { WireAIComponent, Message, WireAIResponse } from 'wireai-rn';
-import { a as WireFeaturesConfig, W as WireFeatures, b as WireOnboardingStorage } from './types-CMuOexw0.mjs';
-export { D as DEFAULT_SESSION_TTL_MS, L as LoadedSession, O as OnboardingMode, c as clearPersistedSession, l as loadPersistedSession, p as peekPersistedSession, s as savePersistedSession, d as sessionStorageKey } from './types-CMuOexw0.mjs';
+import { a as WireFeaturesConfig, W as WireFeatures, b as WireOnboardingStorage } from './types-CKFhyrMu.mjs';
+export { D as DEFAULT_SESSION_TTL_MS, L as LoadedSession, O as OnboardingMode, c as clearPersistedSession, l as loadPersistedSession, p as peekPersistedSession, s as savePersistedSession, d as sessionStorageKey } from './types-CKFhyrMu.mjs';
+import { z } from 'zod';
 import 'react-native';
 
 /**
@@ -346,6 +347,16 @@ declare const Button: React__default.NamedExoticComponent<ButtonProps>;
  *   - "fade": loaders — enter/exit as a plain 120ms fade so the "thinking"
  *     state hands off to the first card without a hard cut.
  *
+ * `direction` mirrors the whole slide for BACK navigation, so a step the user
+ * returns to comes back from the side it left toward. Spatial consistency: if
+ * "next" pushes left, "back" must pull right, or the stack loses its geography.
+ *
+ * `layout` picks how the moving surface is sized. "fill" (default) is the
+ * full-screen flow, where the pane owns the viewport. "auto" is for a pane
+ * inside an auto-height container (the CenteredModal card): `flex: 1` there
+ * resolves to a ZERO-height child under Yoga — flex-basis 0 with no free space
+ * to grow into — so the in-flow layer must size to its own content instead.
+ *
  * Reduce motion: every handoff becomes a 120ms crossfade, no translate/scale.
  * All values run on the native driver (transform/opacity only); in-flight
  * animations are stopped when superseded and on unmount.
@@ -356,11 +367,19 @@ declare const Button: React__default.NamedExoticComponent<ButtonProps>;
  */
 
 type CardHandoffVariant = "slide" | "spring" | "fade";
+/** Which way the stack is moving. "backward" mirrors the slide (see the header note). */
+type CardHandoffDirection = "forward" | "backward";
+/** How the moving surface is sized. "auto" = a pane in an auto-height container. */
+type CardHandoffLayout = "fill" | "auto";
 type CardHandoffProps = {
     /** Identity of the current child (e.g. the message id). A change runs the handoff. */
     transitionKey: string;
     /** How the CURRENT child enters (and, snapshotted, how it will later exit). */
     variant?: CardHandoffVariant;
+    /** Travel direction of THIS transition. Default "forward". */
+    direction?: CardHandoffDirection;
+    /** Sizing mode. Default "fill" (the full-screen flow). */
+    layout?: CardHandoffLayout;
     children: React__default.ReactNode;
 };
 declare const CardHandoff: React__default.NamedExoticComponent<CardHandoffProps>;
@@ -535,12 +554,51 @@ declare const TextInputCard: WireAIComponent;
 
 declare const SelectionCard: WireAIComponent;
 
+declare const CardGridSelectCard: WireAIComponent;
+
 declare const StatusCard: WireAIComponent;
 
 declare const NumberStepperCard: WireAIComponent;
 
 declare const InterstitialCard: WireAIComponent;
 
+/**
+ * The shared option shape for the choice cards (SelectionCard, CardGridSelectCard).
+ *
+ * ── BACK-COMPAT, IN BOTH DIRECTIONS (the hard gate) ──────────────────────────────────────
+ *
+ * NEW option → OLD kit: `z.object` STRIPS unknown keys, and the SDK renderer mounts
+ * `parsed.data` (not the raw props — see wireai-rn `renderer/ComponentRenderer.tsx`). So a
+ * client on kit 0.7.x that receives `{value, label, icon}` silently drops `icon` and renders
+ * the plain row it always did. No throw, no fallback card. This is what makes it safe to teach
+ * the server `icon` before every host has re-pinned — and it MUST stay true, so never make
+ * this schema `.strict()`.
+ *
+ * OLD option → NEW kit: the `preprocess` still coerces a bare `"Spring"` into
+ * `{value:"Spring", label:"Spring"}`, exactly as before. A bare string and a bare
+ * `{value,label}` both keep working untouched.
+ *
+ * `icon` is a plain `z.string()`, NOT a z.enum of the vocabulary. Deliberate: an unknown name
+ * must degrade to no icon (WireIcon does that), never fail validation. If it were an enum, one
+ * hallucinated or newer-than-this-client icon name would turn the whole card into a
+ * LLM_SCHEMA_ERROR and cost the user their question — a catastrophic trade for a decoration.
+ */
+
+declare const optionObjectSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+    icon: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    value: string;
+    icon?: string | undefined;
+}, {
+    label: string;
+    value: string;
+    icon?: string | undefined;
+}>;
+type CardOption = z.infer<typeof optionObjectSchema>;
+
 /**
  * onboardingComponents — the constrained set of themed cards the kit registers
  * with the SDK. The backend's `allowed_components` must be a subset of these
@@ -549,6 +607,473 @@ declare const InterstitialCard: WireAIComponent;
 
 declare const onboardingComponents: WireAIComponent[];
 
+/**
+ * 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. */
+type WireIconFamily = "MaterialCommunityIcons" | "Ionicons";
+/** One vocabulary entry: the concrete glyph a semantic name resolves to. */
+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.
+ */
+declare const WIRE_ICON_GLYPHS: {
+    readonly instagram: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "instagram";
+    };
+    readonly tiktok: {
+        readonly family: "Ionicons";
+        readonly name: "logo-tiktok";
+    };
+    readonly youtube: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "youtube";
+    };
+    readonly facebook: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "facebook";
+    };
+    readonly twitter: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "twitter";
+    };
+    readonly reddit: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "reddit";
+    };
+    readonly linkedin: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "linkedin";
+    };
+    readonly discord: {
+        readonly family: "Ionicons";
+        readonly name: "logo-discord";
+    };
+    readonly whatsapp: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "whatsapp";
+    };
+    readonly twitch: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "twitch";
+    };
+    readonly snapchat: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "snapchat";
+    };
+    readonly pinterest: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "pinterest";
+    };
+    readonly google: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "google";
+    };
+    readonly search: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "magnify";
+    };
+    readonly friend: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "account-heart";
+    };
+    readonly podcast: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "podcast";
+    };
+    readonly blog: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "post";
+    };
+    readonly newsletter: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "email-outline";
+    };
+    readonly news: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "newspaper";
+    };
+    readonly "app-store": {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "apple";
+    };
+    readonly ad: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "bullhorn";
+    };
+    readonly wedding: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "ring";
+    };
+    readonly birthday: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "cake-variant";
+    };
+    readonly baby: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "baby-carriage";
+    };
+    readonly travel: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "airplane";
+    };
+    readonly work: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "briefcase";
+    };
+    readonly celebration: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "party-popper";
+    };
+    readonly store: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "storefront";
+    };
+    readonly school: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "school";
+    };
+    readonly team: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "account-multiple";
+    };
+    readonly growth: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "trending-up";
+    };
+    readonly sparkle: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "star-four-points";
+    };
+    readonly heart: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "heart";
+    };
+    readonly star: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "star";
+    };
+    readonly fire: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "fire";
+    };
+    readonly target: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "target";
+    };
+    readonly trophy: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "trophy";
+    };
+    readonly rocket: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "rocket-launch";
+    };
+    readonly clock: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "clock-outline";
+    };
+    readonly calendar: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "calendar-star";
+    };
+    readonly camera: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "camera";
+    };
+    readonly image: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "image";
+    };
+    readonly video: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "video";
+    };
+    readonly mic: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "microphone";
+    };
+    readonly music: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "music";
+    };
+    readonly book: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "book-open-variant";
+    };
+    readonly food: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "silverware-fork-knife";
+    };
+    readonly coffee: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "coffee";
+    };
+    readonly fitness: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "dumbbell";
+    };
+    readonly health: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "heart-pulse";
+    };
+    readonly meditation: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "meditation";
+    };
+    readonly sleep: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "sleep";
+    };
+    readonly brain: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "brain";
+    };
+    readonly idea: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "lightbulb-on";
+    };
+    readonly money: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "cash";
+    };
+    readonly shopping: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "cart";
+    };
+    readonly gift: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "gift";
+    };
+    readonly home: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "home";
+    };
+    readonly car: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "car";
+    };
+    readonly pet: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "paw";
+    };
+    readonly plant: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "sprout";
+    };
+    readonly sun: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "white-balance-sunny";
+    };
+    readonly moon: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "weather-night";
+    };
+    readonly globe: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "earth";
+    };
+    readonly "map-pin": {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "map-marker";
+    };
+    readonly compass: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "compass";
+    };
+    readonly flag: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "flag";
+    };
+    readonly bookmark: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "bookmark";
+    };
+    readonly bell: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "bell";
+    };
+    readonly mail: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "email";
+    };
+    readonly phone: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "phone";
+    };
+    readonly chat: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "chat";
+    };
+    readonly user: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "account";
+    };
+    readonly users: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "account-group";
+    };
+    readonly settings: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "cog";
+    };
+    readonly tools: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "tools";
+    };
+    readonly puzzle: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "puzzle";
+    };
+    readonly chart: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "chart-line";
+    };
+    readonly shield: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "shield-check";
+    };
+    readonly lock: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "lock";
+    };
+    readonly cloud: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "cloud";
+    };
+    readonly pencil: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "pencil";
+    };
+    readonly check: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "check-circle";
+    };
+    readonly plus: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "plus-circle";
+    };
+    readonly question: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "help-circle";
+    };
+    readonly other: {
+        readonly family: "MaterialCommunityIcons";
+        readonly name: "dots-horizontal-circle";
+    };
+};
+/** A name in the vocabulary. The card schemas accept any string and degrade — see `WireIcon`. */
+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.
+ */
+declare const WIRE_ICON_NAMES: readonly string[];
+/**
+ * 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.
+ */
+declare const lookupIconGlyph: (name: string | undefined) => WireIconGlyph | undefined;
+
+/** A `require`-like resolver. Injectable in tests; production uses the guarded literal require. */
+type OptionalRequire$2 = (moduleName: string) => unknown;
+
+/**
+ * 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.
+ */
+
+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$2;
+};
+declare const WireIcon: React__default.NamedExoticComponent<WireIconProps>;
+
+/**
+ * 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`.
+ */
+
+type WireIconRegistry = Record<string, React__default.ReactNode>;
+type IconRegistryProviderProps = {
+    registry?: WireIconRegistry;
+    children: React__default.ReactNode;
+};
+declare const IconRegistryProvider: React__default.FC<IconRegistryProviderProps>;
+/**
+ * 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.
+ */
+declare const useHostIcon: (name?: string) => React__default.ReactNode | undefined;
+
 /**
  * OnboardingFlow — the inner engine. Mirrors the proven production-app usage of the SDK
  * (useWireAIThread + useWireAIAction + ComponentRenderer) and layers on the kit's
@@ -733,7 +1258,7 @@ declare const featuresEqual: (a: WireFeatures, b: WireFeatures) => boolean;
  * A cache younger than this is "fresh"; older is "stale" (still served on a fetch error).
  */
 declare const DEFAULT_FEATURES_TTL_MS = 300000;
-/** 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`. */
 declare const featuresCacheKey: (appId?: string) => string;
 /** A cached flags entry: the resolved flags + the epoch-ms they were fetched. */
 interface CachedFeatures {
@@ -837,10 +1362,20 @@ declare const attributionMetadata: (a: OnboardingAttribution) => {
  * 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).
@@ -867,10 +1402,18 @@ declare const detectAppVersion: (requireModule?: OptionalRequire$1) => string |
  * 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
@@ -1091,7 +1634,7 @@ declare const useSessionStart: (config: SessionStartConfig | undefined, options?
 /** The canonical event name for the first-ever app open. Same `app.*` namespace as
  *  {@link SESSION_STARTED_EVENT}; a trigger keys off this exact string. */
 declare const FIRST_OPEN_EVENT: "app.first_open";
-/** Storage key for the once-ever first-open flag, e.g. `wireai:first_open:myelino`. Mirrors the
+/** Storage key for the once-ever first-open flag, e.g. `wireai:first_open:acme`. Mirrors the
  *  `wireai:<concern>:<appId>` namespacing of {@link sessionStorageKey}. */
 declare const firstOpenStorageKey: (appId: string) => string;
 /** Test-only: forget the first-open latch so a unit test starts from a clean process state. */
@@ -1196,4 +1739,4 @@ interface UseLifecycleEventsOptions {
  */
 declare const useLifecycleEvents: (config: LifecycleConfig | undefined, options?: UseLifecycleEventsOptions) => void;
 
-export { AUTO_DEVICE_ID_PREFIX, AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardHandoff, type CardHandoffProps, type CardHandoffVariant, ChipSelectCard, ClientEvent, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, DeviceContext, DoneBlock, ErrorBlock, FIRST_OPEN_EVENT, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, type LifecycleConfig, type LifecycleEventInput, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseLifecycleEventsOptions, type UseSessionStartOptions, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, attributionMetadata, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, detectAppVersion, detectNativeModel, deviceIdStorageKey, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, mergeTheme, mintDeviceId, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetFirstOpenLatch, resetSessionStartGuard, sanitizeUserId, themeFromBrand, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };
+export { AUTO_DEVICE_ID_PREFIX, AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardGridSelectCard, CardHandoff, type CardHandoffProps, type CardHandoffVariant, type CardOption, ChipSelectCard, ClientEvent, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, DeviceContext, DoneBlock, ErrorBlock, FIRST_OPEN_EVENT, IconRegistryProvider, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, type LifecycleConfig, type LifecycleEventInput, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseLifecycleEventsOptions, type UseSessionStartOptions, WIRE_ICON_GLYPHS, WIRE_ICON_NAMES, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, WireIcon, type WireIconFamily, type WireIconGlyph, type WireIconName, type WireIconProps, type WireIconRegistry, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, attributionMetadata, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, detectAppVersion, detectNativeModel, deviceIdStorageKey, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, lookupIconGlyph, mergeTheme, mintDeviceId, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetFirstOpenLatch, resetSessionStartGuard, sanitizeUserId, themeFromBrand, useHostIcon, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };