@wireai/activation 0.12.2 → 0.13.2

package/src/permissions/permissionMemory.ts

@@ -0,0 +1,88 @@
+/**
+ * permissionMemory - "shown exactly once per session", kept true across an app kill.
+ *
+ * The in-memory guard alone is not enough. The kit already resumes a killed onboarding into the
+ * SAME backend session (see `persistedSession.ts`), so without a persisted record the resumed mount
+ * would re-show a permission screen the user had already answered - and on the ask path that means
+ * a second dialog attempt against an OS that grants exactly one.
+ *
+ * The record is SCOPED TO THE SESSION ID, one entry, never a growing map: a record whose
+ * `sessionId` is not the session being resumed is stale by definition and reads as empty. That is
+ * also what makes a genuinely new onboarding start clean without anything having to expire it.
+ *
+ * Same host-injected `WireOnboardingStorage` and the same best-effort discipline as the session
+ * seed: reads race the shared ceiling and degrade to "nothing remembered", writes swallow every
+ * error. A broken storage adapter must never gate or break onboarding.
+ */
+import {
+  READ_TIMEOUT_MS,
+  withTimeout,
+  type WireOnboardingStorage,
+} from "../session/persistedSession";
+
+/** Storage key for an app's settled permission screens, e.g. `wireai:permissions:acme`. */
+export const permissionStorageKey = (appId: string): string => `wireai:permissions:${appId}`;
+
+type PermissionRecord = { sessionId: string; ids: string[] };
+
+/**
+ * PURE seam: which screen ids a stored blob contributes to THIS session. A corrupt entry, a
+ * malformed shape, or a record belonging to a different session all read as "nothing remembered",
+ * because re-showing a screen is a far cheaper failure than trusting another session's answers.
+ */
+export const readSettledPermissions = (
+  raw: string | null | undefined,
+  sessionId: string,
+): string[] => {
+  if (!raw || !sessionId) return [];
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) return [];
+    const record = parsed as Partial<PermissionRecord>;
+    if (record.sessionId !== sessionId || !Array.isArray(record.ids)) return [];
+    return record.ids.filter((id): id is string => typeof id === "string" && id.length > 0);
+  } catch {
+    // Corrupt entry: treat as absent. The next write overwrites it.
+    return [];
+  }
+};
+
+/** Read the settled ids for `sessionId`. Never throws, never hangs past the shared read ceiling. */
+export const loadSettledPermissions = async (
+  storage: WireOnboardingStorage,
+  key: string,
+  sessionId: string,
+): Promise<string[]> => {
+  try {
+    return readSettledPermissions(await withTimeout(storage.getItem(key), READ_TIMEOUT_MS), sessionId);
+  } catch {
+    return [];
+  }
+};
+
+/** Persist the settled ids for `sessionId` - fire-and-forget, all errors swallowed. */
+export const saveSettledPermissions = (
+  storage: WireOnboardingStorage,
+  key: string,
+  sessionId: string,
+  ids: readonly string[],
+): void => {
+  try {
+    const record: PermissionRecord = { sessionId, ids: [...ids] };
+    void storage.setItem(key, JSON.stringify(record)).catch(() => {});
+  } catch {
+    // Best-effort: a failed write only means a resumed session may re-show the screen.
+  }
+};
+
+/** Drop the record (fired alongside the session seed on completion) - fire-and-forget. */
+export const clearSettledPermissions = (
+  storage: WireOnboardingStorage,
+  key: string,
+): void => {
+  try {
+    void storage.removeItem(key).catch(() => {});
+  } catch {
+    // Best-effort.
+  }
+};

package/src/permissions/placement.ts

