@wireai/activation 0.12.2 → 0.13.2

package/src/identity/identityRecord.ts

@@ -0,0 +1,123 @@
+/**
+ * identityRecord — the ONE provenance-carrying shape for an id the kit puts on the wire.
+ *
+ * WHY IT EXISTS. `session_id` and `device_key` are bare `string`s minted independently by four
+ * subsystems, and nothing anywhere recorded WHERE a given id came from. Every id-layer defect this
+ * release fixes is a direct consequence of that one omission:
+ *
+ *   • a rejecting storage adapter's in-memory id was indistinguishable from a persisted one, so the
+ *     kit injected a fresh per-launch join key on every launch — nothing carried `durable`.
+ *   • an app-OPEN session id could be posted into a field that means the ONBOARDING session, and the
+ *     caller was told `true` — nothing carried `space`.
+ *   • an auto-minted `wdev_*` could be injected beside a device id the host demonstrably owns on
+ *     another surface, silently — nothing carried `source`.
+ *
+ * WHAT THIS IS, AND WHAT IT DELIBERATELY IS NOT. It is a small record plus a process-wide registry of
+ * the ids a HOST supplied. It is NOT a branded-type refactor (`OnboardingSessionId` / `AppSessionId` /
+ * `DeviceKey` across every signature) — that is real value and it is deferred, because it touches
+ * every file and is not what makes a number correct this week. Nothing here changes the wire.
+ *
+ * WHY A `Symbol.for` REGISTRY. Same reason as `analytics/currentSession` and `context/deviceId`: tsup
+ * inlines a separate copy of a module into each bundle (`.` and `./analytics`), so a plain module
+ * `let` would give every bundle its own registry and the cross-surface question this exists to answer
+ * ("did ANY surface in this process get a host-supplied device key?") would read `no` from the wrong
+ * copy. `Symbol.for` resolves to one slot on `globalThis` no matter how many copies exist.
+ */
+
+/**
+ * Which id space a value belongs to. These are NOT interchangeable, and the whole point of naming
+ * them is that a value from one space must never be posted into a field that means another:
+ *   • `onboarding-session` — the A2A `contextId` for ONE onboarding run.
+ *   • `app-session`        — the per-app-open session id (`app.session_started`).
+ *   • `device`             — the per-install `device_key`; the only cross-family join key.
+ */
+export type IdentitySpace = "onboarding-session" | "app-session" | "device";
+
+/** Where the value came from: the host handed it over, or the kit minted it. */
+export type IdentitySource = "host" | "auto";
+
+/** An id plus everything a consumer needs to decide whether it may use it. */
+export type IdentityRecord = {
+  /** The id itself, trimmed. Never empty (a blank input yields no record at all). */
+  value: string;
+  /** Which id space {@link value} belongs to. */
+  space: IdentitySpace;
+  /** `host` = the integrator supplied it; `auto` = the kit minted it. */
+  source: IdentitySource;
+  /**
+   * Whether the value was actually PERSISTED (or adopted from persistence), as opposed to living
+   * only in this process's memory. A non-durable auto id is a DIFFERENT id on the next launch, which
+   * for a `device` value is worse than no value at all: the server counts `min_sessions` by distinct
+   * opens grouped on `device_key`, so a per-launch key corrupts the counter rather than leaving it
+   * empty. A host-supplied value is durable by definition — the host owns its lifetime.
+   */
+  durable: boolean;
+};
+
+/** Input to {@link resolveIdentity}. `value` is `unknown` so callers can pass a raw prop through. */
+export type ResolveIdentityInput = {
+  value: unknown;
+  space: IdentitySpace;
+  source: IdentitySource;
+  /** Defaults to `true` for a host value (the host owns its lifetime) and `false` otherwise. */
+  durable?: boolean;
+  /** Tenant/app id — two tenants in one process never share a provenance entry. */
+  scope?: string;
+};
+
+/** Well-known key into the runtime-global symbol registry — one provenance registry per process. */
+const IDENTITY_PROVENANCE_SLOT: unique symbol = Symbol.for("@wireai/activation:identityProvenance");
+
+/** `"<space>:<scope>"` → the HOST-supplied value seen for it. Auto values are never recorded. */
+type ProvenanceRegistry = { host: Map<string, string> };
+
+type GlobalWithProvenance = typeof globalThis & {
+  [IDENTITY_PROVENANCE_SLOT]?: ProvenanceRegistry;
+};
+
+const provenanceGlobal = globalThis as GlobalWithProvenance;
+
+const provenanceRegistry = (): ProvenanceRegistry => {
+  const existing = provenanceGlobal[IDENTITY_PROVENANCE_SLOT];
+  if (existing) return existing;
+  const created: ProvenanceRegistry = { host: new Map() };
+  provenanceGlobal[IDENTITY_PROVENANCE_SLOT] = created;
+  return created;
+};
+
+const provenanceKey = (space: IdentitySpace, scope?: string): string =>
+  `${space}:${scope ?? "default"}`;
+
+/**
+ * Build an {@link IdentityRecord} from a candidate value, or `undefined` when there is nothing usable
+ * (a non-string, or blank after trimming) — so a caller can `if (record)`-gate instead of guessing
+ * whether an empty string means "none" or "not yet".
+ *
+ * SIDE EFFECT, deliberate and the reason this is a function and not an object literal: a `host`-sourced
+ * record is RECORDED on the process registry, so a later surface can ask {@link hostIdentity} whether
+ * this process demonstrably owns a host id in that space. That is what turns "the kit injected its own
+ * key" from a silent third id space into a warnable condition. Never throws.
+ */
+export const resolveIdentity = (input: ResolveIdentityInput): IdentityRecord | undefined => {
+  if (typeof input.value !== "string") return undefined;
+  const value = input.value.trim();
+  if (!value) return undefined;
+  const durable = input.durable ?? input.source === "host";
+  if (input.source === "host") {
+    provenanceRegistry().host.set(provenanceKey(input.space, input.scope), value);
+  }
+  return { value, space: input.space, source: input.source, durable };
+};
+
+/**
+ * The HOST-supplied id this process has seen for a space, or `undefined` when every surface so far
+ * let the kit mint its own. Answers the cross-surface question no single mount can answer alone:
+ * "does this app own a device id that this particular mount was not given?"
+ */
+export const hostIdentity = (space: IdentitySpace, scope?: string): string | undefined =>
+  provenanceRegistry().host.get(provenanceKey(space, scope));
+
+/** Test-only: forget every recorded host identity so a unit test starts from a clean registry. */
+export const resetIdentityProvenance = (): void => {
+  provenanceRegistry().host.clear();
+};

