@wireai/activation 0.13.0 → 0.13.3

package/src/theme/ThemeContext.tsx

@@ -3,12 +3,53 @@
  * 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.
+ *
+ * ── WHY THE CONTEXT LIVES ON A `Symbol.for` SLOT ───────────────────────────────────────────────
+ *
+ * It was a plain `createContext(...)`, and tsup inlines this module into FIVE dist bundles
+ * (`.`, `./reviews`, `./questionnaire`, `./coachmarks`, `./showcase`) — so each one carried its own
+ * context instance. `OnboardingThemeProvider` is exported ONLY from the root barrel, so on any
+ * `dist` resolution path (plain RN CLI, `unstable_enablePackageExports: false`, node, jest, SSR) a
+ * host that wrapped its tree in `<OnboardingThemeProvider>` and rendered `<ReviewGate>` from
+ * `@wireai/activation/reviews` was writing one context and reading another. Nothing crashed and
+ * nothing warned: `useOnboardingTheme`'s `ctx ?? mergeTheme()` fallback quietly served the NEUTRAL
+ * default theme, so the tenant's brand simply did not apply to the gate. On-device this was masked
+ * only because Metro's `react-native` export condition collapses every subpath back to this one
+ * `src/` file — the same "bundler accident, not a guarantee" the `currentSession` header names, and
+ * the same root cause as the optional-peers bug 0.13.3 fixed.
+ *
+ * The bundler-agnostic fix, exactly as `coachmarks/runtime`, `analytics/currentSession`,
+ * `context/deviceId` and `features/WireFeaturesProvider` already do it: park the ONE context on a
+ * well-known `globalThis` slot keyed by `Symbol.for(...)`. `Symbol.for` uses the runtime-global
+ * symbol registry, so every inlined copy of this module resolves the SAME symbol, finds the slot
+ * already filled, and reuses that instance — one context identity however many copies exist.
+ * `globalThis` is present and identical in Hermes/React Native, Node and SSR (we never touch
+ * `window`), so this is safe on every host. `test/canary/themeContextIdentity.test.tsx` measures it
+ * in the BUILT artifact, because the defect is invisible in source.
  */
 import React, { createContext, useContext, useMemo } from "react";
 import { mergeTheme } from "./defaultTheme";
 import type { OnboardingTheme } from "./types";
 
-const OnboardingThemeContext = createContext<OnboardingTheme | null>(null);
+/**
+ * Well-known key into the runtime-global symbol registry. `Symbol.for` (NOT a plain `Symbol()`) is
+ * what makes this cross-bundle: it returns the SAME symbol for the same string across every copy of
+ * this module, so duplicated inlined copies all address one slot.
+ */
+const THEME_CONTEXT_SLOT: unique symbol = Symbol.for("@wireai/activation:themeContext");
+
+type GlobalWithThemeContext = typeof globalThis & {
+  [THEME_CONTEXT_SLOT]?: React.Context<OnboardingTheme | null>;
+};
+
+const themeGlobal = globalThis as GlobalWithThemeContext;
+
+// First copy to load creates the context; every later copy adopts it. Never overwrite an existing
+// slot — a second `createContext` here would re-split the identity this guard exists to keep whole.
+if (!themeGlobal[THEME_CONTEXT_SLOT]) {
+  themeGlobal[THEME_CONTEXT_SLOT] = createContext<OnboardingTheme | null>(null);
+}
+const OnboardingThemeContext = themeGlobal[THEME_CONTEXT_SLOT] as React.Context<OnboardingTheme | null>;
 
 export type OnboardingThemeProviderProps = {
   /** Partial overrides merged over the neutral default theme. */

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. 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). */

package/src/utils/submitResult.ts

@@ -0,0 +1,39 @@
+/**
+ * submitResult — the ONE delivery verdict every user-payload POST in this kit reports back.
+ *
+ * WHY IT IS SHARED, AND WHY IT IS NOT A BOOLEAN. Two surfaces post a payload the user typed —
+ * `submitReview` (`reviews/transport.ts`) and `submitQuestionnaireResponse`
+ * (`questionnaire/transport.ts`) — and NEITHER has a persisted queue behind it (unlike
+ * `analytics/eventQueue`, with its `maxSize`/`maxRetries`/backoff). Both sit behind a permanent
+ * once-gate: the host writes `wire_review_<id>_seen` / `wire_questionnaire_<id>_<ver>_seen` when the
+ * gate resolves, so a payload that dies in the socket is lost AND the user is never asked again.
+ * Reading the fate of the request is the only thing that lets a caller keep an undelivered payload
+ * recoverable, so the two surfaces must answer the same question in the same words.
+ *
+ *   • `accepted` — the server answered 2xx. Stored.
+ *   • `rejected` — the server ANSWERED, non-2xx. It was reached; it either stored the payload and
+ *                  lost the ack (a gateway 502 after the write commits) or deliberately refused it.
+ *                  Either way the server owns the outcome and a re-post risks a SECOND row.
+ *   • `unsent`   — nothing came back at all: no target, a missing/throwing `fetch`, a rejected
+ *                  request. **This is the ONLY outcome a caller may retry on.**
+ *
+ * ── WHY THREE VALUES AND NOT TWO (pinned here so the defect cannot move surface) ───────────────
+ *
+ * `submitReview` was a boolean for exactly one unpublished release, and the boolean WAS the bug.
+ * `false` meant both "nothing reached the server" and "the server answered non-2xx", and the caller
+ * treats `false` as "still owed" and re-posts. But the server mints its own row id
+ * (`create_review` / `_new_id()`), and neither `CreateReviewRequest` nor the questionnaire response
+ * body carries a client id, so there is NO idempotency key on the wire: a 502 returned AFTER the
+ * insert commits means the re-post writes a SECOND row. A response of any status proves the server
+ * was reached, and that is a different question from whether it liked the payload.
+ *
+ * ── THE RESIDUAL, STATED HONESTLY ─────────────────────────────────────────────────────────────
+ *
+ * `unsent` is not proof the server never got it. A connection dropped after the request was written
+ * — or after the row committed — surfaces as a thrown/rejected `fetch`, exactly like an offline
+ * device. Retrying only on `unsent` is therefore SAFER, not SAFE. Closing that window needs a
+ * CLIENT-MINTED IDEMPOTENCY KEY the server upserts on, which is a server change and not something
+ * the kit can fake. Until it exists, prefer losing a row over inventing one: a lost detractor is a
+ * gap in the data, a duplicated one is a lie in the data.
+ */
+export type SubmitResult = "accepted" | "rejected" | "unsent";