@wireai/activation 0.13.0 → 0.13.2

package/src/cards/PermissionCard.tsx

@@ -0,0 +1,438 @@
+/**
+ * PermissionCard - the priming screen that stands in front of an OS permission dialog.
+ *
+ * THE PRIMING PATTERN, which is the entire point: the OS dialog opens from the primary press
+ * handler and from nowhere else. There is no mount effect, no auto-fire, no timer, and no code path
+ * from render to `request()`. iOS grants an app exactly ONE native notification prompt for its
+ * whole lifetime, so this cheap in-app screen spends first and only forwards the users who said
+ * yes. The secondary ("Maybe later") advances the flow with the prompt still unspent.
+ *
+ * THREE PRIMARY ACTIONS, picked from the non-prompting `getStatus` probe (never from `request`):
+ *   • ask (the default, and the only branch that can reach `request`)
+ *   • settings (status `blocked`: the OS would show nothing, so the only route left is Settings)
+ *   • continue (already granted, or a host that supplied no `request` at all - the kit declines to
+ *     fabricate a prompt it has no way to open)
+ *
+ * IT IS NOT A QUESTION. It sends nothing to the backend, appends nothing to the thread, and mints
+ * no `key` / `slot_id`, so `deriveAnswers` and every completion semantic are untouched. Every
+ * outcome, including a denial, continues the flow.
+ *
+ * Motion: the same register as the other value beats. The illustration springs in
+ * (STATUS_POP_SPRING, the StatusCard glyph pop) and the copy rises behind it on the interstitial
+ * head stagger. Reduce motion: final frame at once, like every other card.
+ *
+ * Registered as a `WireAIComponent` so a later server-emitted placement (AI-chosen timing) renders
+ * through the same component with no rewrite. It is deliberately NOT in `onboardingComponents`:
+ * that array is what the device ADVERTISES as renderable, and a backend told it may emit this card
+ * could emit one for a host that wired no `request`.
+ */
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { Animated, Easing, StyleSheet, Text, View } from "react-native";
+import { z } from "zod";
+import type { InjectedProps, WireAIComponent } from "wireai-rn";
+import { useOnboardingTheme } from "../theme/ThemeContext";
+import { bodyStyle, headingStyle } from "../theme/typography";
+import { useIllustration } from "../components/Illustration";
+import { Button } from "../components/Button";
+import { CardLayout } from "../components/CardLayout";
+import {
+  INTERSTITIAL_HEAD_MS,
+  INTERSTITIAL_HEAD_STAGGER_MS,
+  STATUS_POP_SCALE_FROM,
+  STATUS_POP_SPRING,
+  WIRE_BEZIER,
+  scaledMs,
+} from "../motion/motionSpec";
+import { useReducedMotion } from "../motion/useReducedMotion";
+import { normalizePermissionStatus } from "../permissions/permissionEvents";
+import type {
+  PermissionStage,
+  WirePermissionOutcome,
+  WirePermissionStatus,
+} from "../permissions/types";
+import { playHaptic } from "../haptics/haptics";
+import { warnInDev } from "../utils/warnInDev";
+
+const easeWire = Easing.bezier(...WIRE_BEZIER);
+const RISE_PX = 10;
+
+/** The name the card is registered under, and the `component` stamped on its events. */
+export const PERMISSION_CARD_NAME = "PermissionCard";
+
+/**
+ * How long a host's `request` may stay outstanding before the kit hands the controls back.
+ *
+ * DELIBERATELY GENEROUS. This is not a race against the user: someone reading an OS permission
+ * dialog, switching apps mid-prompt, or hitting a slow native bridge is doing nothing wrong, and a
+ * short ceiling would advance the flow underneath a dialog that is still open. It exists for one
+ * failure only, a `request` that never settles at all (a swallowed native callback, a promise
+ * nobody resolves), which would otherwise leave the user on a screen whose buttons are all
+ * disabled. On expiry the kit records NO outcome, because a pending request is not a denial.
+ */
+export const REQUEST_WATCHDOG_MS = 90_000;
+
+/**
+ * The COPY half of the card, i.e. everything a server could legitimately author. The capability
+ * half (`request` / `getStatus` / `openSettings`) is host-injected and deliberately absent here:
+ * a schema field can only ever carry data, never a function, and the kit imports no native module.
+ */
+const schema = z.object({
+  permission: z
+    .string()
+    .describe("Which OS permission this screen primes, e.g. 'notifications'"),
+  title: z.string().describe("Headline for the ask"),
+  message: z.string().describe("Why the app needs it, in the user's terms"),
+  primaryLabel: z.string().describe("Primary button, the only control that can open the OS dialog"),
+  secondaryLabel: z.string().describe("Secondary button, advances without spending the OS prompt"),
+  blockedTitle: z.string().optional().describe("Headline once the permission is permanently refused"),
+  blockedMessage: z.string().optional().describe("Rationale for the settings route"),
+  settingsLabel: z.string().optional().describe("Primary button label on the blocked route"),
+  continueLabel: z.string().optional().describe("Primary button label when there is nothing to ask"),
+  illustration: z
+    .string()
+    .optional()
+    .describe("Name of an app-provided illustration (defaults to the permission name)"),
+});
+
+export type PermissionCardProps = z.infer<typeof schema> &
+  Partial<InjectedProps> & {
+    /** THE ONLY function that can open an OS dialog. Called from the primary handler alone. */
+    request?: () => Promise<WirePermissionStatus>;
+    /** NON-PROMPTING status read. Decides which primary action is offered, nothing else. */
+    getStatus?: () => Promise<WirePermissionStatus>;
+    /** Open the OS settings page. Only reachable on the `blocked` route. */
+    openSettings?: () => void | Promise<void>;
+    /** Reports each moment for analytics. Never control flow. */
+    onStage?: (stage: PermissionStage, status?: WirePermissionStatus) => void;
+    /** Fires exactly once, with the outcome this screen produced. The flow advances on it. */
+    onSettled?: (outcome: WirePermissionOutcome) => void;
+  };
+
+/** Which action the primary button performs. `ask` is the only one that can reach `request`. */
+type PrimaryAction = "ask" | "settings" | "continue";
+
+const _PermissionCard: React.FC<PermissionCardProps> = ({
+  permission,
+  title,
+  message,
+  primaryLabel,
+  secondaryLabel,
+  blockedTitle,
+  blockedMessage,
+  settingsLabel,
+  continueLabel,
+  illustration,
+  request,
+  getStatus,
+  openSettings,
+  onStage,
+  onSettled,
+}) => {
+  const t = useOnboardingTheme();
+  const reduced = useReducedMotion();
+  const art = useIllustration(illustration ?? permission);
+  // The probed status. `undefined` means "not known", which is the ASK state: the kit never
+  // assumes a grant it has not been told about.
+  const [status, setStatus] = useState<WirePermissionStatus | undefined>(undefined);
+  const [busy, setBusy] = useState(false);
+  // One settle per mount. The card is keyed by screen id, so this is one settle per screen. It is
+  // also what makes a late `request` settlement a no-op, since `finish` reaches `settle`
+  // synchronously (see `handlePrimary`).
+  const settledRef = useRef(false);
+  // `accepted` is a per-screen boolean, so `accepted / shown` stays a readable rate.
+  const acceptedRef = useRef(false);
+  const watchdogRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const clearWatchdog = useCallback(() => {
+    if (watchdogRef.current) {
+      clearTimeout(watchdogRef.current);
+      watchdogRef.current = null;
+    }
+  }, []);
+  // A pending watchdog must never outlive the screen (it would setState on an unmounted card).
+  useEffect(() => clearWatchdog, [clearWatchdog]);
+
+  // Host callbacks held in refs so the mount-once effects below stay mount-once no matter how a
+  // host passes them (the documented usage is an INLINE `permissionScreens={[...]}`, which mints a
+  // fresh closure for every one of them on every render).
+  const onStageRef = useRef(onStage);
+  onStageRef.current = onStage;
+  const onSettledRef = useRef(onSettled);
+  onSettledRef.current = onSettled;
+  const getStatusRef = useRef(getStatus);
+  getStatusRef.current = getStatus;
+
+  // `shown` fires once per mount, ref-guarded so StrictMode's dev double-invoke cannot
+  // double-count the denominator every rate in this funnel is measured against.
+  const shownRef = useRef(false);
+  useEffect(() => {
+    if (shownRef.current) return;
+    shownRef.current = true;
+    onStageRef.current?.("shown");
+  }, []);
+
+  // The status probe, MOUNT-ONCE. `getPermissionsAsync()` and its equivalents READ, they never
+  // prompt - which is exactly why `request` is not called here and why this effect may exist at
+  // all. All it decides is which primary action the screen offers.
+  useEffect(() => {
+    const probe = getStatusRef.current;
+    if (!probe) return;
+    let cancelled = false;
+    try {
+      void Promise.resolve(probe())
+        .then((value) => {
+          if (!cancelled) setStatus(normalizePermissionStatus(value));
+        })
+        .catch(() => {
+          // A host probe that throws just leaves the screen in its ask state.
+        });
+    } catch {
+      // A synchronously-throwing probe, same treatment.
+    }
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // A host that configured a screen with no `request` gets a screen that cannot ask. The kit says
+  // so instead of rendering a button that silently does nothing (dev only, never a throw).
+  const requestRef = useRef(request);
+  requestRef.current = request;
+  useEffect(() => {
+    if (requestRef.current) return;
+    warnInDev(
+      `[wireai] <WireOnboarding> got a permission screen for "${permission}" with no \`request\` ` +
+        "function, so it cannot open the OS dialog and renders as a plain continue. Pass " +
+        "request: () => Promise<'granted' | 'denied' | 'blocked'> (5 lines around " +
+        "expo-notifications, see the README).",
+    );
+  }, [permission]);
+
+  const settle = useCallback((outcome: WirePermissionOutcome) => {
+    if (settledRef.current) return;
+    settledRef.current = true;
+    clearWatchdog();
+    onSettledRef.current?.(outcome);
+  }, [clearWatchdog]);
+
+  const primaryAction: PrimaryAction =
+    status === "blocked" ? "settings" : status === "granted" || !request ? "continue" : "ask";
+
+  const handlePrimary = useCallback(() => {
+    if (settledRef.current || busy) return;
+
+    if (primaryAction === "settings") {
+      onStageRef.current?.("settings", "blocked");
+      try {
+        void Promise.resolve(openSettings?.()).catch(() => {});
+      } catch {
+        // A settings redirect that fails is not a reason to trap the user on this screen.
+      }
+      settle("blocked");
+      return;
+    }
+
+    if (primaryAction === "continue") {
+      // Already granted (nothing to ask), or no `request` was supplied. Report the state as it is;
+      // never report a grant this screen did not produce as anything other than what it is.
+      if (status === "granted") {
+        onStageRef.current?.("granted", "granted");
+        settle("granted");
+      } else {
+        onStageRef.current?.("skipped");
+        settle("skipped");
+      }
+      return;
+    }
+
+    // THE ONE PATH TO THE OS DIALOG, reachable from this press handler only.
+    //
+    // `accepted` is a per-screen boolean, not a per-tap counter: the screen is shown once, and
+    // `accepted / shown` is the rate that says whether the rationale copy works. A second tap after
+    // the watchdog re-armed the UI would push that rate past 100%, so it is emitted once.
+    if (!acceptedRef.current) {
+      acceptedRef.current = true;
+      onStageRef.current?.("accepted");
+    }
+    setBusy(true);
+    // FIRST SETTLEMENT WINS, and `settledRef` is the whole mechanism. The watchdog below can hand
+    // the UI back while a `request` is still outstanding, so a second tap can put a SECOND one in
+    // flight, and the original can answer late. What decides between them is that this function
+    // runs STRAIGHT THROUGH to `settle` with no await in between: the first settlement to arrive
+    // has already flipped that ref by the time any later one is invoked, so the later one returns
+    // on the line below. The flow advances once and each stage event is emitted once. The same ref
+    // is why a settlement landing after the user skipped changes nothing.
+    const finish = (value: unknown) => {
+      if (settledRef.current) return;
+      clearWatchdog();
+      const resolved = normalizePermissionStatus(value);
+      setBusy(false);
+      setStatus(resolved);
+      if (resolved === "granted") {
+        // A light success tap on the grant, through the kit's optional-peer haptics: a host
+        // without `expo-haptics` simply feels nothing and nothing throws.
+        playHaptic("success");
+        onStageRef.current?.("granted", "granted");
+      } else {
+        onStageRef.current?.("denied", resolved);
+      }
+      settle(resolved);
+    };
+
+    // THE WATCHDOG, and what it deliberately does NOT do.
+    //
+    // A host `request` that never settles (a native module that swallows its callback, a promise
+    // that is never resolved) would otherwise BRICK the screen: `busy` disables both buttons, the
+    // secondary re-guards on it, and nothing upstream rescues a rendered card. Dead end, and
+    // `onComplete` never fires.
+    //
+    // So the ceiling exists to un-brick a HOST BUG, never to race the user. A person can sit on an
+    // OS permission dialog for a long time, so a short ceiling that recorded `denied` on expiry
+    // would advance the flow underneath a dialog that is still open and log an outcome the user
+    // never gave. On expiry this therefore fabricates NOTHING: no outcome, no event, no settle. It
+    // only hands the controls back so the user can tap again or skip, and says so in dev.
+    clearWatchdog();
+    watchdogRef.current = setTimeout(() => {
+      watchdogRef.current = null;
+      if (settledRef.current) return;
+      setBusy(false);
+      warnInDev(
+        `[wireai] the \`request\` for the "${permission}" permission screen has not settled after ` +
+          `${Math.round(REQUEST_WATCHDOG_MS / 1000)}s, so the kit handed the controls back rather ` +
+          "than leaving the user on a dead-end screen. It recorded NO outcome, because a pending " +
+          "request is not a denial. Make sure your request resolves to 'granted' | 'denied' | " +
+          "'blocked' on every branch, including the one where the user dismisses the OS dialog.",
+      );
+    }, REQUEST_WATCHDOG_MS);
+
+    try {
+      void Promise.resolve(request?.()).then(finish, () => finish("denied"));
+    } catch {
+      // A synchronously-throwing request is a denial, never a stuck screen.
+      finish("denied");
+    }
+  }, [busy, primaryAction, status, request, openSettings, settle, clearWatchdog, permission]);
+
+  const handleSecondary = useCallback(() => {
+    if (settledRef.current || busy) return;
+    onStageRef.current?.("skipped");
+    settle("skipped");
+  }, [busy, settle]);
+
+  // Art springs in, copy rises behind it (final frame at once under reduce motion).
+  const popT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+  const titleT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+  const bodyT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+  useEffect(() => {
+    if (reduced) {
+      popT.setValue(1);
+      titleT.setValue(1);
+      bodyT.setValue(1);
+      return;
+    }
+    const rise = (value: Animated.Value, delay: number) =>
+      Animated.timing(value, {
+        toValue: 1,
+        duration: scaledMs(INTERSTITIAL_HEAD_MS),
+        delay,
+        easing: easeWire,
+        useNativeDriver: true,
+      });
+    const anims = [
+      Animated.spring(popT, {
+        toValue: 1,
+        friction: STATUS_POP_SPRING.friction,
+        tension: STATUS_POP_SPRING.tension,
+        useNativeDriver: true,
+      }),
+      rise(titleT, scaledMs(INTERSTITIAL_HEAD_STAGGER_MS)),
+      rise(bodyT, scaledMs(INTERSTITIAL_HEAD_STAGGER_MS * 2)),
+    ];
+    anims.forEach((a) => a.start());
+    return () => anims.forEach((a) => a.stop());
+  }, [reduced, popT, titleT, bodyT]);
+
+  const popScale = popT.interpolate({
+    inputRange: [0, 1],
+    outputRange: [STATUS_POP_SCALE_FROM, 1],
+  });
+  const riseStyle = (value: Animated.Value) => ({
+    opacity: value,
+    transform: [
+      { translateY: value.interpolate({ inputRange: [0, 1], outputRange: [RISE_PX, 0] }) },
+    ],
+  });
+
+  const blocked = status === "blocked";
+  const shownTitle = blocked ? (blockedTitle ?? title) : title;
+  const shownMessage = blocked ? (blockedMessage ?? message) : message;
+  const primaryTitle =
+    primaryAction === "settings"
+      ? (settingsLabel ?? primaryLabel)
+      : primaryAction === "continue"
+        ? (continueLabel ?? primaryLabel)
+        : primaryLabel;
+  // Nothing left to decline once the permission is already granted.
+  const showSecondary = status !== "granted";
+
+  return (
+    <CardLayout
+      align="center"
+      footer={
+        <View style={[styles.footer, { gap: t.spacing.sm }]}>
+          <Button title={primaryTitle} onPress={handlePrimary} variant="primary" disabled={busy} />
+          {showSecondary ? (
+            <Button
+              title={secondaryLabel}
+              onPress={handleSecondary}
+              variant="outline"
+              disabled={busy}
+            />
+          ) : null}
+        </View>
+      }
+    >
+      <View style={[styles.center, { gap: t.spacing.md }]}>
+        {art ? (
+          <Animated.View
+            style={[styles.art, { opacity: popT, transform: [{ scale: popScale }] }]}
+          >
+            {art}
+          </Animated.View>
+        ) : null}
+
+        <Animated.View style={riseStyle(titleT)}>
+          <Text style={[headingStyle(t.fonts), { color: t.colors.text, textAlign: "center" }]}>
+            {shownTitle}
+          </Text>
+        </Animated.View>
+
+        <Animated.View style={riseStyle(bodyT)}>
+          <Text style={[bodyStyle(t.fonts), { color: t.colors.textMuted, textAlign: "center" }]}>
+            {shownMessage}
+          </Text>
+        </Animated.View>
+      </View>
+    </CardLayout>
+  );
+};
+
+/** The typed component the flow renders directly (host-injected placement). */
+export const PermissionCardView = React.memo(_PermissionCard);
+
+/**
+ * The SDK registration object, so a server-emitted placement can adopt this exact screen later.
+ * Not part of `onboardingComponents` on purpose - see the file header.
+ */
+export const PermissionCard: WireAIComponent = {
+  name: PERMISSION_CARD_NAME,
+  description:
+    "A priming screen shown BEFORE an OS permission dialog: it explains why the app wants the permission and asks only on the primary tap. Never first, never last. The user is never blocked by it: the secondary advances the flow with the OS prompt unspent.",
+  component: PermissionCardView as WireAIComponent["component"],
+  propsSchema: schema,
+};
+
+const styles = StyleSheet.create({
+  center: { width: "100%", alignItems: "center", justifyContent: "center" },
+  art: { alignItems: "center", justifyContent: "center" },
+  footer: { width: "100%", alignItems: "center" },
+});

package/src/cards/index.ts

@@ -21,9 +21,16 @@ export {
   NumberStepperCard,
   InterstitialCard,
 };
+export { PermissionCard, PermissionCardView, PERMISSION_CARD_NAME } from "./PermissionCard";
+export type { PermissionCardProps } from "./PermissionCard";
 export { normalizeOptions, optionsField, optionObjectSchema } from "./optionSchema";
 export type { CardOption } from "./optionSchema";
 
+// ⚠️ `PermissionCard` is deliberately NOT in this array. The list is what the device ADVERTISES to
+// the backend as renderable (`metadata.supportedComponents`), and a backend told it may emit a
+// permission screen could emit one into a host that injected no `request` function, which the kit
+// has no way to honour. Permission screens are host-declared for now (`permissionScreens`); the
+// card is registered and ready for the day a server-emitted placement lands.
 export const onboardingComponents: WireAIComponent[] = [
   ChipSelectCard,
   TextInputCard,

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

@@ -57,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.
@@ -243,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";