@@ -0,0 +1,88 @@
+/**
+ * placement - WHERE an injected permission screen lands in a stream nobody knows the length of.
+ *
+ * The card stream is server-driven: the backend decides how many questions this user gets, and the
+ * count differs per user and per run. So a placement is never an index into a known list; it is a
+ * predicate evaluated against the card the flow is ABOUT to render, on every turn.
+ *
+ * THE CLAMP is the whole reason this is a function and not a comparison. `{ afterCard: 4 }` against
+ * a stream that ended after 3 would simply never fire, and "the screen silently never showed" is
+ * the exact failure a host cannot see. So an unreached target degrades to `"beforeEnd"`: the
+ * terminal card is the last position where the screen can still exist, so that is where it goes.
+ *
+ * PURE, no React, no React Native - the placement math is the part worth unit-testing.
+ */
+import type { PermissionPlacement, PermissionScreenConfig } from "./types";
+
+/** Where a screen sits when the host does not say. High intent, and it can never be clamped away. */
+export const DEFAULT_PERMISSION_PLACEMENT: PermissionPlacement = "beforeEnd";
+
+/** The flow position a placement is resolved against. */
+export type FlowPosition = {
+  /** 0-based index of the card about to render. `-1` when no card has arrived yet. */
+  cardIndex: number;
+  /** Whether that card is the terminal recap, i.e. the flow's last screen. */
+  isTerminal: boolean;
+};
+
+/** `afterCard` from a host is arbitrary input: floor it, floor it at 0, and never let NaN through. */
+export const normalizeAfterCard = (value: number): number =>
+  Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+
+/** The 0-based card index a placement targets. `"beforeEnd"` has none, it rides `isTerminal`. */
+const targetIndex = (placement: PermissionPlacement): number | undefined => {
+  if (placement === "beforeEnd") return undefined;
+  if (placement === "start") return 0;
+  return normalizeAfterCard(placement.afterCard);
+};
+
+/**
+ * Is a screen with this placement due at this position?
+ *
+ * `>=` rather than `===` on purpose: due-ness is re-evaluated every render and a screen is settled
+ * the moment it is answered, so a target the flow has already passed (because a screen ahead of it
+ * in the array was on screen for those turns) still fires instead of being skipped forever.
+ */
+export const isPermissionDue = (
+  placement: PermissionPlacement,
+  position: FlowPosition,
+): boolean => {
+  if (position.cardIndex < 0) return false;
+  const target = targetIndex(placement);
+  // "beforeEnd", or an `afterCard` the stream ended before reaching: the terminal card is the
+  // last chance, so this is where the clamp lands.
+  if (target === undefined) return position.isTerminal;
+  return position.cardIndex >= target || position.isTerminal;
+};
+
+/**
+ * The stable id a screen is remembered by across a resume. Defaults to `<permission>:<index>`,
+ * which is right until the array is reordered - hence the documented `id` escape hatch.
+ */
+export const permissionScreenId = (screen: PermissionScreenConfig, index: number): string =>
+  screen.id ?? `${screen.permission}:${index}`;
+
+/** A due screen and the id it is remembered by. */
+export type DuePermissionScreen = { screen: PermissionScreenConfig; id: string };
+
+/**
+ * The FIRST configured screen that is due here and has not already been settled in this session.
+ * One at a time, in array order, so two screens due at the same position queue rather than collide.
+ */
+export const selectDuePermissionScreen = (
+  screens: readonly PermissionScreenConfig[] | undefined,
+  settled: readonly string[],
+  position: FlowPosition,
+): DuePermissionScreen | undefined => {
+  if (!screens || screens.length === 0) return undefined;
+  for (let index = 0; index < screens.length; index++) {
+    const screen = screens[index];
+    if (!screen) continue;
+    const id = permissionScreenId(screen, index);
+    if (settled.includes(id)) continue;
+    if (isPermissionDue(screen.placement ?? DEFAULT_PERMISSION_PLACEMENT, position)) {
+      return { screen, id };
+    }
+  }
+  return undefined;
+};

package/src/permissions/types.ts

