@wireai/activation 0.13.0 → 0.13.2

package/src/permissions/permissionCopy.ts

@@ -0,0 +1,87 @@
+/**
+ * permissionCopy - the rationale a priming screen shows, and the kit-quality defaults behind it.
+ *
+ * Same job the `copy` prop does for the loaders: the kit ships English that is good enough to
+ * ship as-is, and a host overrides any single line without having to restate the rest.
+ *
+ * PURE, no React, no React Native - so the resolution is unit-testable and the same function can
+ * later resolve copy a server sent.
+ */
+import type { WirePermissionKind } from "./types";
+
+/** Every string a permission screen can render. Both states (the ask and the blocked route). */
+export type PermissionScreenCopy = {
+  /** Headline for the ask. */
+  title: string;
+  /** The rationale. The one thing that decides whether the primary gets tapped. */
+  message: string;
+  /** Primary button. Tapping it is the ONLY thing that can open the OS dialog. */
+  primaryLabel: string;
+  /** Secondary button. Advances the flow and does NOT spend the one native prompt. */
+  secondaryLabel: string;
+  /** Headline once the OS says the permission is permanently refused. */
+  blockedTitle: string;
+  /** Rationale for the blocked state, where the only remaining route is the settings app. */
+  blockedMessage: string;
+  /** Primary button on the blocked route. */
+  settingsLabel: string;
+  /** Primary button when there is nothing left to ask for (already granted, or no `request`). */
+  continueLabel: string;
+};
+
+/**
+ * The notification default. Written to the same bar as the kit's other shipped copy: it names the
+ * benefit in the user's terms and promises a limit, because "we would like to send you
+ * notifications" is exactly the sentence that spends the one iOS prompt on a no.
+ */
+export const NOTIFICATIONS_PERMISSION_COPY: PermissionScreenCopy = {
+  title: "Want a nudge at the right moment?",
+  message:
+    "Turn notifications on and we will remind you when it actually helps. No daily noise, and you can turn them off any time.",
+  primaryLabel: "Enable notifications",
+  secondaryLabel: "Maybe later",
+  blockedTitle: "Notifications are switched off",
+  blockedMessage:
+    "Notifications are turned off for this app, so we cannot ask from here. You can switch them back on in Settings.",
+  settingsLabel: "Open settings",
+  continueLabel: "Continue",
+};
+
+/** The fallback for any permission the kit ships no copy for. A host overriding `copy` replaces it. */
+export const GENERIC_PERMISSION_COPY: PermissionScreenCopy = {
+  title: "One quick permission",
+  message: "We need your permission for this part to work. You can change it any time.",
+  primaryLabel: "Allow",
+  secondaryLabel: "Maybe later",
+  blockedTitle: "Permission is switched off",
+  blockedMessage:
+    "This permission is turned off for this app, so we cannot ask from here. You can switch it back on in Settings.",
+  settingsLabel: "Open settings",
+  continueLabel: "Continue",
+};
+
+/** The kit's shipped defaults, by permission. Anything not listed falls back to the generic set. */
+export const DEFAULT_PERMISSION_COPY: Record<string, PermissionScreenCopy> = {
+  notifications: NOTIFICATIONS_PERMISSION_COPY,
+};
+
+/**
+ * The kit default for `permission`, with the host's overrides applied on top.
+ *
+ * An override key whose value is `undefined` is IGNORED rather than allowed to blank the default:
+ * hosts build this object from their i18n layer, and a missing translation resolving to `undefined`
+ * would otherwise render an empty button.
+ */
+export const resolvePermissionCopy = (
+  permission: WirePermissionKind,
+  overrides?: Partial<PermissionScreenCopy>,
+): PermissionScreenCopy => {
+  const base = DEFAULT_PERMISSION_COPY[permission] ?? GENERIC_PERMISSION_COPY;
+  if (!overrides) return base;
+  const merged: PermissionScreenCopy = { ...base };
+  for (const key of Object.keys(overrides) as Array<keyof PermissionScreenCopy>) {
+    const value = overrides[key];
+    if (typeof value === "string" && value.length > 0) merged[key] = value;
+  }
+  return merged;
+};

