@wireai/activation 0.1.0

package/src/showcase/types.ts

@@ -0,0 +1,74 @@
+import type { ImageSourcePropType } from "react-native";
+
+import type { GestureKind } from "../coachmarks/types";
+import type { OnboardingTheme } from "../theme/types";
+import type { CoachmarkStorage } from "../coachmarks/types";
+import type { WireFeatures, WireFeaturesConfig } from "../features/types";
+
+/**
+ * One slide in the pre-onboarding feature showcase (the "app intro"). Maps onto
+ * a `@blazejkustra/react-native-onboarding` step, with an optional perf-tuned
+ * GestureHint overlaid on top. An `image` is strongly recommended — the
+ * underlying package renders an image area per slide; slides without one fall
+ * back to a transparent placeholder so nothing crashes.
+ */
+export interface ShowcaseSlide {
+  id: string;
+  title: string;
+  description: string;
+  image?: ImageSourcePropType;
+  /** Where the image sits relative to the copy. Default `top`. */
+  imagePosition?: "top" | "bottom";
+  /** Per-slide primary button label; falls back to the showcase default. */
+  buttonLabel?: string;
+  /** Optional animated hand overlaid on the slide (the perf-tuned GestureHint). */
+  gesture?: GestureKind;
+}
+
+/** Optional intro panel shown before the slides begin. */
+export interface ShowcaseIntroPanel {
+  title?: string;
+  subtitle?: string;
+  /** Start-button label (required by the underlying package). */
+  button: string;
+  image?: ImageSourcePropType;
+}
+
+/** The whole declarative feature-showcase an app supplies. */
+export interface ShowcaseConfig {
+  /** Gate key — persisted as `wire_showcase_<id>_seen`. */
+  id: string;
+  introPanel?: ShowcaseIntroPanel;
+  slides: ShowcaseSlide[];
+}
+
+export interface FeatureShowcaseProps {
+  config: ShowcaseConfig;
+  /** Called when the showcase completes, is skipped, or was already seen. */
+  onDone: () => void;
+  /** Partial theme merged over the active onboarding theme for the showcase colors. */
+  theme?: Partial<OnboardingTheme>;
+  /** Accent override (buttons + emphasis). Defaults to the theme's `primary`. */
+  accentColor?: string;
+  /** Default primary button label when a slide/intro omits one. Default "Next". */
+  buttonLabel?: string;
+  /**
+   * Sync gate storage. Defaults to the storage injected by CoachmarkProvider, so
+   * you usually don't pass this — the showcase gates through the same store as
+   * the coachmark tours.
+   */
+  storage?: CoachmarkStorage | null;
+  /** Testing override; defaults to the global `isTestingCoachmark` flag. */
+  isTesting?: boolean;
+  /**
+   * OPTIONAL feature-flag wiring. When `flags.showcase.enabled` is false, the showcase renders
+   * NOTHING and calls `onDone()` from an effect so the host's navigation flow continues exactly
+   * as if it had completed — it can never strand a flow waiting on a screen that won't appear. It
+   * does NOT write the seen gate, so re-enabling replays it. Provide pre-resolved `features`, OR a
+   * `featuresConfig` to lazily fetch once, OR mount a `WireFeaturesProvider` above (context is
+   * read automatically). Omit all three and the showcase stays on (fail-open).
+   */
+  features?: WireFeatures;
+  /** Lazy-fetch config for the flags, used when `features` is absent and no provider is above. */
+  featuresConfig?: WireFeaturesConfig;
+}

package/src/theme/ThemeContext.tsx