@@ -0,0 +1,131 @@
+/**
+ * Public types for the injectable mid-flow permission screens.
+ *
+ * THE ONE RULE THIS WHOLE MODULE EXISTS TO ENFORCE: the OS permission dialog is reached from the
+ * user's explicit primary tap and from nowhere else. iOS grants an app exactly ONE native
+ * notification prompt for its entire lifetime, so firing it on mount (the shape almost every app
+ * ships) spends the single ask on a user who has not been told why. A priming screen spends a
+ * cheap in-app screen first and only forwards the ones who said yes.
+ *
+ * DEPENDENCY-FREE, the RevenueCat-bridge idiom: the kit imports NO native permission module. The
+ * host passes `request` (and optionally `getStatus` / `openSettings`) in, exactly the way it hands
+ * the RevenueCat bridge real `CustomerInfo` objects. Wiring `expo-notifications` is five lines in
+ * the host and zero dependencies here.
+ *
+ * A PERMISSION SCREEN IS NOT A QUESTION. It mints no `key` and no `slot_id`, sends nothing to the
+ * backend, and never enters the thread, so `deriveAnswers` / `readProgress` and every completion
+ * semantic are byte-identical whether or not one is configured. Completion NEVER blocks on a grant.
+ */
+import type { PermissionScreenCopy } from "./permissionCopy";
+
+export type { PermissionScreenCopy } from "./permissionCopy";
+
+/**
+ * Which OS permission a screen primes. `notifications` is the one the kit ships copy for; any other
+ * string is accepted (the host supplies the copy) so a host can prime tracking, health or location
+ * without waiting on a kit release.
+ */
+export type WirePermissionKind = "notifications" | (string & {});
+
+/**
+ * What the host's `request` / `getStatus` answers.
+ *  - `granted`: the user allowed it.
+ *  - `denied`: not allowed right now, but the OS would still show a dialog if asked again
+ *    (Android, or an iOS provisional state).
+ *  - `blocked`: permanently refused. Asking again shows NOTHING, so the only route left is Settings.
+ */
+export type WirePermissionStatus = "granted" | "denied" | "blocked";
+
+/** How a permission screen ENDED. `skipped` is the secondary tap, which never burns the OS prompt. */
+export type WirePermissionOutcome = WirePermissionStatus | "skipped";
+
+/**
+ * The moments a permission screen reports. One stage, one canonical event name (see
+ * `permissionEventName`), so the funnel reads the same across every tenant.
+ *  - `shown`: the primer screen became visible. The denominator.
+ *  - `accepted`: the user tapped the primary, so the OS dialog is ABOUT to open. The gap between
+ *    `shown` and `accepted` is the only number that tells a host whether its rationale copy works.
+ *  - `granted` / `denied`: what the OS answered (a `blocked` answer reports as `denied` and carries
+ *    `status: "blocked"`, so the two are one funnel step and still distinguishable).
+ *  - `skipped`: the secondary tap. The prompt was NOT spent.
+ *  - `settings`: the user was redirected to the OS settings page (the `blocked` route).
+ */
+export type PermissionStage =
+  | "shown"
+  | "accepted"
+  | "granted"
+  | "denied"
+  | "skipped"
+  | "settings";
+
+/**
+ * WHERE a screen sits in the server-driven stream. The flow length is decided by the backend and
+ * varies per user, so every position is resolved against the card the flow is ABOUT to render:
+ *  - `"start"`: before the first card.
+ *  - `{ afterCard: n }`: after `n` cards have been shown (`{ afterCard: 2 }` sits between card 2
+ *    and card 3). An `n` past the end of a shorter-than-expected stream degrades to `"beforeEnd"`
+ *    rather than silently never showing.
+ *  - `"beforeEnd"`: immediately before the terminal recap. The default.
+ */
+export type PermissionPlacement = "start" | "beforeEnd" | { afterCard: number };
+
+/**
+ * One injectable permission screen.
+ *
+ * ```tsx
+ * import * as Notifications from "expo-notifications";
+ *
+ * <WireOnboarding
+ *   permissionScreens={[
+ *     {
+ *       permission: "notifications",
+ *       placement: "beforeEnd",
+ *       request: async () => {
+ *         const { status, canAskAgain } = await Notifications.requestPermissionsAsync();
+ *         return status === "granted" ? "granted" : canAskAgain ? "denied" : "blocked";
+ *       },
+ *     },
+ *   ]}
+ * />
+ * ```
+ */
+export type PermissionScreenConfig = {
+  /** Which permission this screen primes. Drives the default copy and every event's `permission`. */
+  permission: WirePermissionKind;
+  /**
+   * Stable id for the once-only / resume record. Defaults to `<permission>:<index in the array>`,
+   * which is right until you reorder the array; set it explicitly if you configure two screens for
+   * the same permission or intend to reorder them between releases.
+   */
+  id?: string;
+  /** Where the screen sits in the stream. Default `"beforeEnd"`. */
+  placement?: PermissionPlacement;
+  /**
+   * THE ONLY FUNCTION THE KIT CALLS THAT CAN OPEN AN OS DIALOG, and it is called from the primary
+   * press handler alone. Never from mount, never from an effect, never from a status probe.
+   */
+  request: () => Promise<WirePermissionStatus>;
+  /**
+   * Optional NON-PROMPTING status read (`Notifications.getPermissionsAsync()`), used only to pick
+   * which primary action the screen offers: a `blocked` user gets "Open settings" instead of an
+   * "Enable" button that would open nothing, and an already-granted user gets a plain Continue.
+   * Leave it out and the screen simply always offers the ask.
+   */
+  getStatus?: () => Promise<WirePermissionStatus>;
+  /** Open the OS settings page (`Linking.openSettings()`). Only reachable on the `blocked` route. */
+  openSettings?: () => void | Promise<void>;
+  /** Rationale copy overrides. Anything left out keeps the kit default for this permission. */
+  copy?: Partial<PermissionScreenCopy>;
+  /**
+   * Name of a host illustration (the existing `illustrations` registry). Defaults to the
+   * permission name, so registering `illustrations={{ notifications: <MyBell/> }}` is enough. The
+   * kit ships a dependency-free default so the screen is never a blank box.
+   */
+  illustration?: string;
+  /**
+   * Fired once, with the outcome this screen produced. This is the seam for scheduling a local
+   * notification the moment a grant lands; the kit deliberately schedules nothing itself. It can
+   * never break the flow: a throw here is caught and the flow continues.
+   */
+  onResult?: (permission: WirePermissionKind, outcome: WirePermissionOutcome) => void;
+};