package/src/permissions/permissionEvents.ts

@@ -0,0 +1,76 @@
+/**
+ * permissionEvents - the canonical Wire names for a permission-priming funnel.
+ *
+ * Same job `purchaseEvents.ts` does for the subscription funnel and `analyticsEvent.ts` does for
+ * the onboarding funnel: every app was naming these itself (`push_permission`, `NOTIF_PROMPT`,
+ * `notifications_allowed`), so the same funnel read differently per tenant and no cross-app report
+ * was possible. These are the ONE set of names.
+ *
+ * They are `app_event` `question_key` values on the wire, exactly like `WIRE_PURCHASE_EVENTS`, so
+ * they are ALSO the exact strings a review / questionnaire firing trigger matches on. Never rename
+ * one: a rename silently unfires every trigger configured against the old string.
+ *
+ * PURE + dependency-free: no React, no React Native, no transport, no imports outside the type
+ * declarations - so an analytics-only bundle can carry the names without carrying a screen.
+ */
+import type { PermissionStage, WirePermissionKind, WirePermissionStatus } from "./types";
+
+export const WIRE_PERMISSION_EVENTS = {
+  /** The priming screen became visible. The denominator for every rate below. */
+  screenShown: "wire_permission_screen_shown",
+  /** The user tapped the primary, so the OS dialog is about to open. The rationale worked. */
+  primerAccepted: "wire_permission_primer_accepted",
+  /** The OS granted it. */
+  granted: "wire_permission_granted",
+  /** The OS refused it (a permanently blocked answer reports here too, with `status: "blocked"`). */
+  denied: "wire_permission_denied",
+  /** The user took the secondary. The one native prompt was NOT spent. */
+  skipped: "wire_permission_skipped",
+  /** A blocked user was redirected to the OS settings page. */
+  settingsOpened: "wire_permission_settings_opened",
+} as const;
+
+export type WirePermissionEventName =
+  (typeof WIRE_PERMISSION_EVENTS)[keyof typeof WIRE_PERMISSION_EVENTS];
+
+/** The canonical event name for a stage. Exhaustive over the union (a new stage is a compile error). */
+export const permissionEventName = (stage: PermissionStage): WirePermissionEventName => {
+  switch (stage) {
+    case "shown":
+      return WIRE_PERMISSION_EVENTS.screenShown;
+    case "accepted":
+      return WIRE_PERMISSION_EVENTS.primerAccepted;
+    case "granted":
+      return WIRE_PERMISSION_EVENTS.granted;
+    case "denied":
+      return WIRE_PERMISSION_EVENTS.denied;
+    case "skipped":
+      return WIRE_PERMISSION_EVENTS.skipped;
+    case "settings":
+      return WIRE_PERMISSION_EVENTS.settingsOpened;
+    default: {
+      const _exhaustive: never = stage;
+      return _exhaustive;
+    }
+  }
+};
+
+/**
+ * The small, non-PII props that ride a permission event. `permission` is always present so one
+ * funnel can be sliced per permission; `status` only appears when the OS actually answered, which
+ * is what keeps a `blocked` refusal distinguishable from a plain `denied` without a second event.
+ */
+export const permissionEventProps = (
+  permission: WirePermissionKind,
+  status?: WirePermissionStatus,
+): Record<string, string> => (status ? { permission, status } : { permission });
+
+/**
+ * Normalize whatever the host's `request` / `getStatus` actually returned.
+ *
+ * A native permission bridge is the host's code, and hosts return `"undetermined"`, `true`, or a
+ * whole Expo response object. Anything the kit does not recognise is treated as `denied`: it is the
+ * only reading that cannot invent a grant, and every outcome continues the flow anyway.
+ */
+export const normalizePermissionStatus = (value: unknown): WirePermissionStatus =>
+  value === "granted" || value === "denied" || value === "blocked" ? value : "denied";

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/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;
   /**
@@ -281,9 +340,12 @@ export type OnboardingProgress = {
    * `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 CURRENTLY INERT: no server emits it yet. 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 that never sends it produces byte-identical behaviour to 0.12.2.
+   * 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). */