package/src/identity/userIdentity.ts

@@ -76,20 +76,49 @@ export type IdentifyOnboardingOptions = {
   appId?: string;
   /** Storage key override — pass the same `persistKey` you gave `<WireOnboarding>`, if any. */
   persistKey?: string;
+  /**
+   * OPT-IN LAST RESORT, default `false`. When no ONBOARDING session can be resolved (no `contextId`,
+   * nothing in `storage`), bind the user to the LIVE PER-OPEN app session instead and return
+   * `"app_session"`.
+   *
+   * ⚠️ These are two different id spaces sharing one wire field. An onboarding session id is the A2A
+   * `contextId`; a per-open id is what `app.session_started` registers. The server's onboarding funnel
+   * groups by `session_id`, so a per-open id posted here does not attach the user to their onboarding
+   * — it writes a row nothing in that funnel can join. Until 0.13.0 this happened SILENTLY and
+   * returned `true`, in exactly the documented post-completion case (completion clears the persisted
+   * session), so the funnel stayed unattributed while the host was told it had worked.
+   *
+   * Turn it on only if binding the id to *some* session the server saw is genuinely worth more to you
+   * than knowing the onboarding bind failed — and read the return value, which now says which it was.
+   */
+  allowAppSessionFallback?: boolean;
 };
 