package/src/session/persistedSession.ts

@@ -37,7 +37,7 @@ export type WireOnboardingStorage = {
 export const DEFAULT_SESSION_TTL_MS = 3_600_000;
 
 /** Ceiling on the storage read — a hung adapter degrades to a fresh mint, never a stuck gate. */
-const READ_TIMEOUT_MS = 1_500;
+export const READ_TIMEOUT_MS = 1_500;
 
 /** Storage key for an app's cached session, e.g. `wireai:session:acme`. */
 export const sessionStorageKey = (appId: string): string => `wireai:session:${appId}`;
@@ -51,7 +51,14 @@ export type LoadedSession = {
   resumed: boolean;
 };
 
-const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | undefined> => {
+/**
+ * Race a storage read against a ceiling, resolving `undefined` when the adapter did not answer.
+ * Exported so the permission memory reads through the same ceiling as the session seed rather than
+ * carrying a second copy of it. NOT the kit's only such helper: `features/cache.ts`,
+ * `session-analytics/lifecycle.ts` and `analytics/eventQueue.ts` each keep their own local timeout
+ * for their own transports. Consolidating those is a separate change, not this one.
+ */
+export 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);
@@ -150,7 +157,7 @@ export const clearPersistedSession = (storage: WireOnboardingStorage, key: strin
  * not opt in.)
  *
  *  - undefined / false (the default) → `true`: clear on completion, so the NEXT onboarding on this
- *    device mints a fresh session. This is the legacy single-stage behavior (e.g. Myelino).
+ *    device mints a fresh session. This is the legacy single-stage behavior.
  *  - true → `false`: LEAVE the seed in place so a same-signup re-entry/remount within the TTL
  *    resumes the SAME session (one funnel start) instead of minting a phantom second `started`.
  *    Freshness for a genuinely new run is then governed by the TTL (past `sessionTtlMs` → fresh

package/src/session-analytics/useLifecycleEvents.ts

@@ -33,6 +33,7 @@ import { AppState, Platform, type AppStateStatus } from "react-native";
 import { createEventQueue, type EnvelopeSource, type EventQueue } from "../analytics/eventQueue";
 import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../analytics/reportClientEvent";
 import { hydrateAutoDeviceKey, resolveAutoDeviceKey } from "../context/deviceId";
+import { resolveIdentity } from "../identity/identityRecord";
 import { collectDeviceContext } from "../device/deviceContext";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 import { reportFirstOpen } from "./lifecycle";
@@ -137,7 +138,15 @@ export const useLifecycleEvents = (
       cfg: LifecycleConfig | undefined,
       opts: UseLifecycleEventsOptions,
     ): string | undefined => {
-      const host = typeof opts.deviceKey === "string" && opts.deviceKey.trim() ? opts.deviceKey : undefined;
+      // A HOST-supplied key is recorded on the process provenance registry, so a `<WireOnboarding>`
+      // mount that was not given one can tell "this app owns no device id" from "this app owns one
+      // and forgot it there" — the silent third id space (K9). Recording only; nothing reads it here.
+      const host = resolveIdentity({
+        value: opts.deviceKey,
+        space: "device",
+        source: "host",
+        scope: cfg?.appId,
+      })?.value;
       if (host) return host;
       if (!cfg?.storage) return undefined;
       return resolveAutoDeviceKey({ appId: cfg.appId, storage: cfg.storage });

package/src/types.ts

@@ -4,6 +4,12 @@
 import type { Message } from "wireai-rn";
 import type { OnboardingTheme } from "./theme/types";
 import type { WireOnboardingStorage } from "./session/persistedSession";
+import type {
+  PermissionScreenConfig,
+  PermissionStage,
+  WirePermissionKind,
+  WirePermissionStatus,
+} from "./permissions/types";
 
 export type { OnboardingTheme } from "./theme/types";
 export type { WireOnboardingStorage } from "./session/persistedSession";
@@ -65,6 +71,10 @@ export type OnboardingResult = {
  *  - `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.
+ *  - `permission`: an injected permission screen moved (`shown` / `accepted` / `granted` /
+ *               `denied` / `skipped` / `settings`). Carries NO funnel weight: a permission screen
+ *               is not a question, so it never appears in `answers` and never gates completion.
+ *               `toAnalyticsEvent` maps it to the canonical `wire_permission_*` name.
  */
 export type OnboardingEvent =
   | { type: "started"; contextId: string }
@@ -72,7 +82,14 @@ export type OnboardingEvent =
   | { type: "turn"; step: number; component?: string }
   | { type: "error"; reason: "backend" | "timeout" }
   | { type: "retry"; reason: "backend" | "timeout"; attempt: number }
-  | { type: "fallback"; reason: "backend" | "timeout" };
+  | { type: "fallback"; reason: "backend" | "timeout" }
+  | {
+      type: "permission";
+      permission: WirePermissionKind;
+      stage: PermissionStage;
+      /** What the OS actually answered, when it answered. Absent on `shown` / `accepted`. */
+      status?: WirePermissionStatus;
+    };
 
 /**
  * Copy overrides for the kit's built-in (English) strings, so a host can localize
@@ -118,6 +135,48 @@ export type WireOnboardingProps = {
   icons?: Record<string, import("react").ReactNode>;
   /** Per-step validators keyed by base-question key, e.g. `{ username: checkUsername }`. */
   validators?: Record<string, StepValidator>;
+  /**
+   * PERMISSION SCREENS injected into the server-driven flow at a position you choose.
+   *
+   * The screen explains why the app wants the permission and asks the OS **only** on the primary
+   * tap. That priming pattern is not decoration: iOS grants an app exactly ONE native notification
+   * prompt for its whole lifetime, and firing it on mount spends it on a user who was told nothing.
+   * "Maybe later" advances the flow with the prompt still unspent.
+   *
+   * ```tsx
+   * import * as Notifications from "expo-notifications";
+   *
+   * <WireOnboarding
+   *   permissionScreens={[
+   *     {
+   *       permission: "notifications",
+   *       placement: "beforeEnd",
+   *       request: async () => {
+   *         const { status, canAskAgain } = await Notifications.requestPermissionsAsync();
+   *         return status === "granted" ? "granted" : canAskAgain ? "denied" : "blocked";
+   *       },
+   *       getStatus: async () => {
+   *         const { status, canAskAgain } = await Notifications.getPermissionsAsync();
+   *         return status === "granted" ? "granted" : canAskAgain ? "denied" : "blocked";
+   *       },
+   *       onResult: (_p, outcome) => { if (outcome === "granted") scheduleFirstReminder(); },
+   *     },
+   *   ]}
+   * />
+   * ```
+   *
+   * The kit adds NO dependency for this: it imports no `expo-notifications`, no
+   * `react-native-permissions`, nothing native. You inject `request`, exactly the way you hand the
+   * RevenueCat bridge real RevenueCat objects.
+   *
+   * A permission screen is NOT a question. It sends nothing to the backend, never enters the
+   * thread, mints no `key` / `slot_id`, and never appears in `onComplete`'s `answers`. Completion
+   * never blocks on a grant: grant, deny, skip and blocked all continue the flow. Each screen is
+   * shown at most once per session, and with `storage` that survives an app kill (a resumed session
+   * does not re-ask). Analytics ride `onEvent` (`type: "permission"`) and the canonical
+   * `wire_permission_*` events, stamped with the same `device_key` as the rest of the funnel.
+   */
+  permissionScreens?: PermissionScreenConfig[];
   /** Fired once the flow reaches its terminal StatusCard. */
   onComplete: (result: OnboardingResult) => void;
   /**
@@ -272,6 +331,23 @@ export type OnboardingProgress = {
   total: number;
   /** Base-question key for the CURRENT screen, when known (used to pick a validator). */
   key?: string;
+  /**
+   * STABLE per-slot identity for the CURRENT screen, when the backend sends one. Preferred over
+   * {@link key} for both the answer key and the validator lookup.
+   *
+   * WHY IT EXISTS: `key` is authored from the question's prompt text (the tenant flows slugify it and
+   * cut at 32 chars), so re-wording a question mints a NEW key — the answer a host reads as
+   * `answers.interests` silently becomes `answers.what_are_you_into_v2`, with no error anywhere. A
+   * slot is the question's identity independent of its wording.
+   *
+   * FULLY ADDITIVE, AND LIVE SINCE 2026-07-28 (server `47dae92`). The deployed server sends it on
+   * `progress` for every AI-GENERATED question, as `adaptive_<n>` 1-based over adaptive answers, and
+   * for a CONFIGURED question only when the tenant set one. Where the tenant set none the field is
+   * simply absent. Every fallback is PER-CARD, so a thread that mixes slotted and unslotted cards
+   * (the real shape during a rollout) keys each one correctly, and a backend or tenant that never
+   * sends it produces byte-identical behaviour to 0.12.2.
+   */
+  slot_id?: string;
   /** Whether the CURRENT screen may be skipped (backend-marked; default false → no Skip shown). */
   skippable?: boolean;
 };

package/src/utils/deriveAnswers.ts

@@ -29,10 +29,14 @@ export const deriveAnswers = (messages: Message[]): Record<string, unknown> => {
     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 progress = props.progress as { key?: string; slot_id?: string } | undefined;
     const questionText =
       (props.title as string) ?? (props.label as string) ?? (props.question as string);
-    const key = progress?.key || questionText;
+    // slot_id > key > question text, decided PER CARD. A thread that mixes slotted and unslotted
+    // cards is the real shape during a server rollout, so caching a "this backend does slots" verdict
+    // off the first card would mis-key every later one. Against a backend that sends no `slot_id`
+    // this is byte-identical to 0.12.2.
+    const key = progress?.slot_id || progress?.key || questionText;
 
     const reply = messages[i + 1];
     if (key && reply?.role === "user") {

package/src/utils/readProgress.ts

@@ -15,6 +15,8 @@ type PartialProgress = {
   step?: number;
   total?: number;
   key?: string;
+  /** The stable per-slot identity, when the backend sends one. See `OnboardingProgress.slot_id`. */
+  slot_id?: string;
   skippable?: boolean;
 };
 
@@ -28,6 +30,8 @@ export const readProgress = (response?: WireAIResponse): PartialProgress => {
     step: typeof p.step === "number" ? p.step : undefined,
     total: typeof p.total === "number" ? p.total : undefined,
     key: typeof p.key === "string" ? p.key : undefined,
+    // Whitelisted the same way as every other field: an old backend simply omits it.
+    slot_id: typeof p.slot_id === "string" ? p.slot_id : undefined,
     skippable: typeof p.skippable === "boolean" ? p.skippable : undefined,
   };
 };

package/src/utils/warnInDev.ts

@@ -0,0 +1,33 @@
+/**
+ * warnInDev — the ONE developer-warning primitive.
+ *
+ * The kit warns a developer in four places (the onboarding host, the env-config helper, the analytics
+ * façade, the current-session registry) and until 0.13.0 each carried its own copy of the same five
+ * lines. Three were byte-identical; the fourth differed only by returning whether it actually warned.
+ * Four copies of a guard is four chances for one of them to drift out of the `__DEV__` gate, which is
+ * the failure that matters: a warning that runs in production is a string built for nobody.
+ *
+ * ON THE TREE-SHAKING NOTE THIS REPLACES: `analytics/currentSession` used to justify its copy as
+ * keeping the module import-free for the tree-shaken `./analytics` bundle. That rationale had already
+ * lapsed — the module imports `makeSessionId` from `./reportClientEvent` — and this module has no
+ * imports of its own, so it adds one leaf to the graph and nothing to the bundle. The `treeShake`
+ * canary still holds the real guarantee (the analytics graph reaches no UI module).
+ */
+
+/** RN sets this global; absent under node/SSR. Read defensively, never assumed. */
+declare const __DEV__: boolean | undefined;
+
+/**
+ * Emit a one-line developer warning, but ONLY in a dev build (RN `__DEV__`). No-op in prod/tests.
+ *
+ * Returns whether it ACTUALLY warned, which a caller holding a once-flag must honour: marking
+ * "already warned" after a no-op would burn the single warning in production, and the one dev build
+ * that needed it would then run silent.
+ */
+export const warnInDev = (message: string): boolean => {
+  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+    console.warn(message);
+    return true;
+  }
+  return false;
+};

package/src/components/DoneBlock.tsx

@@ -1,37 +0,0 @@
-/**
- * DoneBlock — a brief themed "all set" state shown when the flow completes, while
- * the host persists results and navigates away. Purely cosmetic; the real
- * terminal signal is the SDK's StatusCard (handled in OnboardingFlow).
- */
-import React from "react";
-import { StyleSheet, Text, View } from "react-native";
-import { useOnboardingTheme } from "../theme/ThemeContext";
-import { bodyStyle, headingStyle } from "../theme/typography";
-
-export type DoneBlockProps = {
-  title?: string;
-  message?: string;
-};
-
-const _DoneBlock: React.FC<DoneBlockProps> = ({
-  title = "You're all set",
-  message = "Personalizing your experience…",
-}) => {
-  const t = useOnboardingTheme();
-  return (
-    <View style={[styles.center, { gap: t.spacing.sm, padding: t.spacing.lg }]}>
-      <Text style={[headingStyle(t.fonts), { color: t.colors.success, textAlign: "center" }]}>
-        {title}
-      </Text>
-      <Text style={[bodyStyle(t.fonts), { color: t.colors.textMuted, textAlign: "center" }]}>
-        {message}
-      </Text>
-    </View>
-  );
-};
-
-export const DoneBlock = React.memo(_DoneBlock);
-
-const styles = StyleSheet.create({
-  center: { flex: 1, alignItems: "center", justifyContent: "center" },
-});