@wireai/activation 0.13.0 → 0.13.3

package/src/context/deviceId.ts

@@ -74,7 +74,7 @@ const AUTO_DEVICE_KEY_SLOT: unique symbol = Symbol.for("@wireai/activation:autoD
 /** What a hydration settled on: the id, and whether persistence actually CONFIRMED it.
  *
  *  `durable: false` means the id lives only in this process's memory — the adapter rejected, threw,
- *  or there was no adapter at all. That distinction is the whole of K1: a string is a string, so
+ *  or there was no adapter at all. That distinction is the whole point here: a string is a string, so
  *  before 0.13.0 a caller could not tell a persisted id from a per-launch mint, and the auto-join
  *  gate (`Boolean(storage)`) was reading the PRESENCE of the prop rather than the SUCCESS of the
  *  write. See {@link hydrateDeviceIdentity}. */
@@ -131,7 +131,7 @@ export interface ResolveAutoDeviceKeyOptions {
  *                                   the write. The id is real but PROCESS-scoped, so anything that
  *                                   counts a device across launches must refuse it.
  *
- * A DEGRADED outcome also drops the registry latches so the NEXT caller starts a fresh read (K8). A
+ * A DEGRADED outcome also drops the registry latches so the NEXT caller starts a fresh read. A
  * cold-boot storage lock is transient; caching it as a verdict for the process lifetime turned a
  * one-second problem into a whole-launch one, and nothing ever retried.
  */
@@ -170,7 +170,7 @@ const startHydration = (
     run = Promise.resolve(degraded());
   }
   registry.pending.set(appId, run);
-  // Retry-on-failure (K8): release the latches once a degraded outcome settles, so a later caller
+  // Retry-on-failure: release the latches once a degraded outcome settles, so a later caller
   // is not permanently bound to one bad read. Registered AFTER the `set` above, so the clean-up can
   // never race ahead of the entry it is clearing.
   void run.then((outcome) => {
@@ -238,7 +238,7 @@ export const hydrateAutoDeviceKey = async (
  * The PROVENANCE-CARRYING sibling of {@link hydrateAutoDeviceKey}: the same awaited read, but it
  * answers "is this id one this install will KEEP?" instead of only "what is the id?".
  *
- * WHY IT EXISTS (K1). `<WireOnboarding>` gated auto-injection on `Boolean(storage)` — the presence of
+ * WHY IT EXISTS. `<WireOnboarding>` gated auto-injection on `Boolean(storage)` — the presence of
  * the prop — because a string carries no provenance and there was nothing better to gate on. A
  * REJECTING adapter therefore injected a fresh `wdev_*` on every launch: strictly worse than
  * injecting nothing, since the server counts `min_sessions` by distinct opens grouped on `device_key`,

package/src/features/WireFeaturesProvider.tsx

@@ -19,7 +19,10 @@ import { useWireFeatures } from "./useWireFeatures";
 import type { WireFeatures, WireFeaturesConfig } from "./types";
 
 const CONTEXT_SYMBOL = Symbol.for("wireai.features.context");
-const globalObj = global as any;
+// `globalThis`, not `global`: the other nine `Symbol.for` slots in this kit all use it, and `global`
+// simply does not exist in a plain browser (RN-web / SSR-in-the-browser), where this line would
+// throw a ReferenceError before the provider could render anything.
+const globalObj = globalThis as any;
 
 if (!globalObj[CONTEXT_SYMBOL]) {
   globalObj[CONTEXT_SYMBOL] = createContext<WireFeatures | null>(null);

package/src/identity/userIdentity.ts

@@ -131,7 +131,7 @@ export const identifyOnboarding = async (
     }
   }
   let space: Exclude<IdentifyOnboardingBinding, false> = "onboarding";
-  // The OPT-IN last resort (K3). Until 0.13.0 this ran unconditionally: with no captured contextId
+  // The OPT-IN last resort. 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

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

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;
+};