@wireai/activation 0.1.0

package/src/features/cache.ts

@@ -0,0 +1,92 @@
+/**
+ * The last-known-flags cache — persisted through the host's optional `storage`.
+ *
+ * WHY: the fetch is best-effort and fail-open. When the control plane is unreachable we serve the
+ * LAST value we saw rather than snapping to defaults, so a tenant that intentionally disabled a
+ * module during an incident keeps it disabled across an outage instead of flapping back on. That
+ * is "stale-while-error": a fresh cache (< TTL) is trusted, and on a fetch error even a STALE
+ * cache is served (any age beats a guess). Every operation is best-effort — a broken/hung storage
+ * degrades to defaults, never a throw and never a stuck gate (mirrors persistedSession).
+ */
+import { parseWireFeatures } from "./defaults";
+import type { WireFeatures } from "./types";
+import type { WireOnboardingStorage } from "../session/persistedSession";
+
+/**
+ * TTL for a cached flags entry, aligned to the server's `Cache-Control: private, max-age=300`.
+ * A cache younger than this is "fresh"; older is "stale" (still served on a fetch error).
+ */
+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`. */
+export const featuresCacheKey = (appId?: string): string =>
+  `wireai:features:${appId && appId.length > 0 ? appId : "default"}`;
+
+/** A cached flags entry: the resolved flags + the epoch-ms they were fetched. */
+export interface CachedFeatures {
+  features: WireFeatures;
+  /** Age of the entry in ms at read time. */
+  ageMs: number;
+}
+
+const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | undefined> => {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<undefined>((resolve) => {
+    timer = setTimeout(() => resolve(undefined), ms);
+  });
+  return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
+};
+
+/** Whether a cache entry is still within the TTL (server max-age aligned). */
+export const isFeaturesFresh = (ageMs: number, ttlMs: number = DEFAULT_FEATURES_TTL_MS): boolean =>
+  ageMs >= 0 && ageMs < ttlMs;
+
+/**
+ * Read the cached flags for `key`, or `undefined` when absent/corrupt/timed-out. Returns the
+ * value AND its age so a caller can apply a TTL (fresh) or ignore it (stale-while-error). Never
+ * throws; never hangs past the read timeout. The stored value is re-parsed through
+ * `parseWireFeatures`, so a partially-corrupt entry still degrades fail-open.
+ */
+export const readCachedFeatures = async (
+  storage: WireOnboardingStorage,
+  key: string,
+): Promise<CachedFeatures | undefined> => {
+  let raw: string | null | undefined;
+  try {
+    raw = await withTimeout(storage.getItem(key), READ_TIMEOUT_MS);
+  } catch {
+    return undefined;
+  }
+  if (!raw) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && typeof (parsed as { ts?: unknown }).ts === "number") {
+      const ts = (parsed as { ts: number }).ts;
+      return {
+        features: parseWireFeatures((parsed as { features?: unknown }).features),
+        ageMs: Date.now() - ts,
+      };
+    }
+  } catch {
+    // Corrupt entry → treat as absent; the caller falls back to defaults / a fresh fetch.
+  }
+  return undefined;
+};
+
+/** Persist `{ features, ts }` under `key` — fire-and-forget, all errors swallowed. */
+export const writeCachedFeatures = (
+  storage: WireOnboardingStorage,
+  key: string,
+  features: WireFeatures,
+): void => {
+  try {
+    void storage
+      .setItem(key, JSON.stringify({ features, ts: Date.now() }))
+      .catch(() => {});
+  } catch {
+    // Best-effort: a failed write just means the next launch has no cache to fall back to.
+  }
+};

package/src/features/defaults.ts

@@ -0,0 +1,67 @@
+/**
+ * The fail-open defaults + a tolerant parser for the server's flags payload.
+ *
+ * THE CONTRACT: fail-open, never fail-dark. An absent server object, a missing module key, a
+ * malformed value, or an unreachable endpoint must resolve to the MOST PERMISSIVE state — every
+ * module ON, onboarding `ai` — so a control-plane outage can only ever be more permissive than
+ * the dashboard intends. It can never dark a tenant's activation. Matches the server's own
+ * documented fail-open default (FEATURES.md: "local defaults — every module on, onboarding ai").
+ */
+import type { OnboardingMode, WireFeatures } from "./types";
+
+/**
+ * ALL ON, onboarding `ai`. Frozen + module-level so its reference is stable across every call
+ * (consumers that list resolved flags in an effect dep array never loop on a fresh identity).
+ */
+export const defaultWireFeatures: WireFeatures = Object.freeze({
+  coachmarks: Object.freeze({ enabled: true }),
+  showcase: Object.freeze({ enabled: true }),
+  onboarding: Object.freeze({ mode: "ai" as OnboardingMode }),
+  review: Object.freeze({ enabled: true }),
+  questionnaire: Object.freeze({ enabled: true }),
+  announcements: Object.freeze({ enabled: true }),
+}) as WireFeatures;
+
+const VALID_MODES: readonly OnboardingMode[] = ["ai", "static", "off"];
+
+/** Read a `{ enabled: boolean }` module, defaulting to ON when absent/malformed (fail-open). */
+const readEnabled = (raw: unknown): { enabled: boolean } => {
+  if (raw && typeof raw === "object" && typeof (raw as { enabled?: unknown }).enabled === "boolean") {
+    return { enabled: (raw as { enabled: boolean }).enabled };
+  }
+  return { enabled: true };
+};
+
+/**
+ * Narrow the server's (untrusted) JSON to a complete `WireFeatures`. Every field is filled with
+ * its fail-open default when the server omits it or sends the wrong type, so a partial or
+ * malformed payload degrades PERMISSIVELY rather than throwing. A non-object input (null, array,
+ * string) → the full defaults. Never throws.
+ */
+export const parseWireFeatures = (raw: unknown): WireFeatures => {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return defaultWireFeatures;
+  const src = raw as Record<string, unknown>;
+  const modeRaw = (src.onboarding as { mode?: unknown } | undefined)?.mode;
+  const mode: OnboardingMode =
+    typeof modeRaw === "string" && VALID_MODES.includes(modeRaw as OnboardingMode)
+      ? (modeRaw as OnboardingMode)
+      : "ai";
+  return {
+    coachmarks: readEnabled(src.coachmarks),
+    showcase: readEnabled(src.showcase),
+    onboarding: { mode },
+    review: readEnabled(src.review),
+    questionnaire: readEnabled(src.questionnaire),
+    announcements: readEnabled(src.announcements),
+  };
+};
+
+/** Value-equality of two resolved flags — lets the hook hold a stable reference across churn. */
+export const featuresEqual = (a: WireFeatures, b: WireFeatures): boolean =>
+  a === b ||
+  (a.coachmarks.enabled === b.coachmarks.enabled &&
+    a.showcase.enabled === b.showcase.enabled &&
+    a.onboarding.mode === b.onboarding.mode &&
+    a.review.enabled === b.review.enabled &&
+    a.questionnaire.enabled === b.questionnaire.enabled &&
+    a.announcements.enabled === b.announcements.enabled);

package/src/features/fetchWireFeatures.ts

@@ -0,0 +1,86 @@
+/**
+ * fetchWireFeatures — read the per-module kill switches from `GET {serverUrl}/v1/features`.
+ *
+ * Contract (server: chohra-med/wireai-onboarding-server, routers/onboarding.py):
+ *   GET {serverUrl}/v1/features
+ *   Authorization: Bearer {apiKey}
+ *   200 → { coachmarks:{enabled}, showcase:{enabled}, onboarding:{mode}, review:{enabled},
+ *           announcements:{enabled} }   (Cache-Control: private, max-age=300)
+ *
+ * THE CONTRACT — fail-open, never fail-dark. Unreachable, timed-out, unauthorized (401),
+ * server-error (5xx), or malformed JSON all resolve to the LAST CACHED value, else the
+ * all-on defaults. No throw ever reaches the host: this is timeout-capped and swallows every
+ * error, exactly like the session's best-effort reads. A control-plane outage can only ever be
+ * MORE permissive than the dashboard intends — it can never dark a tenant's activation.
+ */
+import { readCachedFeatures, featuresCacheKey, writeCachedFeatures } from "./cache";
+import { defaultWireFeatures, parseWireFeatures } from "./defaults";
+import type { WireFeatures, WireFeaturesConfig } from "./types";
+import type { WireOnboardingStorage } from "../session/persistedSession";
+
+const DEFAULT_TIMEOUT_MS = 4_000;
+
+/** The fail-open fallback: last cached value (any age — stale-while-error), else defaults. */
+const failOpen = async (
+  storage: WireOnboardingStorage | undefined,
+  key: string,
+): Promise<WireFeatures> => {
+  if (!storage) return defaultWireFeatures;
+  const cached = await readCachedFeatures(storage, key);
+  return cached?.features ?? defaultWireFeatures;
+};
+
+/** GET with a hard timeout via AbortController (falls back to no-abort where unsupported). */
+const fetchWithTimeout = async (
+  url: string,
+  apiKey: string,
+  timeoutMs: number,
+): Promise<Response> => {
+  const controller =
+    typeof AbortController !== "undefined" ? new AbortController() : undefined;
+  const timer = setTimeout(() => controller?.abort(), timeoutMs);
+  try {
+    return await fetch(url, {
+      method: "GET",
+      headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
+      signal: controller?.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/**
+ * Resolve the tenant's feature flags. Attempts the network once; on ANY failure returns the
+ * cached value (any age), else the all-on defaults. On success, persists the fresh value to the
+ * cache (fire-and-forget) and returns it. Never throws.
+ *
+ *   const flags = await fetchWireFeatures({ serverUrl, apiKey, appId, storage });
+ *   if (!flags.coachmarks.enabled) { /* skip the tour * / }
+ */
+export const fetchWireFeatures = async (
+  config?: WireFeaturesConfig,
+): Promise<WireFeatures> => {
+  const key = featuresCacheKey(config?.appId);
+  const storage = config?.storage;
+
+  // Nothing to fetch (no creds) → cache, else defaults. Lets a host mount the provider before
+  // its config is ready without ever darking.
+  if (!config?.serverUrl || !config?.apiKey) return failOpen(storage, key);
+
+  const url = `${config.serverUrl.replace(/\/$/, "")}/v1/features`;
+  const timeoutMs = config.timeoutMs && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS;
+
+  try {
+    const res = await fetchWithTimeout(url, config.apiKey, timeoutMs);
+    // 401 (bad/rotated key), 5xx, any non-2xx → last-known, never dark.
+    if (!res || !res.ok) return failOpen(storage, key);
+    const json: unknown = await res.json(); // throws on malformed body → caught below
+    const features = parseWireFeatures(json);
+    if (storage) writeCachedFeatures(storage, key, features);
+    return features;
+  } catch {
+    // Timeout/abort, network error, missing fetch, or malformed JSON — all fail open.
+    return failOpen(storage, key);
+  }
+};

package/src/features/index.ts

@@ -0,0 +1,39 @@
+/**
+ * wireai-onboarding feature controls — the per-module dashboard kill switches, consumed by the
+ * kit with a HARD fail-open contract (a control-plane outage can never dark your app).
+ *
+ * These live in the CORE barrel (dependency-free: types + fetch + a React hook/provider). The
+ * GATING is wired into the three client surfaces (coachmarks / showcase / reviews); onboarding
+ * mode is server-owned, so the kit needs no gating there.
+ *
+ *   import { WireFeaturesProvider, fetchWireFeatures } from "wireai-onboarding";
+ */
+export { fetchWireFeatures } from "./fetchWireFeatures";
+export { useWireFeatures } from "./useWireFeatures";
+export {
+  WireFeaturesProvider,
+  useWireFeaturesContext,
+  useResolvedFeatures,
+} from "./WireFeaturesProvider";
+export type {
+  WireFeaturesProviderProps,
+  ResolveFeaturesOptions,
+} from "./WireFeaturesProvider";
+export {
+  defaultWireFeatures,
+  parseWireFeatures,
+  featuresEqual,
+} from "./defaults";
+export {
+  featuresCacheKey,
+  readCachedFeatures,
+  writeCachedFeatures,
+  isFeaturesFresh,
+  DEFAULT_FEATURES_TTL_MS,
+} from "./cache";
+export type { CachedFeatures } from "./cache";
+export type {
+  WireFeatures,
+  WireFeaturesConfig,
+  OnboardingMode,
+} from "./types";

package/src/features/types.ts

@@ -0,0 +1,61 @@
+/**
+ * Public types for the feature-controls module — the per-module dashboard kill switches.
+ *
+ * Mirrors the server's `GET /v1/features` response (chohra-med/wireai-onboarding-server):
+ * one switch per activation surface, all fail-open. This file is dependency-free (types +
+ * the frozen default), so it stays in the CORE barrel — the gating lives in the dep-heavy
+ * subpaths (coachmarks / showcase / reviews) that consume these flags.
+ */
+import type { WireOnboardingStorage } from "../session/persistedSession";
+
+/**
+ * The onboarding module's three-way control. The kit needs NO gating for these: the SERVER
+ * owns the branch (`ai` = LLM flow, `static` = scripted zero-LLM flow over the same A2A
+ * contract, `off` = a terminal StatusCard the kit already reads as completion). Surfaced here
+ * only so a host can read the current mode. See the README "Onboarding mode" note.
+ */
+export type OnboardingMode = "ai" | "static" | "off";
+
+/**
+ * The resolved controls object. Every field is always present after parsing (missing server
+ * keys are filled with the fail-open default), so consumers read `flags.coachmarks.enabled`
+ * without guarding for absence.
+ */
+export interface WireFeatures {
+  /** Coachmarks / gesture hints (kit-gated in CoachmarkProvider + the overlay host). */
+  coachmarks: { enabled: boolean };
+  /** Pre-onboarding + post-onboarding value bridge (kit-gated in FeatureShowcase). */
+  showcase: { enabled: boolean };
+  /** Onboarding flow. Server-owned branch — informational for the kit (no gating). */
+  onboarding: { mode: OnboardingMode };
+  /** In-app review master switch (kit-gated in useReviewGate / ReviewGate). */
+  review: { enabled: boolean };
+  /** Pre-onboarding questionnaire master switch (kit-gated in the questionnaire module). */
+  questionnaire: { enabled: boolean };
+  /** Reserved — the announcements module is not built yet. No kit surface reads it. */
+  announcements: { enabled: boolean };
+}
+
+/**
+ * What `fetchWireFeatures` / `useWireFeatures` need to reach the control plane. Same tenant
+ * creds as the onboarding flow (`WireOnboardingConfig.serverUrl` + `apiKey`); `storage` is the
+ * OPTIONAL last-known cache channel (the same AsyncStorage-compatible subset the session uses).
+ */
+export interface WireFeaturesConfig {
+  /** Base server URL (same as `WireOnboardingConfig.serverUrl`); `/v1/features` is appended. */
+  serverUrl?: string;
+  /** Tenant API key; sent as `Authorization: Bearer`. */
+  apiKey?: string;
+  /**
+   * App id — scopes the cache key so one device caching flags for two tenants never collides.
+   * Optional; falls back to a shared `default` bucket when absent.
+   */
+  appId?: string;
+  /**
+   * Host-injected storage (AsyncStorage/MMKV subset) for the last-known-flags cache. Omit and
+   * the module still works — it just has no cache to fall back to (defaults on failure).
+   */
+  storage?: WireOnboardingStorage;
+  /** Network timeout in ms before the fetch is abandoned to the fail-open fallback. Default 4000. */
+  timeoutMs?: number;
+}

package/src/features/useWireFeatures.ts

@@ -0,0 +1,57 @@
+/**
+ * useWireFeatures — resolve the tenant's feature flags for a component tree, once per mount.
+ *
+ * Returns the all-on defaults immediately (fail-open), then swaps to the fetched value when the
+ * network resolves. When no `serverUrl`+`apiKey` is supplied it never fetches and just returns
+ * defaults, so a host that never adopts flags sees ZERO behavior change and ZERO network calls.
+ *
+ * frequent_rules #11 (unstable inline props): the config is idiomatically passed inline
+ * (`config={{ serverUrl, apiKey }}`), a fresh identity every render. We stabilize the fetch key
+ * by VALUE so the effect fires once per real credential change, and we only swap the returned
+ * flags object when its VALUES change — so a host that lists the returned flags in an effect dep
+ * array settles in a bounded number of commits instead of looping (enforced by the canary suite).
+ */
+import { useEffect, useRef, useState } from "react";
+
+import { defaultWireFeatures, featuresEqual } from "./defaults";
+import { fetchWireFeatures } from "./fetchWireFeatures";
+import type { WireFeatures, WireFeaturesConfig } from "./types";
+
+/** Hold a stable reference for a value while its CONTENT is unchanged (see reviews/equality.ts). */
+const useStableValue = <T,>(value: T, isEqual: (a: T, b: T) => boolean): T => {
+  const ref = useRef(value);
+  if (!isEqual(ref.current, value)) ref.current = value;
+  return ref.current;
+};
+
+/** The credential slice that actually drives a refetch — stabilized by value. */
+const sameFetchKey = (a: WireFeaturesConfig | undefined, b: WireFeaturesConfig | undefined): boolean =>
+  a?.serverUrl === b?.serverUrl && a?.apiKey === b?.apiKey && a?.appId === b?.appId;
+
+export const useWireFeatures = (config?: WireFeaturesConfig): WireFeatures => {
+  const stableConfig = useStableValue(config, sameFetchKey);
+  const [flags, setFlags] = useState<WireFeatures>(defaultWireFeatures);
+
+  const canFetch = !!stableConfig?.serverUrl && !!stableConfig?.apiKey;
+
+  useEffect(() => {
+    if (!canFetch) {
+      // No creds → stay on the all-on defaults (and reset if creds were removed).
+      setFlags((prev) => (featuresEqual(prev, defaultWireFeatures) ? prev : defaultWireFeatures));
+      return;
+    }
+    let alive = true;
+    // fetchWireFeatures never throws — the .then always runs with a fail-open value.
+    void fetchWireFeatures(stableConfig).then((next) => {
+      if (!alive) return;
+      // Only adopt a NEW reference on a real value change, so a host effect keyed on the
+      // returned flags doesn't loop (frequent_rules #11).
+      setFlags((prev) => (featuresEqual(prev, next) ? prev : next));
+    });
+    return () => {
+      alive = false;
+    };
+  }, [canFetch, stableConfig]);
+
+  return flags;
+};

package/src/identity/userIdentity.ts

@@ -0,0 +1,100 @@
+/**
+ * User identity — bind an onboarding session to the HOST's own user id so the funnel can
+ * be reconciled to real users later (console sessions ↔ your user table / GA4 users).
+ *
+ * The id is an OPAQUE PSEUDONYMOUS STRING the host owns — its internal user id, NOT an
+ * email/name/phone. Same host-injection philosophy as `storage` and `userContext`: the kit
+ * mints nothing and reads nothing; the host passes what it wants. Dependency-free.
+ *
+ * Three binding moments (see WireOnboarding + the README "User identity" section):
+ *   1. MOUNT      — pass `userId` and it rides the A2A session-start metadata; the server
+ *                   binds it when it creates the session.
+ *   2. MID-SESSION— the user registers DURING onboarding: change the `userId` prop and the
+ *                   kit emits an `identify` client event that attaches the id to the live
+ *                   session (late binding — the key scenario).
+ *   3. POST-FLOW  — the user registers AFTER onboarding: call `identifyOnboarding(...)` with
+ *                   the same host storage (it recovers the persisted contextId, before completion
+ *                   clears it) or, more reliably, the `contextId` you captured from the
+ *                   `started`/`resumed` `onEvent` (both events carry a `contextId` field).
+ *
+ * ⚠️ NO PII. Pass an opaque id (or a hash), never a raw email/name/phone. The id is capped at
+ * {@link USER_ID_MAX_LENGTH} chars (longer ids are truncated, not rejected).
+ */
+import { reportClientEvent } from "../analytics/reportClientEvent";
+import {
+  peekPersistedSession,
+  sessionStorageKey,
+  type WireOnboardingStorage,
+} from "../session/persistedSession";
+
+/** Max accepted user-id length. Longer strings are truncated (never rejected). Keep in sync
+ *  with the server's `USER_ID_MAX_LENGTH` (analytics/events.py). */
+export const USER_ID_MAX_LENGTH = 128;
+
+/**
+ * Normalize a host-supplied user id: trim, drop empty, and cap at {@link USER_ID_MAX_LENGTH}.
+ * Returns `undefined` for a missing/blank/non-string value so callers can `if (id)`-gate.
+ * PII is a host concern — this only bounds length, it does not (and cannot) detect an email.
+ */
+export const sanitizeUserId = (raw: unknown): string | undefined => {
+  if (typeof raw !== "string") return undefined;
+  const trimmed = raw.trim();
+  if (!trimmed) return undefined;
+  return trimmed.length > USER_ID_MAX_LENGTH ? trimmed.slice(0, USER_ID_MAX_LENGTH) : trimmed;
+};
+
+/** Options for {@link identifyOnboarding}. */
+export type IdentifyOnboardingOptions = {
+  /** Tenant transport, same shape as `WireOnboardingConfig` (only these two fields are used). */
+  config: { serverUrl: string; apiKey: string };
+  /** The host's opaque user id to bind. Trimmed + capped; NO PII. */
+  userId: string;
+  /**
+   * The onboarding session id to bind to (the A2A contextId) — the `contextId` field carried on
+   * the `started`/`resumed` `onEvent`. Pass this when you captured it there. Required after the
+   * flow COMPLETED, since completion clears the persisted session. Wins over the storage lookup.
+   */
+  contextId?: string;
+  /**
+   * The SAME host storage you passed to `<WireOnboarding storage={…} />`. When `contextId` is
+   * omitted, the helper reads the persisted contextId from it (works while the session is still
+   * persisted — i.e. dropped or mid-flow, before completion clears it).
+   */
+  storage?: WireOnboardingStorage;
+  /** App id, to derive the default storage key `wireai:session:<appId>` when reading from storage. */
+  appId?: string;
+  /** Storage key override — pass the same `persistKey` you gave `<WireOnboarding>`, if any. */
+  persistKey?: string;
+};
+
+/**
+ * Attach a host user id to an onboarding session AFTER the fact (post-registration), by sending
+ * an `identify` client event to `/v1/events`. Resolves the contextId from an explicit
+ * `contextId` or, failing that, from the persisted session in the host `storage`.
+ *
+ * Fire-and-forget under the hood (never throws, never blocks onboarding). Resolves to `true`
+ * when an identify event was dispatched, `false` when it couldn't (no user id, no server url,
+ * or no resolvable contextId).
+ */
+export const identifyOnboarding = async (
+  opts: IdentifyOnboardingOptions,
+): Promise<boolean> => {
+  const userId = sanitizeUserId(opts.userId);
+  if (!userId || !opts.config?.serverUrl) return false;
+
+  let contextId = opts.contextId?.trim() || undefined;
+  if (!contextId && opts.storage) {
+    const key = opts.persistKey ?? (opts.appId ? sessionStorageKey(opts.appId) : undefined);
+    if (key) {
+      const stored = await peekPersistedSession(opts.storage, key);
+      contextId = stored?.id;
+    }
+  }
+  if (!contextId) return false;
+
+  reportClientEvent(
+    { serverUrl: opts.config.serverUrl, apiKey: opts.config.apiKey },
+    { event_type: "identify", session_id: contextId, user_id: userId },
+  );
+  return true;
+};

package/src/illustrations/defaultIllustrations.tsx

@@ -0,0 +1,99 @@
+/**
+ * defaultIllustrations — a tiny, dependency-free fallback registry so an app can
+ * render `InterstitialCard` with ZERO illustration code. These are plain
+ * <View>/<Text> glyphs (NO react-native-svg, NO Lottie, NO image assets) themed
+ * from the active OnboardingTheme, covering the common backend-emitted names.
+ *
+ * Spread it under your own artwork — your named nodes win:
+ *
+ *   illustrations={{ ...defaultIllustrations, ...myIllustrations }}
+ *
+ * Names match what the onboarding backend commonly emits via an InterstitialCard's
+ * `illustration`: `momentum` (forward-motion arc) and `before-after` (two states).
+ * Add more by spreading your own — these are only sensible defaults.
+ */
+import React from "react";
+import { StyleSheet, Text, View } from "react-native";
+import { useOnboardingTheme } from "../theme/ThemeContext";
+
+/** A soft tinted disc with a centered glyph — the shared frame for every default. */
+const Glyph: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const t = useOnboardingTheme();
+  return (
+    <View
+      style={[
+        styles.disc,
+        { backgroundColor: t.colors.primarySoft, borderRadius: t.radius.full },
+      ]}
+    >
+      <Text style={[styles.glyphText, { color: t.colors.primary }]} allowFontScaling={false}>
+        {children}
+      </Text>
+    </View>
+  );
+};
+
+/** Forward-motion / momentum: an upward arrow. */
+const MomentumGlyph: React.FC = () => <Glyph>{"↗"}</Glyph>;
+
+/** Before → after: two states with an arrow between. */
+const BeforeAfterGlyph: React.FC = () => {
+  const t = useOnboardingTheme();
+  return (
+    <View style={styles.row}>
+      <View
+        style={[
+          styles.chip,
+          { borderColor: t.colors.border, borderRadius: t.radius.md },
+        ]}
+      />
+      <Text style={[styles.arrow, { color: t.colors.primary }]} allowFontScaling={false}>
+        {"→"}
+      </Text>
+      <View
+        style={[
+          styles.chip,
+          { backgroundColor: t.colors.primarySoft, borderColor: t.colors.primary, borderRadius: t.radius.md },
+        ]}
+      />
+    </View>
+  );
+};
+
+/**
+ * The default registry. `WireOnboarding`'s `illustrations` prop is
+ * `Record<string, ReactNode>`, so these are concrete element nodes.
+ */
+export const defaultIllustrations: Record<string, React.ReactNode> = {
+  momentum: <MomentumGlyph />,
+  "before-after": <BeforeAfterGlyph />,
+};
+
+const styles = StyleSheet.create({
+  disc: {
+    width: 96,
+    height: 96,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  glyphText: {
+    fontSize: 44,
+    fontWeight: "700",
+    lineHeight: 52,
+  },
+  row: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: 12,
+  },
+  chip: {
+    width: 56,
+    height: 56,
+    borderWidth: 2,
+  },
+  arrow: {
+    fontSize: 28,
+    fontWeight: "700",
+  },
+});