@@ -0,0 +1,38 @@
+/**
+ * ThemeContext — provides the resolved OnboardingTheme to every shell element and
+ * themed card via `useOnboardingTheme()`. WHY a context rather than prop-drilling:
+ * the cards are mounted by the SDK's ComponentRenderer (not by us), so we can't
+ * pass them props directly — they must read the theme from context.
+ */
+import React, { createContext, useContext, useMemo } from "react";
+import { mergeTheme } from "./defaultTheme";
+import type { OnboardingTheme } from "./types";
+
+const OnboardingThemeContext = createContext<OnboardingTheme | null>(null);
+
+export type OnboardingThemeProviderProps = {
+  /** Partial overrides merged over the neutral default theme. */
+  theme?: Partial<OnboardingTheme>;
+  children: React.ReactNode;
+};
+
+export const OnboardingThemeProvider: React.FC<OnboardingThemeProviderProps> = ({
+  theme,
+  children,
+}) => {
+  const resolved = useMemo(() => mergeTheme(theme), [theme]);
+  return (
+    <OnboardingThemeContext.Provider value={resolved}>
+      {children}
+    </OnboardingThemeContext.Provider>
+  );
+};
+
+/**
+ * Read the active theme. Falls back to the default theme when used outside a
+ * provider so a stray card never crashes — it just renders neutral.
+ */
+export const useOnboardingTheme = (): OnboardingTheme => {
+  const ctx = useContext(OnboardingThemeContext);
+  return ctx ?? mergeTheme();
+};

package/src/theme/defaultTheme.ts

@@ -0,0 +1,70 @@
+/**
+ * defaultOnboardingTheme — a neutral, light, brand-agnostic baseline. Consumers
+ * pass a `Partial<OnboardingTheme>` that is deep-merged over this (see
+ * `mergeTheme`), so they only override what differs from neutral.
+ */
+import type { OnboardingTheme } from "./types";
+
+export const defaultOnboardingTheme: OnboardingTheme = {
+  colors: {
+    background: "#FFFFFF",
+    surface: "#F7F7F8",
+    text: "#101114",
+    textMuted: "#6B7280",
+    primary: "#111111",
+    onPrimary: "#FFFFFF",
+    primarySoft: "rgba(17,17,17,0.06)",
+    border: "#E4E4E7",
+    borderStrong: "#C7C7CC",
+    disabled: "#EBEBEB",
+    success: "#16A34A",
+    warning: "#D97706",
+    error: "#DC2626",
+    info: "#2563EB",
+  },
+  fonts: {
+    regular: undefined,
+    medium: undefined,
+    bold: undefined,
+    baseSize: 16,
+    scale: 1,
+  },
+  radius: {
+    sm: 8,
+    md: 12,
+    lg: 16,
+    full: 9999,
+  },
+  spacing: {
+    xs: 4,
+    sm: 8,
+    md: 16,
+    lg: 24,
+    xl: 32,
+  },
+  // Circled (pill) CTA by default; an app can pass `button: { radius: 12 }` for
+  // a rounded rectangle, or override height/paddingX to match its design system.
+  button: {
+    radius: 9999,
+    height: 52,
+    paddingX: 24,
+  },
+};
+
+/**
+ * Deep-merge a partial theme over the default. Two levels deep is enough — the
+ * theme is intentionally shallow (colors/fonts/radius/spacing), so we merge each
+ * known sub-object and leave scalars to overwrite.
+ */
+export const mergeTheme = (
+  override?: Partial<OnboardingTheme>,
+): OnboardingTheme => {
+  if (!override) return defaultOnboardingTheme;
+  return {
+    colors: { ...defaultOnboardingTheme.colors, ...override.colors },
+    fonts: { ...defaultOnboardingTheme.fonts, ...override.fonts },
+    radius: { ...defaultOnboardingTheme.radius, ...override.radius },
+    spacing: { ...defaultOnboardingTheme.spacing, ...override.spacing },
+    button: { ...defaultOnboardingTheme.button, ...override.button },
+  };
+};

package/src/theme/themeFromBrand.ts