+/**
+ * What {@link identifyOnboarding} bound, and to WHICH id space — because `true` could not say.
+ *
+ *   • `"onboarding"`  — bound to the A2A `contextId`. This is the one that attributes the funnel.
+ *   • `"app_session"` — bound to the live per-open app session, via `allowAppSessionFallback`. The
+ *                       server saw that session, but it is not this user's onboarding.
+ *   • `false`         — nothing was dispatched (no user id, no server url, no resolvable session).
+ *
+ * ⚠️ 0.13.0 widened this from `boolean`. `"onboarding"` is truthy, so an `if (await identify…)` still
+ * behaves identically; only an explicit `: boolean` annotation needs updating.
+ */
+export type IdentifyOnboardingBinding = "onboarding" | "app_session" | false;
+
 /**
  * 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).
+ * Fire-and-forget under the hood (never throws, never blocks onboarding). Resolves to the
+ * {@link IdentifyOnboardingBinding} that says WHICH id space was bound, or `false` when nothing could
+ * be (no user id, no server url, or no resolvable session).
  */
 export const identifyOnboarding = async (
   opts: IdentifyOnboardingOptions,
-): Promise<boolean> => {
+): Promise<IdentifyOnboardingBinding> => {
   const userId = sanitizeUserId(opts.userId);
   if (!userId || !opts.config?.serverUrl) return false;
 
@@ -101,15 +130,22 @@ export const identifyOnboarding = async (
       contextId = stored?.id;
     }
   }
-  // Last resort: bind to the LIVE per-open session (registered by `reportSessionStart`) so a
-  // post-flow identify with no captured contextId still attaches to a session the server saw,
-  // instead of no-oping. The onboarding contextId (above) is still preferred when available.
-  if (!contextId) contextId = getCurrentSessionId();
+  let space: Exclude<IdentifyOnboardingBinding, false> = "onboarding";
+  // The OPT-IN last resort (K3). Until 0.13.0 this ran unconditionally: with no captured contextId
+  // it posted the LIVE PER-OPEN session id in the `session_id` field — which on this endpoint means
+  // the ONBOARDING session — and then returned `true`. Two disjoint id spaces share that field, so
+  // the row it wrote could never join the onboarding funnel, and the host got a success signal for a
+  // bind that had not happened. It is now off unless the caller asks, and when it does fire it says
+  // so in the return value instead of impersonating an onboarding bind.
+  if (!contextId && opts.allowAppSessionFallback) {
+    contextId = getCurrentSessionId();
+    space = "app_session";
+  }
   if (!contextId) return false;
 
   reportClientEvent(
     { serverUrl: opts.config.serverUrl, apiKey: opts.config.apiKey },
     { event_type: "identify", session_id: contextId, user_id: userId },
   );
-  return true;
+  return space;
 };

package/src/illustrations/defaultIllustrations.tsx

@@ -16,8 +16,8 @@ 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 }) => {
+/** The soft tinted disc every default sits in, whether its content is a glyph or a shape. */
+const Disc: React.FC<{ children: React.ReactNode }> = ({ children }) => {
   const t = useOnboardingTheme();
   return (
     <View
@@ -26,16 +26,51 @@ const Glyph: React.FC<{ children: React.ReactNode }> = ({ children }) => {
         { backgroundColor: t.colors.primarySoft, borderRadius: t.radius.full },
       ]}
     >
+      {children}
+    </View>
+  );
+};
+
+/** A soft tinted disc with a centered glyph: the shared frame for every text-glyph default. */
+const Glyph: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const t = useOnboardingTheme();
+  return (
+    <Disc>
       <Text style={[styles.glyphText, { color: t.colors.primary }]} allowFontScaling={false}>
         {children}
       </Text>
-    </View>
+    </Disc>
   );
 };
 
 /** Forward-motion / momentum: an upward arrow. */
 const MomentumGlyph: React.FC = () => <Glyph>{"↗"}</Glyph>;
 
