@wireai/activation 0.3.0 → 0.7.0

package/src/components/Illustration.tsx

@@ -10,11 +10,14 @@
  * When the backend names an illustration the registry doesn't have, the
  * InterstitialCard falls back to its `imageUrl` (a plain RN <Image>).
  */
-import React, { createContext, useContext } from "react";
+import React, { createContext, useContext, useMemo } from "react";
 
 export type IllustrationRegistry = Record<string, React.ReactNode>;
 
-const IllustrationContext = createContext<IllustrationRegistry>({});
+/** One shared empty registry so an unconfigured provider never allocates a fresh {} per render. */
+const EMPTY_REGISTRY: IllustrationRegistry = {};
+
+const IllustrationContext = createContext<IllustrationRegistry>(EMPTY_REGISTRY);
 
 export type IllustrationProviderProps = {
   registry?: IllustrationRegistry;
@@ -24,9 +27,10 @@ export type IllustrationProviderProps = {
 export const IllustrationProvider: React.FC<IllustrationProviderProps> = ({
   registry,
   children,
-}) => (
-  <IllustrationContext.Provider value={registry ?? {}}>{children}</IllustrationContext.Provider>
-);
+}) => {
+  const value = useMemo(() => registry ?? EMPTY_REGISTRY, [registry]);
+  return <IllustrationContext.Provider value={value}>{children}</IllustrationContext.Provider>;
+};
 
 /** Look up an app-supplied illustration node by name. Returns undefined if absent. */
 export const useIllustration = (name?: string): React.ReactNode | undefined => {

package/src/components/LoadingBlock.tsx

@@ -22,7 +22,6 @@ import {
   scaledMs,
 } from "../motion/motionSpec";
 import { useReducedMotion } from "../motion/useReducedMotion";
-import { useLoaderChrome } from "./loaderChrome";
 
 const STAGE_SIZE = 96;
 const ORBIT_DOT = 9;
@@ -104,11 +103,12 @@ const _LoadingBlock: React.FC<LoadingBlockProps> = ({
 }) => {
   const t = useOnboardingTheme();
   const reduced = useReducedMotion();
-  // When the loader renders inside the scaffold body it sits below the header; the scaffold
-  // publishes how far to shift UP so the loader centers in the full flow area, not the body.
-  // Standalone (no provider) → 0. A static transform (visual only): it never reflows the body,
-  // so the card underneath and the card↔loader handoff are unaffected.
-  const { offsetY } = useLoaderChrome();
+  // The loader fills its parent (flex:1) and centers in it. In the flow that parent is the
+  // scaffold BODY (the same content region the cards render into), so the loader lands at the
+  // content-area center — visually consistent with the cards it hands off to. Standalone
+  // (LoadingScreen / a playground CardFrame) it centers in whatever bounds it. No screen-inset
+  // math and no transform: it inherits the content area it is dropped into, so it is centered
+  // in every context by construction.
 
   // Skeleton lines are gated behind the 300ms window: a fast fetch never shows them.
   const [showSkeleton, setShowSkeleton] = useState(false);
@@ -118,34 +118,44 @@ const _LoadingBlock: React.FC<LoadingBlockProps> = ({
   }, []);
 
   return (
-    <View
-      style={[
-        styles.center,
-        { gap: t.spacing.md, padding: t.spacing.lg },
-        offsetY ? { transform: [{ translateY: offsetY }] } : null,
-      ]}
-    >
+    <View style={[styles.center, { padding: t.spacing.lg }]}>
+      {/*
+       * The stage is the ANCHOR: it's the only in-flow child, so `justifyContent:
+       * center` lands the icon at the true center of the flow area. Title, hint and
+       * the (300ms-gated) skeleton hang BELOW it in an absolutely-positioned column,
+       * so they never displace the icon — previously they lived in the same centered
+       * column, which re-balanced (and jumped the icon UP ~½ its height) the moment
+       * the skeleton lines mounted at 300ms.
+       */}
       <View style={styles.stage}>
         <View style={[styles.ring, { borderColor: t.colors.border, borderRadius: t.radius.full }]} />
         <OrbitDot color={t.colors.primary} reduced={reduced} />
         <AnimatedSparkle size={40} variant="pulse" />
       </View>
-      {title ? (
-        <Text style={[headingStyle(t.fonts), { color: t.colors.text, textAlign: "center" }]}>
-          {title}
-        </Text>
-      ) : null}
-      {hint ? (
-        <Text style={[bodyStyle(t.fonts), { color: t.colors.textMuted, textAlign: "center" }]}>
-          {hint}
-        </Text>
-      ) : null}
-      {showSkeleton ? (
-        <View style={[styles.skeleton, { gap: t.spacing.sm, marginTop: t.spacing.sm }]}>
-          <SkeletonLine width="80%" delay={0} color={t.colors.surface} reduced={reduced} />
-          <SkeletonLine width="60%" delay={200} color={t.colors.surface} reduced={reduced} />
-        </View>
-      ) : null}
+      <View
+        style={[
+          styles.labels,
+          { marginTop: STAGE_SIZE / 2 + t.spacing.lg, gap: t.spacing.md, paddingHorizontal: t.spacing.lg },
+        ]}
+        pointerEvents="none"
+      >
+        {title ? (
+          <Text style={[headingStyle(t.fonts), { color: t.colors.text, textAlign: "center" }]}>
+            {title}
+          </Text>
+        ) : null}
+        {hint ? (
+          <Text style={[bodyStyle(t.fonts), { color: t.colors.textMuted, textAlign: "center" }]}>
+            {hint}
+          </Text>
+        ) : null}
+        {showSkeleton ? (
+          <View style={[styles.skeleton, { gap: t.spacing.sm, marginTop: t.spacing.sm }]}>
+            <SkeletonLine width="80%" delay={0} color={t.colors.surface} reduced={reduced} />
+            <SkeletonLine width="60%" delay={200} color={t.colors.surface} reduced={reduced} />
+          </View>
+        ) : null}
+      </View>
     </View>
   );
 };
@@ -154,6 +164,11 @@ export const LoadingBlock = React.memo(_LoadingBlock);
 
 const styles = StyleSheet.create({
   center: { flex: 1, alignItems: "center", justifyContent: "center" },
+  // Absolutely-positioned label column, pinned just under the centered stage: its top
+  // edge starts at the flow center (top: 50%) and the inline marginTop (STAGE_SIZE/2 +
+  // a gap) drops it below the stage. Out of flow → it never moves the stage, so the
+  // 300ms skeleton reveal grows DOWNWARD only and the icon stays centered.
+  labels: { position: "absolute", top: "50%", left: 0, right: 0, alignItems: "center" },
   stage: {
     width: STAGE_SIZE,
     height: STAGE_SIZE,

package/src/components/LoadingScreen.tsx

@@ -7,8 +7,9 @@
  * WHY a dedicated frame: those slots used to return a bare <LoadingBlock/>, whose flex:1 only
  * fills whatever the host happened to give it — with no safe area and, if the host didn't
  * bound it, no height at all (top-anchored). This wraps them in the same SafeAreaView the flow
- * uses, so the standalone loaders center exactly like the between-turns loader (which centers
- * in the full flow area via the scaffold's loaderChrome offset). One consistent centered look.
+ * uses, so the standalone loaders center exactly like the between-turns loader (both fill their
+ * parent flex:1 region and center in it — here the SafeAreaView, in the flow the scaffold body).
+ * One consistent centered look.
  */
 import React from "react";
 import { StyleSheet } from "react-native";

package/src/components/OnboardingScaffold.tsx

@@ -15,16 +15,13 @@
  * RN core SafeAreaView is deprecated and iOS-only, so the kit takes the standard
  * Expo/RN peer instead of shipping cropped layouts on Android + notched devices.
  */
-import React from "react";
+import React, { useMemo } from "react";
 import { StyleSheet, Text, TouchableOpacity, View } from "react-native";
 import { SafeAreaView } from "react-native-safe-area-context";
 import { useOnboardingTheme } from "../theme/ThemeContext";
+import type { OnboardingTheme } from "../theme/types";
 import { bodyStyle } from "../theme/typography";
 import { StepProgress } from "./StepProgress";
-import { LoaderChromeProvider } from "./loaderChrome";
-
-// The header's fixed StepProgress bar height (design bar = 6px; see StepProgress styles).
-const PROGRESS_TRACK = 6;
 
 export type OnboardingScaffoldProps = {
   /** 1-based index of the current step; drives the (countless) progress bar. */
@@ -53,15 +50,9 @@ const _OnboardingScaffold: React.FC<OnboardingScaffoldProps> = ({
   children,
 }) => {
   const t = useOnboardingTheme();
+  const styles = useMemo(() => makeStyles(t), [t]);
   const hit = { top: 12, bottom: 12, left: 12, right: 12 };
 
-  // Top chrome above the body content = header (progress bar + its paddingTop) + the body's
-  // own paddingTop. A loader that fills the body centers half that distance too low; it reads
-  // this offset (via LoaderChromeProvider) and shifts UP by half the chrome to land at the true
-  // screen center. Cards ignore it, so their layout — and the card↔loader handoff — is untouched.
-  const topChrome = t.spacing.md + PROGRESS_TRACK + t.spacing.md;
-  const loaderOffsetY = -Math.round(topChrome / 2);
-
   return (
     <SafeAreaView
       edges={["top", "bottom"]}
@@ -72,15 +63,19 @@ const _OnboardingScaffold: React.FC<OnboardingScaffoldProps> = ({
           <StepProgress step={step} complete={complete} approxScreens={approxScreens} />
         </View>
         {onSkip ? (
-          <TouchableOpacity onPress={onSkip} hitSlop={hit} style={{ marginLeft: t.spacing.md }}>
+          <TouchableOpacity onPress={onSkip} hitSlop={hit} style={styles.skip}>
             <Text style={[bodyStyle(t.fonts), { color: t.colors.textMuted }]}>{skipLabel}</Text>
           </TouchableOpacity>
         ) : null}
       </View>
 
-      {/* Full-screen body: the card (via CardLayout) fills this and pins its own CTA. */}
-      <View style={[styles.body, { paddingHorizontal: t.spacing.md, paddingTop: t.spacing.md }]}>
-        <LoaderChromeProvider value={{ offsetY: loaderOffsetY }}>{children}</LoaderChromeProvider>
+      {/* Full-screen body (flex:1): the card (via CardLayout) fills this and pins its own CTA,
+          and the between-turns LoadingBlock fills+centers in this SAME region — so the loader
+          lands at the content-area center, consistent with the cards, not the full-screen center. */}
+      <View
+        style={[styles.body, { paddingHorizontal: t.spacing.md, paddingTop: t.spacing.md }]}
+      >
+        {children}
       </View>
 
       {onBack ? (
@@ -96,10 +91,13 @@ const _OnboardingScaffold: React.FC<OnboardingScaffoldProps> = ({
 
 export const OnboardingScaffold = React.memo(_OnboardingScaffold);
 
-const styles = StyleSheet.create({
-  flex: { flex: 1 },
-  header: { flexDirection: "row", alignItems: "center" },
-  progressWrap: { flex: 1 },
-  body: { flex: 1 },
-  footer: { flexDirection: "row", justifyContent: "flex-start" },
-});
+function makeStyles(t: OnboardingTheme) {
+  return StyleSheet.create({
+    flex: { flex: 1 },
+    header: { flexDirection: "row", alignItems: "center" },
+    progressWrap: { flex: 1 },
+    body: { flex: 1 },
+    footer: { flexDirection: "row", justifyContent: "flex-start" },
+    skip: { marginLeft: t.spacing.md },
+  });
+}

package/src/context/userContext.ts

@@ -0,0 +1,210 @@
+/**
+ * userContext — the ONE extensible object a host passes once and the kit flows into every
+ * analytics event's `user_context` (plus the top-level opaque `user_id`).
+ *
+ * WHY it exists: hosts already hand the kit fragments of "who this user is" — `config.appVersion`,
+ * `useSessionStart({ deviceKey, userId })`, `<WireOnboarding userContext={…} />` — but there was no
+ * single object that carries app version + device key + user id + (opt-in) email + arbitrary extras
+ * together, with one precedence rule, into every event. `WireUserContext` is that object;
+ * `resolveUserContext` is the pure merge that turns it into the wire shape.
+ *
+ * PRECEDENCE (the one rule): an explicit `WireUserContext` field WINS over the #42 auto-detected
+ * `device`/`appVersion`. A missing field is OMITTED, never sent empty.
+ *
+ * WHERE EACH FIELD LANDS (deliberate separation so nothing leaks across buckets):
+ *   • `userId`    → the event's TOP-LEVEL opaque `user_id` (via `sanitizeUserId`). NEVER the bucket.
+ *   • `userEmail` → its OWN key `user_context.user_email`. NEVER merged into `userId`. OPT-IN PII.
+ *   • `deviceKey` → `user_context.device_key` (the server's `_event_device_key` reads it there).
+ *   • `appVersion`→ `user_context.app_version` (and returned as `appVersion` for `device.appVersion`).
+ *   • `extra`     → NAMESPACED under a `custom.` key prefix, coerced to scalars, so a host extra can
+ *                   never collide with a reserved `user_context` key.
+ *
+ * DEPENDENCY-FREE: the only import is the kit's own `sanitizeUserId`. The optional email hash is a
+ * dependency-free FNV-1a fold (see {@link hashEmailFnv1a}) — no crypto library, no async.
+ */
+import { sanitizeUserId } from "../identity/userIdentity";
+
+/**
+ * The single, extensible user-context object. A host passes it ONCE (at analytics init) and may
+ * update it post-mount (e.g. attach `userId`/`userEmail` at login) via `setUserContext(partial)`.
+ * Every field is optional; missing fields are omitted from the wire payload.
+ */
+export interface WireUserContext {
+  /**
+   * Host app version, e.g. "1.4.2". EXPLICIT — wins over the #42 auto-detected `device.appVersion`.
+   * Lands in `user_context.app_version`. Omitted when neither this nor auto-detect yields a version.
+   */
+  appVersion?: string;
+  /**
+   * A stable, non-PII device id the host owns. Lands in `user_context.device_key` (NOT `session_id`),
+   * where the server groups a device's sessions. Host-supplied; the kit never mints or reads one.
+   */
+  deviceKey?: string;
+  /**
+   * The host's OPAQUE PSEUDONYMOUS user id (their internal id — NOT an email/name/phone). Sanitized +
+   * capped (see `sanitizeUserId`) and placed on the event's top-level `user_id`. NEVER the bucket.
+   */
+  userId?: string;
+  /**
+   * OPT-IN PII. The user's email, its OWN field (`user_context.user_email`) — NEVER merged into
+   * `userId`. The kit NEVER auto-collects this; a host passes it only WITH the user's consent (EU
+   * users: treat as personal data). For a non-reversible form, set {@link hashEmail} `true` (the kit
+   * folds it with a dependency-free hash and stamps `user_context.user_email_hashed: true`), OR
+   * pre-hash host-side with a cryptographic digest and pass that here with `hashEmail` falsy.
+   */
+  userEmail?: string;
+  /**
+   * When `true`, {@link userEmail} is folded with the kit's dependency-free {@link hashEmailFnv1a}
+   * before it leaves the device, and `user_context.user_email_hashed` is set `true`. NOTE: FNV-1a is
+   * a lightweight NON-cryptographic fold (obfuscation, not a secure digest). For a cryptographic
+   * hash, compute it host-side (e.g. SHA-256 via `expo-crypto`) and pass the digest as `userEmail`
+   * with `hashEmail` falsy. Default: raw email is sent as-is (opt-in already gated it upstream).
+   */
+  hashEmail?: boolean;
+  /**
+   * Arbitrary host context (signup method, referral, plan tier…). Each value is coerced to a scalar
+   * (`string | number | boolean`; non-scalars and non-finite numbers are DROPPED) and NAMESPACED
+   * under a `custom.` key prefix in `user_context` (e.g. `user_context["custom.referral"]`) so it can
+   * never collide with a reserved key. No raw PII — use {@link userEmail} for email.
+   */
+  extra?: Record<string, string | number | boolean>;
+}
+
+/**
+ * The wire-shaped result of {@link resolveUserContext}. `userContext` is the non-PII/opt-in-PII
+ * bucket stamped onto the event; `userId` is the top-level opaque id; `appVersion`/`deviceKey` are
+ * echoed for callers that also place them elsewhere (e.g. `device.appVersion`). Absent fields are
+ * omitted so a caller can spread this without sending empties.
+ */
+export interface ResolvedUserContext {
+  /** The opaque, sanitized user id → the event's top-level `user_id`. Omitted when unset/blank. */
+  userId?: string;
+  /** The stable device id → `user_context.device_key`. Omitted when unset. */
+  deviceKey?: string;
+  /** The effective app version (explicit > auto-detected) → `user_context.app_version`. */
+  appVersion?: string;
+  /** The `user_context` bucket (device_key, app_version, user_email[+ _hashed], custom.*). */
+  userContext?: Record<string, string | number | boolean>;
+}
+
+/** Reserved `user_context` keys the kit itself writes; host `extra` is namespaced away from these. */
+export const RESERVED_USER_CONTEXT_KEYS = [
+  "device_key",
+  "app_version",
+  "app_build",
+  "network_type",
+  "session_count",
+  "returning",
+  "platform",
+  "user_email",
+  "user_email_hashed",
+] as const;
+
+/** The prefix applied to every host `extra` key so it can never collide with a reserved key. */
+export const EXTRA_KEY_PREFIX = "custom." as const;
+
+/** A finite scalar the wire accepts. Non-finite numbers (NaN/Infinity) are NOT scalars here. */
+export const isWireScalar = (value: unknown): value is string | number | boolean => {
+  const t = typeof value;
+  if (t === "string" || t === "boolean") return true;
+  if (t === "number") return Number.isFinite(value as number);
+  return false;
+};
+
+/**
+ * Fold an email to a stable, dependency-free 32-bit FNV-1a hex token (lowercased + trimmed first so
+ * the same address always folds identically). This is OBFUSCATION, not a cryptographic digest — it
+ * is not collision-resistant. For a real hash, pre-hash host-side and pass the digest as `userEmail`.
+ */
+export const hashEmailFnv1a = (email: string): string => {
+  const normalized = email.trim().toLowerCase();
+  let hash = 0x811c9dc5; // FNV offset basis (32-bit)
+  for (let i = 0; i < normalized.length; i++) {
+    hash ^= normalized.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193); // FNV prime (32-bit), kept in 32-bit via imul
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+};
+
+/** Trim a candidate string; return `undefined` for a non-string / blank so callers can `if`-gate. */
+const cleanString = (value: unknown): string | undefined => {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+};
+
+/**
+ * Coerce a host `extra` map into the namespaced, scalar-only bucket shape. Every kept value is
+ * placed under `custom.<key>`; non-scalar values (objects, arrays, null, functions, NaN/Infinity)
+ * are DROPPED. Returns an object (possibly empty).
+ */
+export const namespaceExtra = (
+  extra: Record<string, unknown> | undefined,
+): Record<string, string | number | boolean> => {
+  const out: Record<string, string | number | boolean> = {};
+  if (!extra || typeof extra !== "object") return out;
+  for (const [key, value] of Object.entries(extra)) {
+    const cleanKey = cleanString(key);
+    if (!cleanKey) continue;
+    if (!isWireScalar(value)) continue; // drop anything that isn't a finite scalar
+    out[`${EXTRA_KEY_PREFIX}${cleanKey}`] = value;
+  }
+  return out;
+};
+
+/** Options for {@link resolveUserContext}. */
+export interface ResolveUserContextOptions {
+  /**
+   * The kit's best-effort auto-detected app version (#42; from `detectAppVersion()`/the device
+   * snapshot). Used ONLY when the explicit `WireUserContext.appVersion` is absent — explicit wins.
+   */
+  autoAppVersion?: string;
+}
+
+/**
+ * Merge a {@link WireUserContext} into the wire shape with the precedence rule (explicit field >
+ * auto-detected). Pure, never throws. Missing fields are omitted so the result can be spread onto an
+ * event without sending empties.
+ */
+export const resolveUserContext = (
+  ctx: WireUserContext = {},
+  opts: ResolveUserContextOptions = {},
+): ResolvedUserContext => {
+  const result: ResolvedUserContext = {};
+  const bucket: Record<string, string | number | boolean> = {};
+
+  // userId → top-level opaque id (NEVER the bucket). Sanitized + capped host-side.
+  const userId = sanitizeUserId(ctx.userId);
+  if (userId) result.userId = userId;
+
+  // deviceKey → user_context.device_key (NOT session_id).
+  const deviceKey = cleanString(ctx.deviceKey);
+  if (deviceKey) {
+    result.deviceKey = deviceKey;
+    bucket.device_key = deviceKey;
+  }
+
+  // appVersion → explicit wins over auto-detected (#42); echoed for device.appVersion callers.
+  const appVersion = cleanString(ctx.appVersion) ?? cleanString(opts.autoAppVersion);
+  if (appVersion) {
+    result.appVersion = appVersion;
+    bucket.app_version = appVersion;
+  }
+
+  // userEmail → its OWN key. OPT-IN PII, optionally folded. NEVER touches userId.
+  const email = cleanString(ctx.userEmail);
+  if (email) {
+    if (ctx.hashEmail) {
+      bucket.user_email = hashEmailFnv1a(email);
+      bucket.user_email_hashed = true;
+    } else {
+      bucket.user_email = email;
+    }
+  }
+
+  // extra → namespaced + scalar-coerced.
+  Object.assign(bucket, namespaceExtra(ctx.extra));
+
+  if (Object.keys(bucket).length > 0) result.userContext = bucket;
+  return result;
+};

package/src/device/appVersion.ts

@@ -0,0 +1,103 @@
+/**
+ * appVersion — best-effort, DEPENDENCY-FREE auto-detection of the host app's version string.
+ *
+ * WHY this exists: analytics segments the funnel `by_app_version`, but that breakdown is only
+ * populated when a `device.appVersion` rides the event. `config.appVersion` (see types.ts) has
+ * always been the way to supply it — but it is easy for a host to forget, and then the release
+ * breakdown is silently empty. This module fills that gap: when the host does NOT pass a version,
+ * the kit makes a best-effort read of the app version the host already ships in its Expo config,
+ * so the breakdown works out of the box. An explicit `config.appVersion` always WINS over this.
+ *
+ * WHY it adds NO dependency (the kit's hard rule): `expo-constants` / `expo-application` are read
+ * through a GUARDED, VARIABLE-specifier `require`. Passing a variable (not a string literal) keeps
+ * Metro/esbuild from statically resolving the module, so a host that does NOT have it installed
+ * (e.g. bare React Native) never fails to bundle — the require simply throws at runtime and is
+ * swallowed. Nothing is added to `package.json`; nothing is forced on the host.
+ *
+ * PRIVACY: an app version string is not PII and identifies no user or device, so surfacing it
+ * changes no App Privacy / Data Safety declaration (same guarantee as the rest of deviceContext).
+ *
+ * NEVER THROWS: every read is guarded; a missing/odd value yields `undefined`, never an exception.
+ * Analytics must never be able to break onboarding.
+ */
+
+// Metro injects a module-scoped `require`; it is ABSENT in a pure-ESM runtime. Declared locally so
+// this type-checks without ambient Node types; the `typeof` guard keeps the reference ESM-safe.
+declare const require: ((id: string) => unknown) | undefined;
+
+/** A `require`-like resolver. Injectable in tests; production uses the guarded runtime require. */
+export type OptionalRequire = (moduleName: string) => unknown;
+
+/** Trim + reject non-strings/empties so we only ever emit a real version string. */
+export const coerceVersion = (value: unknown): string | undefined => {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+};
+
+/**
+ * Guarded runtime require. `moduleName` is a VARIABLE (a parameter), so bundlers cannot statically
+ * resolve it — a host without the module never fails to build; the call just throws and is caught.
+ */
+const runtimeRequire: OptionalRequire = (moduleName) => {
+  try {
+    if (typeof require !== "function") return undefined;
+    return require(moduleName);
+  } catch {
+    return undefined;
+  }
+};
+
+/** Read a module's `default` (Expo modules are consumed as default exports) or the namespace. */
+const interop = (mod: unknown): Record<string, unknown> | undefined => {
+  if (!mod || typeof mod !== "object") return undefined;
+  const def = (mod as { default?: unknown }).default;
+  if (def && typeof def === "object") return def as Record<string, unknown>;
+  return mod as Record<string, unknown>;
+};
+
+/** Resolve a module namespace, swallowing a throwing require (an uninstalled module throws). */
+const safeInterop = (
+  requireModule: OptionalRequire,
+  moduleName: string,
+): Record<string, unknown> | undefined => {
+  try {
+    return interop(requireModule(moduleName));
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Detect the host app version, preferring `expo-constants` (`expoConfig.version`, then
+ * `nativeAppVersion`) and finally `expo-application` (`nativeApplicationVersion`). Returns the
+ * first real string, or `undefined` when none of those are available. Pure and never throws.
+ *
+ * `requireModule` is injectable so tests can exercise the "found" path without the native modules;
+ * production defaults to the guarded runtime require above.
+ */
+export const detectAppVersion = (
+  requireModule: OptionalRequire = runtimeRequire,
+): string | undefined => {
+  try {
+    const constants = safeInterop(requireModule, "expo-constants");
+    if (constants) {
+      const expoConfig = constants.expoConfig;
+      if (expoConfig && typeof expoConfig === "object") {
+        const fromExpoConfig = coerceVersion((expoConfig as { version?: unknown }).version);
+        if (fromExpoConfig) return fromExpoConfig;
+      }
+      const fromNative = coerceVersion(constants.nativeAppVersion);
+      if (fromNative) return fromNative;
+    }
+
+    const application = safeInterop(requireModule, "expo-application");
+    if (application) {
+      const fromApplication = coerceVersion(application.nativeApplicationVersion);
+      if (fromApplication) return fromApplication;
+    }
+  } catch {
+    // Any unexpected read error → "unknown"; analytics must never crash onboarding.
+  }
+  return undefined;
+};

package/src/device/deviceContext.ts

@@ -4,9 +4,12 @@
  * adding a single dependency to the kit or changing a host app's App Privacy / Data Safety
  * declarations.
  *
- * HARD RULE (why this file has no imports beyond React Native built-ins):
+ * HARD RULE (why this file adds no dependency):
  *   The kit stays dependency-free. Everything here comes from `Platform`, `Dimensions`,
- *   `I18nManager`, and the standard `Intl` global. There are NO advertising IDs, NO
+ *   `I18nManager`, and the standard `Intl` global — plus a best-effort `appVersion` read via
+ *   `detectAppVersion()`, which itself adds NO dependency (it reaches for `expo-constants` /
+ *   `expo-application` through a guarded, variable-specifier require that a host without them
+ *   simply never resolves — see device/appVersion.ts). There are NO advertising IDs, NO
  *   `getUniqueId`/IDFA/GAID/fingerprinting APIs, and nothing that would require a new
  *   privacy-label entry. A host can adopt this without touching its store declarations.
  *
@@ -17,6 +20,8 @@
  */
 import { Dimensions, I18nManager, Platform } from "react-native";
 
+import { detectAppVersion } from "./appVersion";
+
 /** Coarse device class. iOS uses the reported interface idiom; else a screen-size heuristic. */
 export type DeviceFormFactor = "phone" | "tablet";
 
@@ -50,9 +55,11 @@ export type DeviceContext = {
   /** IANA time zone (e.g. "Europe/Berlin"), from `Intl` when available. */
   timeZone?: string;
   /**
-   * Host app version (e.g. "1.4.2). HOST-INJECTED — NOT collected here. `WireOnboarding`
-   * merges `config.appVersion` into the snapshot; `collectDeviceContext()` never sets it.
-   * Hosts typically pass it from `expo-constants` (the kit itself adds no dependency).
+   * Host app version (e.g. "1.4.2"). BEST-EFFORT auto-detected here via `detectAppVersion()`
+   * (reads `expo-constants` / `expo-application` when present; adds no dependency — see
+   * device/appVersion.ts). An explicit host-injected `config.appVersion` always WINS: the merge
+   * sites (`WireOnboarding`, the session-analytics hooks, the context envelope) overwrite this
+   * with the host value when one is supplied. Omitted when neither source yields a version.
    */
   appVersion?: string;
 };
@@ -154,5 +161,10 @@ export const collectDeviceContext = (): DeviceContext => {
     // Intl unavailable — omit locale/timeZone.
   }
 
+  // Best-effort host app version (adds no dependency; omitted when unavailable). An explicit
+  // `config.appVersion` overrides this downstream at the merge sites.
+  const appVersion = detectAppVersion();
+  if (appVersion) ctx.appVersion = appVersion;
+
   return ctx;
 };

package/src/features/WireFeaturesProvider.tsx

@@ -18,8 +18,13 @@ import { defaultWireFeatures } from "./defaults";
 import { useWireFeatures } from "./useWireFeatures";
 import type { WireFeatures, WireFeaturesConfig } from "./types";
 
-/** null = no provider mounted (the signal `useResolvedFeatures` uses to fall back). */
-const WireFeaturesContext = createContext<WireFeatures | null>(null);
+const CONTEXT_SYMBOL = Symbol.for("wireai.features.context");
+const globalObj = global as any;
+
+if (!globalObj[CONTEXT_SYMBOL]) {
+  globalObj[CONTEXT_SYMBOL] = createContext<WireFeatures | null>(null);
+}
+const WireFeaturesContext = globalObj[CONTEXT_SYMBOL];
 
 export interface WireFeaturesProviderProps {
   /** Tenant creds (+ optional storage) to fetch the flags once for the whole tree. */

package/src/identity/userIdentity.ts

@@ -20,6 +20,7 @@
  * ⚠️ NO PII. Pass an opaque id (or a hash), never a raw email/name/phone. The id is capped at
  * {@link USER_ID_MAX_LENGTH} chars (longer ids are truncated, not rejected).
  */
+import { getCurrentSessionId } from "../analytics/currentSession";
 import { reportClientEvent } from "../analytics/reportClientEvent";
 import {
   peekPersistedSession,
@@ -90,6 +91,10 @@ 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();
   if (!contextId) return false;
 
   reportClientEvent(