@@ -0,0 +1,93 @@
+/**
+ * themeFromBrand — the fastest path to a branded flow. Give it a primary brand
+ * color (and optionally a background + a font), and it derives a sensible full
+ * `Partial<OnboardingTheme>` over the neutral `defaultOnboardingTheme` (via
+ * `mergeTheme`): a tinted soft wash for selected states, a readable on-primary
+ * label, and matching success/info accents left at the neutral default.
+ *
+ *   theme={themeFromBrand({ primary: "#15B0B0" })}
+ *
+ * It stays intentionally small: it only touches the values that flow from a brand
+ * color. Anything else (radius, spacing, button shape) keeps the default; pass
+ * `extra` to override those without re-authoring the palette.
+ */
+import { defaultOnboardingTheme, mergeTheme } from "./defaultTheme";
+import type { OnboardingTheme } from "./types";
+
+export type ThemeFromBrandInput = {
+  /** Brand / accent color — drives selected states, primary buttons, progress fill. */
+  primary: string;
+  /** App background behind the whole flow. Default: the neutral light background. */
+  background?: string;
+  /** Card / elevated surface background. Default: the neutral surface. */
+  surface?: string;
+  /** Primary body text color. Default: the neutral near-black. */
+  text?: string;
+  /** Text/icon color on top of `primary`. Default: white. */
+  onPrimary?: string;
+  /**
+   * A single font family applied to regular/medium/bold (the kit derives weight
+   * from size when a family isn't weight-split). Pass `fonts` in `extra` for
+   * per-weight families.
+   */
+  font?: string;
+  /** Any further theme overrides, deep-merged last (radius/spacing/button/fonts/colors). */
+  extra?: Partial<OnboardingTheme>;
+};
+
+/** Parse a #RGB or #RRGGBB hex into [r,g,b]; returns null for anything else (e.g. rgba()). */
+const hexToRgb = (hex: string): [number, number, number] | null => {
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(hex.trim());
+  if (!m) return null;
+  let h = m[1] as string;
+  if (h.length === 3) h = h[0]! + h[0]! + h[1]! + h[1]! + h[2]! + h[2]!;
+  const int = parseInt(h, 16);
+  return [(int >> 16) & 255, (int >> 8) & 255, int & 255];
+};
+
+/** A low-alpha wash of the primary for selected backgrounds, falling back gracefully. */
+const softFromPrimary = (primary: string): string => {
+  const rgb = hexToRgb(primary);
+  if (!rgb) return defaultOnboardingTheme.colors.primarySoft;
+  const [r, g, b] = rgb;
+  return `rgba(${r},${g},${b},0.10)`;
+};
+
+export const themeFromBrand = (input: ThemeFromBrandInput): Partial<OnboardingTheme> => {
+  const { primary, background, surface, text, onPrimary, font, extra } = input;
+
+  const derived: Partial<OnboardingTheme> = {
+    colors: {
+      ...defaultOnboardingTheme.colors,
+      primary,
+      primarySoft: softFromPrimary(primary),
+      onPrimary: onPrimary ?? defaultOnboardingTheme.colors.onPrimary,
+      ...(background ? { background } : {}),
+      ...(surface ? { surface } : {}),
+      ...(text ? { text } : {}),
+    },
+    ...(font
+      ? {
+          fonts: {
+            ...defaultOnboardingTheme.fonts,
+            regular: font,
+            medium: font,
+            bold: font,
+          },
+        }
+      : {}),
+  };
+
+  // mergeTheme resolves the derived palette over the neutral default into a full
+  // theme. Then deep-merge `extra` per sub-object so callers can override
+  // radius/spacing/button/fonts/colors without re-authoring the palette.
+  const base = mergeTheme(derived);
+  if (!extra) return base;
+  return {
+    colors: { ...base.colors, ...extra.colors },
+    fonts: { ...base.fonts, ...extra.fonts },
+    radius: { ...base.radius, ...extra.radius },
+    spacing: { ...base.spacing, ...extra.spacing },
+    button: { ...base.button, ...extra.button },
+  };
+};

package/src/theme/types.ts