+/**
+ * Notification priming: a bell, DRAWN FROM VIEWS rather than written as an emoji.
+ *
+ * A color emoji carries its own palette and ignores the `color` its container sets, so a "🔔" here
+ * would be the one default illustration that refuses to repaint with the host's theme, sitting
+ * next to siblings that do. Three plain Views (a domed body, a rim, a clapper) take
+ * `t.colors.primary` directly, and they depend on no glyph being present in the platform font and
+ * on no guess about whether it renders as text or as emoji.
+ *
+ * Keyed by the PERMISSION name, which is what PermissionCard looks up by default, so a
+ * notification screen is never a blank box with no host wiring.
+ */
+const NotificationsGlyph: React.FC = () => {
+  const t = useOnboardingTheme();
+  return (
+    <Disc>
+      <View style={styles.bell}>
+        <View style={[styles.bellBody, { backgroundColor: t.colors.primary }]} />
+        <View style={[styles.bellRim, { backgroundColor: t.colors.primary }]} />
+        <View style={[styles.bellClapper, { backgroundColor: t.colors.primary }]} />
+      </View>
+    </Disc>
+  );
+};
+
 /** Before → after: two states with an arrow between. */
 const BeforeAfterGlyph: React.FC = () => {
   const t = useOnboardingTheme();
@@ -67,6 +102,7 @@ const BeforeAfterGlyph: React.FC = () => {
 export const defaultIllustrations: Record<string, React.ReactNode> = {
   momentum: <MomentumGlyph />,
   "before-after": <BeforeAfterGlyph />,
+  notifications: <NotificationsGlyph />,
 };
 
 const styles = StyleSheet.create({
@@ -96,4 +132,9 @@ const styles = StyleSheet.create({
     fontSize: 28,
     fontWeight: "700",
   },
+  // The bell: a domed body over a wider rim, with the clapper hanging below it.
+  bell: { alignItems: "center", justifyContent: "center" },
+  bellBody: { width: 34, height: 30, borderTopLeftRadius: 17, borderTopRightRadius: 17 },
+  bellRim: { width: 44, height: 5, borderRadius: 3, marginTop: 2 },
+  bellClapper: { width: 9, height: 9, borderRadius: 5, marginTop: 3 },
 });

package/src/index.ts

@@ -30,8 +30,6 @@ export { LoadingBlock } from "./components/LoadingBlock";
 export { LoadingScreen } from "./components/LoadingScreen";
 export { AnimatedSparkle } from "./components/AnimatedSparkle";
 export { ErrorBlock } from "./components/ErrorBlock";
-/** @deprecated No longer used internally — the terminal screen is CompletionView. */
-export { DoneBlock } from "./components/DoneBlock";
 export { CompletionView } from "./components/CompletionView";
 export { IllustrationProvider, useIllustration } from "./components/Illustration";
 export type { IllustrationRegistry } from "./components/Illustration";
@@ -59,6 +57,10 @@ export {
   onboardingComponents,
 } from "./cards";
 export type { CardOption } from "./cards";
+// The priming screen. NOT in `onboardingComponents` (see the note there): it is host-declared via
+// the `permissionScreens` prop, and registered so a server-emitted placement can adopt it later.
+export { PermissionCard, PermissionCardView, PERMISSION_CARD_NAME } from "./cards";
+export type { PermissionCardProps } from "./cards";
 
 // ─── Icons (semantic vocabulary → optional @expo/vector-icons → nothing) ──────
 // WIRE_ICON_NAMES is the list to paste into the server/AI prompt as the allowed `icon` values.
@@ -147,7 +149,9 @@ export { detectNativeModel } from "./device/deviceModel";
 
 // ─── User identity (opaque pseudonymous id; late binding, dependency-free) ────
 export { identifyOnboarding, sanitizeUserId, looksLikeEmail, USER_ID_MAX_LENGTH } from "./identity/userIdentity";
-export type { IdentifyOnboardingOptions } from "./identity/userIdentity";
+export type { IdentifyOnboardingOptions, IdentifyOnboardingBinding } from "./identity/userIdentity";
+export { resolveIdentity, hostIdentity, resetIdentityProvenance } from "./identity/identityRecord";
+export type { IdentityRecord, IdentitySpace, IdentitySource } from "./identity/identityRecord";
 
 // ─── Rich user context (one object → every event's user_context; opt-in email PII) ────
 export {
@@ -159,7 +163,6 @@ export {
   clearPiiFromContext,
   analyticsUserIdStorageKey,
   activationJoinContext,
-  RESERVED_USER_CONTEXT_KEYS,
   EXTRA_KEY_PREFIX,
 } from "./context/userContext";
 export type {
@@ -182,6 +185,9 @@ export {
   // The awaitable sibling: resolves AFTER the persisted id has been read back, for a caller that can
   // afford one storage read and must not stamp a key minted a millisecond ago (the lifecycle mount).
   hydrateAutoDeviceKey,
+  // The PROVENANCE-carrying form of the same read: it also says whether the id was actually persisted,
+  // so a caller writing a cross-launch join key onto the wire can refuse a per-launch one.
+  hydrateDeviceIdentity,
   resetAutoDeviceKeys,
 } from "./context/deviceId";
 export type { DeviceKeyStorage, ResolveAutoDeviceKeyOptions } from "./context/deviceId";
@@ -241,6 +247,40 @@ export type {
   RevenueCatSink,
 } from "./revenuecat";
 
+// ─── Permission screens (mid-flow priming; the OS dialog only ever on the primary tap) ──
+export {
+  WIRE_PERMISSION_EVENTS,
+  permissionEventName,
+  permissionEventProps,
+  normalizePermissionStatus,
+  DEFAULT_PERMISSION_PLACEMENT,
+  isPermissionDue,
+  normalizeAfterCard,
+  permissionScreenId,
+  selectDuePermissionScreen,
+  DEFAULT_PERMISSION_COPY,
+  GENERIC_PERMISSION_COPY,
+  NOTIFICATIONS_PERMISSION_COPY,
+  resolvePermissionCopy,
+  clearSettledPermissions,
+  loadSettledPermissions,
+  permissionStorageKey,
+  readSettledPermissions,
+  saveSettledPermissions,
+} from "./permissions";
+export type {
+  PermissionPlacement,
+  PermissionScreenConfig,
+  PermissionScreenCopy,
+  PermissionStage,
+  WirePermissionKind,
+  WirePermissionOutcome,
+  WirePermissionStatus,
+  WirePermissionEventName,
+  FlowPosition,
+  DuePermissionScreen,
+} from "./permissions";
+
 // ─── Session mapping (one `app.session_started` per app-open → /v1/events) ─────
 export {
   reportSessionStart,

package/src/permissions/index.ts

@@ -0,0 +1,64 @@
+/**
+ * permissions - injectable mid-flow permission screens.
+ *
+ * Re-exported from the main `@wireai/activation` barrel (no separate subpath), the same way
+ * `revenuecat` is: everything here is pure, dependency-free and UI-free, so it costs a consumer
+ * that never configures a screen nothing. The screen itself lives in `cards/PermissionCard.tsx`.
+ *
+ * Adopting it is one prop:
+ *
+ *   <WireOnboarding
+ *     permissionScreens={[{ permission: "notifications", request: askForNotifications }]}
+ *     ...
+ *   />
+ *
+ * See `types.ts` for why the kit imports no native permission module, and `PermissionCard.tsx` for
+ * the priming rule the whole feature exists to enforce.
+ */
+
+// ─── Canonical permission-funnel names + the pure mappers behind them ─────────
+export {
+  WIRE_PERMISSION_EVENTS,
+  permissionEventName,
+  permissionEventProps,
+  normalizePermissionStatus,
+} from "./permissionEvents";
+export type { WirePermissionEventName } from "./permissionEvents";
+
+// ─── Placement math (server-driven stream, so a target past the end clamps) ───
+export {
+  DEFAULT_PERMISSION_PLACEMENT,
+  isPermissionDue,
+  normalizeAfterCard,
+  permissionScreenId,
+  selectDuePermissionScreen,
+} from "./placement";
+export type { FlowPosition, DuePermissionScreen } from "./placement";
+
+// ─── Rationale copy (kit defaults + host overrides) ───────────────────────────
+export {
+  DEFAULT_PERMISSION_COPY,
+  GENERIC_PERMISSION_COPY,
+  NOTIFICATIONS_PERMISSION_COPY,
+  resolvePermissionCopy,
+} from "./permissionCopy";
+
+// ─── Once-only across an app kill (the same host-injected `storage`) ──────────
+export {
+  clearSettledPermissions,
+  loadSettledPermissions,
+  permissionStorageKey,
+  readSettledPermissions,
+  saveSettledPermissions,
+} from "./permissionMemory";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+export type {
+  PermissionPlacement,
+  PermissionScreenConfig,
+  PermissionScreenCopy,
+  PermissionStage,
+  WirePermissionKind,
+  WirePermissionOutcome,
+  WirePermissionStatus,
+} from "./types";

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";