@@ -0,0 +1,88 @@
+/**
+ * OnboardingTheme — the single source of truth for every visual value the kit
+ * renders. It deliberately mirrors the SHAPE of the OSS SDK's design tokens
+ * (`wire-rn/.../styles/tokens.ts`: colors / radii / spacing / textStyles) so the
+ * themed cards port over cleanly — but here EVERY value comes from the theme, so
+ * a consumer app can repaint the whole flow to match its brand.
+ *
+ * WHY a flat-ish object (not nested per-component): a host app already has its
+ * own palette; mapping it onto one object once is far less friction than theming
+ * each card. Cards read semantic roles (surface, primary, border…), never raw hex.
+ */
+
+export type OnboardingColors = {
+  /** App background behind the whole flow. */
+  background: string;
+  /** Card / elevated surface background. */
+  surface: string;
+  /** Primary body text. */
+  text: string;
+  /** Secondary / hint / placeholder text. */
+  textMuted: string;
+  /** Brand / accent — selected states, primary buttons, progress fill. */
+  primary: string;
+  /** Text/icon color on top of `primary` (e.g. primary button label). */
+  onPrimary: string;
+  /** A tinted wash of `primary` for selected backgrounds. */
+  primarySoft: string;
+  /** Hairline borders + unselected outlines. */
+  border: string;
+  /** Stronger border for emphasis. */
+  borderStrong: string;
+  /** Disabled control fill. */
+  disabled: string;
+  success: string;
+  warning: string;
+  error: string;
+  info: string;
+};
+
+export type OnboardingFonts = {
+  /** Family for normal-weight text. Pass undefined to use the platform default. */
+  regular?: string;
+  /** Family for medium-weight text. */
+  medium?: string;
+  /** Family for bold/heading text. */
+  bold?: string;
+  /** Base body font size in px. The text scale derives from this × `scale`. */
+  baseSize: number;
+  /** Multiplier applied to derived sizes (e.g. 1.1 for a larger flow). */
+  scale: number;
+};
+
+export type OnboardingRadius = {
+  sm: number;
+  md: number;
+  lg: number;
+  full: number;
+};
+
+export type OnboardingSpacing = {
+  xs: number;
+  sm: number;
+  md: number;
+  lg: number;
+  xl: number;
+};
+
+/**
+ * Button shape + size, as its own token so an app can decide how its CTAs look
+ * without touching card internals. Set `radius` to a large value (e.g. 9999) for
+ * a fully circled pill, or a small one (e.g. 12) for a rounded rectangle.
+ */
+export type OnboardingButtonStyle = {
+  /** Corner radius. 9999 = fully circled pill; ~12 = rounded rectangle. */
+  radius: number;
+  /** Minimum touch-target height. */
+  height: number;
+  /** Horizontal padding (the button's own spacing). */
+  paddingX: number;
+};
+
+export type OnboardingTheme = {
+  colors: OnboardingColors;
+  fonts: OnboardingFonts;
+  radius: OnboardingRadius;
+  spacing: OnboardingSpacing;
+  button: OnboardingButtonStyle;
+};

package/src/theme/typography.ts

@@ -0,0 +1,46 @@
+/**
+ * typography — derive concrete RN text styles from the theme's font config, so
+ * every label/title/caption in the kit scales from one `baseSize` + `scale` and
+ * picks the right family. Cards call these instead of hardcoding fontSize/weight.
+ */
+import type { TextStyle } from "react-native";
+import type { OnboardingFonts } from "./types";
+
+const round = (n: number) => Math.round(n);
+
+/** Body text — the reference size. */
+export const bodyStyle = (f: OnboardingFonts): TextStyle => ({
+  fontFamily: f.regular,
+  fontSize: round(f.baseSize * f.scale),
+  lineHeight: round(f.baseSize * f.scale * 1.5),
+});
+
+/** Slightly smaller secondary/hint text. */
+export const captionStyle = (f: OnboardingFonts): TextStyle => ({
+  fontFamily: f.regular,
+  fontSize: round(f.baseSize * 0.8125 * f.scale),
+  lineHeight: round(f.baseSize * 0.8125 * f.scale * 1.5),
+});
+
+/** Emphasised label (e.g. a card question). */
+export const labelStyle = (f: OnboardingFonts): TextStyle => ({
+  fontFamily: f.medium ?? f.bold,
+  fontSize: round(f.baseSize * f.scale),
+  lineHeight: round(f.baseSize * f.scale * 1.4),
+  fontWeight: f.medium ? undefined : ("600" as const),
+});
+
+/** Heading (status title, done block). */
+export const headingStyle = (f: OnboardingFonts): TextStyle => ({
+  fontFamily: f.bold,
+  fontSize: round(f.baseSize * 1.25 * f.scale),
+  lineHeight: round(f.baseSize * 1.25 * f.scale * 1.3),
+  fontWeight: f.bold ? undefined : ("700" as const),
+});
+
+/** Button label. */
+export const buttonLabelStyle = (f: OnboardingFonts): TextStyle => ({
+  fontFamily: f.bold ?? f.medium,
+  fontSize: round(f.baseSize * f.scale),
+  fontWeight: f.bold ? undefined : ("600" as const),
+});

package/src/types.ts

@@ -0,0 +1,215 @@
+/**
+ * Public types for the wireai-onboarding kit.
+ */
+import type { Message } from "wireai-rn";
+import type { OnboardingTheme } from "./theme/types";
+import type { WireOnboardingStorage } from "./session/persistedSession";
+
+export type { OnboardingTheme } from "./theme/types";
+export type { WireOnboardingStorage } from "./session/persistedSession";
+
+/** Transport + tenant config for the managed Wire AI onboarding backend (A2A). */
+export type WireOnboardingConfig = {
+  /** Tenant API key (resolves the app server-side). */
+  apiKey: string;
+  /** Base server URL; the kit appends `/a2a`. */
+  serverUrl: string;
+  /** App id — passed as the A2A `model` (informational; the key resolves the app). */
+  appId: string;
+  /**
+   * Extra metadata merged into every A2A request (e.g. install attribution).
+   * NOTE: the kit reserves `sessionId` (correlation seed) and `supportedComponents`
+   * (the renderable card names this device advertises to the backend) — it sets both
+   * automatically, so don't override them here.
+   */
+  metadata?: Record<string, unknown>;
+  /**
+   * Host app version string (e.g. "1.4.2"). HOST-INJECTED — the kit adds no dependency to
+   * read it; hosts typically pass it from `expo-constants`
+   * (`Constants.expoConfig?.version`). Forwarded to the backend on the session metadata and
+   * on client events (merged into the `device` snapshot as `device.appVersion`) so analytics
+   * can segment the funnel by app version. Optional; omit if unknown.
+   */
+  appVersion?: string;
+};
+
+/**
+ * A per-step validator, keyed by a base-question `key` (e.g. `username`). Runs
+ * before the answer is sent to the backend. Return `{ ok: false, error }` to
+ * block advancing and show the error inline on the card.
+ */
+export type StepValidator = (value: string) => Promise<{ ok: boolean; error?: string }>;
+
+/** Result handed to `onComplete` when the flow reaches its terminal StatusCard. */
+export type OnboardingResult = {
+  /** Question-key → captured value, derived from the thread. */
+  answers: Record<string, unknown>;
+  /** The raw message thread, for custom downstream parsing. */
+  raw: Message[];
+};
+
+/**
+ * Lifecycle events emitted as the flow runs, for host-side analytics. The kit owns
+ * the thread loop, so this is how a host recovers per-turn telemetry it used to get
+ * by driving the loop itself.
+ *  - `started`: the very first message was sent to the backend. Carries `contextId` (the
+ *               A2A session id). Capture it if you may need to bind a user AFTER the flow
+ *               finishes (see `identifyOnboarding` and the `userId` prop).
+ *  - `resumed`: a persisted session was restored after an app kill (fires INSTEAD of
+ *               `started`, so host funnels don't double-count the same session). Also carries
+ *               `contextId`. Requires the `storage` prop.
+ *  - `turn`: a new assistant card arrived (`step` = 1-based index of cards seen).
+ *  - `error`: the backend errored or the first-card watchdog timed out.
+ *  - `retry`: a transient failure is being auto-retried (`attempt` = 1-based).
+ *  - `fallback`: retries are exhausted; the kit degraded to the static `fallbackFlow`
+ *               (or handed off to `onError`). This is the client-side mirror of the
+ *               backend's `llm_fallback` reliability event.
+ */
+export type OnboardingEvent =
+  | { type: "started"; contextId: string }
+  | { type: "resumed"; contextId: string }
+  | { type: "turn"; step: number; component?: string }
+  | { type: "error"; reason: "backend" | "timeout" }
+  | { type: "retry"; reason: "backend" | "timeout"; attempt: number }
+  | { type: "fallback"; reason: "backend" | "timeout" };
+
+/**
+ * Copy overrides for the kit's built-in (English) strings, so a host can localize
+ * the loaders / completion fallback via its own i18n. Any field left unset keeps
+ * the kit default.
+ */
+export type OnboardingCopy = {
+  /** First "thinking" screen, before any card arrives. */
+  startingTitle: string;
+  startingHint: string;
+  /** While the persisted session id is being restored from `storage` (pre-mount gate). */
+  restoringTitle: string;
+  restoringHint: string;
+  /** Between-turns loader, while the next card is generated. */
+  thinkingTitle: string;
+  thinkingHint: string;
+  /** While a per-step validator is running. */
+  checkingTitle: string;
+  checkingHint: string;
+  /** Completion fallback when the backend omits a title/CTA. */
+  completeTitle: string;
+  completeCta: string;
+};
+
+export type WireOnboardingProps = {
+  config: WireOnboardingConfig;
+  /** Partial theme merged over the neutral default. */
+  theme?: Partial<OnboardingTheme>;
+  /** Override the registered cards (defaults to the kit's `onboardingComponents`). */
+  components?: import("wireai-rn").WireAIComponent[];
+  /**
+   * App-supplied artwork for InterstitialCard, keyed by name. The backend names one
+   * via `illustration`; the kit slots the matching node (keeping itself dependency-free).
+   */
+  illustrations?: Record<string, import("react").ReactNode>;
+  /** Per-step validators keyed by base-question key, e.g. `{ username: checkUsername }`. */
+  validators?: Record<string, StepValidator>;
+  /** Fired once the flow reaches its terminal StatusCard. */
+  onComplete: (result: OnboardingResult) => void;
+  /**
+   * Retained for back-compat. NOTE: per-question Skip is now INTERNAL — the kit shows
+   * a Skip control only on screens the backend marks `skippable`, and it advances ONE
+   * question (it does not exit the flow). This callback is no longer wired to that control.
+   */
+  onSkip?: () => void;
+  /**
+   * Fired on a backend error or first-card timeout, AFTER retries are exhausted.
+   * When `fallbackFlow` is NOT supplied and this is provided, the host owns recovery
+   * (e.g. navigate to its own static onboarding) instead of the kit's inline retry.
+   */
+  onError?: (err: unknown) => void;
+  /**
+   * Your predefined STATIC onboarding, rendered in place when the AI flow fails and
+   * retries are exhausted — so a generation/backend/timeout error degrades to your
+   * static flow instead of breaking the app. Takes precedence over `onError`. This
+   * is the "it can never break your onboarding" guarantee: supply the same flow you
+   * shipped before adding Wire AI and the user always keeps moving.
+   */
+  fallbackFlow?: import("react").ReactNode;
+  /**
+   * Consecutive failures to auto-retry before degrading to `fallbackFlow`/`onError`.
+   * Default 1 (one silent retry, then degrade). 0 = degrade on the first failure.
+   */
+  maxRetries?: number;
+  /** Lifecycle hook for host-side analytics (started / per-turn / error). */
+  onEvent?: (event: OnboardingEvent) => void;
+  /**
+   * Host-injected, non-PII context the app already knows about the user — signup method,
+   * referral source, plan tier, a HASHED user id, etc. Same host-injection philosophy as
+   * `storage`: the kit collects nothing here; the host passes what it wants. Forwarded to the
+   * backend on the session metadata AND on client events so analytics can segment the funnel.
+   *
+   * MUST NOT contain PII such as raw emails, names, or phone numbers — pass a hash if you need
+   * a user key. Values are limited to primitives (`string | number | boolean`); the server caps
+   * key count / size and drops deep nesting. Old servers ignore it (backward compatible).
+   */
+  userContext?: Record<string, string | number | boolean>;
+  /**
+   * The host's own user id, so onboarding sessions can be reconciled to real users later
+   * (console sessions ↔ your user table / GA4 users). First-class alongside `userContext`.
+   *
+   * An OPAQUE PSEUDONYMOUS string YOU own — your internal user id, NOT an email/name/phone.
+   * Trimmed and capped at 128 chars (longer is truncated). **No PII.**
+   *
+   * LATE BINDING: users often register DURING or AFTER onboarding, so this is fully optional
+   * and can arrive late:
+   *  - present at MOUNT → rides the A2A session-start metadata (server binds it at session start);
+   *  - CHANGES mid-session (e.g. the user just registered) → the kit emits an `identify` event
+   *    that attaches the id to the LIVE session;
+   *  - available only AFTER completion → capture the `contextId` from the `started`/`resumed`
+   *    `onEvent` while the flow runs, then call `identifyOnboarding({ contextId, userId })` once
+   *    the user registers. Completion clears the persisted session, so the captured `contextId`
+   *    is the reliable post-flow handle.
+   *
+   * Backward compatible: omit it and nothing changes; old servers ignore the extra field.
+   */
+  userId?: string;
+  /** Localized overrides for the kit's built-in English strings. */
+  copy?: Partial<OnboardingCopy>;
+  /**
+   * Approximate total number of screens, if known (e.g. the backend screen budget).
+   * Paces the progress bar as `step / approxScreens` (capped, never shown as a
+   * number) instead of the asymptotic default. A backend-supplied `progress.total`
+   * takes precedence when present.
+   */
+  approxScreens?: number;
+  /** First message that kicks off the backend flow. Default `"start"`. */
+  startMessage?: string;
+  /** Ms to wait for the first card before showing the error/retry state. Default 15000. */
+  startTimeoutMs?: number;
+  /**
+   * Host-injected storage for session-id persistence (AsyncStorage-compatible subset:
+   * pass `@react-native-async-storage/async-storage` as-is, or a small MMKV wrapper).
+   * When set, the kit caches its session id so an app KILL mid-onboarding resumes the
+   * SAME backend session instead of minting a new one — keeping the analytics funnel's
+   * `started` count honest (no phantom drops). Omit for the previous per-mount behavior.
+   * This persists the kit's own correlation seed only — never answers.
+   */
+  storage?: WireOnboardingStorage;
+  /**
+   * How long a persisted session id stays resumable, in ms. Default 3 600 000 (1h),
+   * matching the backend's session TTL. Only meaningful with `storage`.
+   */
+  sessionTtlMs?: number;
+  /**
+   * Override the storage key (default `wireai:session:<config.appId>`). Scope it
+   * per-user (e.g. append a user id) if one device can run onboarding for multiple
+   * accounts mid-flow. Only meaningful with `storage`.
+   */
+  persistKey?: string;
+};
+
+/** Backend-supplied progress, read off `response.props.progress` when present. */
+export type OnboardingProgress = {
+  step: number;
+  total: number;
+  /** Base-question key for the CURRENT screen, when known (used to pick a validator). */
+  key?: string;
+  /** Whether the CURRENT screen may be skipped (backend-marked; default false → no Skip shown). */
+  skippable?: boolean;
+};

package/src/utils/deriveAnswers.ts

@@ -0,0 +1,43 @@
+/**
+ * deriveAnswers — read the user's structured choices off the thread.
+ *
+ * The cards send answers back as natural-language strings (the SDK's
+ * useWireAIAction wraps them, e.g. `I selected: ["Food","Travel"]`,
+ * `My answer is: "Casablanca"`). We pair each rendered question with the reply
+ * that followed it and key the answer by the backend's progress `key` when
+ * present (so `username`/`interests`/`city` come back under their real keys),
+ * else by the question text. No second LLM call — the values ARE the data.
+ */
+import type { Message } from "wireai-rn";
+
+const stripPrefix = (s: string): string =>
+  s.replace(/^(I selected:|My answer is:|I tapped:)\s*/i, "").trim();
+
+const tryParse = (s: string): unknown => {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return s;
+  }
+};
+
+export const deriveAnswers = (messages: Message[]): Record<string, unknown> => {
+  const out: Record<string, unknown> = {};
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    const r = m?.response;
+    if (!m || m.role !== "assistant" || !r || r.action !== "render") continue;
+
+    const props = (r.props ?? {}) as Record<string, unknown>;
+    const progress = props.progress as { key?: string } | undefined;
+    const questionText =
+      (props.title as string) ?? (props.label as string) ?? (props.question as string);
+    const key = progress?.key || questionText;
+
+    const reply = messages[i + 1];
+    if (key && reply?.role === "user") {
+      out[key] = tryParse(stripPrefix(reply.content));
+    }
+  }
+  return out;
+};