@wireai/activation 0.1.0

package/src/components/LoadingScreen.tsx

@@ -0,0 +1,35 @@
+/**
+ * LoadingScreen — the STANDALONE loader surface: a full-area safe frame that centers a
+ * LoadingBlock dead in the middle of the screen. Used for the loader slots that render on
+ * their own (no OnboardingScaffold around them): the cold-start "getting started" wait, the
+ * resumed-session "restoring" wait, and the transient error/timeout retry beat.
+ *
+ * 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.
+ */
+import React from "react";
+import { StyleSheet } from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
+import { useOnboardingTheme } from "../theme/ThemeContext";
+import { LoadingBlock, type LoadingBlockProps } from "./LoadingBlock";
+
+const _LoadingScreen: React.FC<LoadingBlockProps> = ({ title, hint }) => {
+  const t = useOnboardingTheme();
+  return (
+    <SafeAreaView
+      edges={["top", "bottom"]}
+      style={[styles.flex, { backgroundColor: t.colors.background }]}
+    >
+      <LoadingBlock title={title} hint={hint} />
+    </SafeAreaView>
+  );
+};
+
+export const LoadingScreen = React.memo(_LoadingScreen);
+
+const styles = StyleSheet.create({
+  flex: { flex: 1 },
+});

package/src/components/OnboardingScaffold.tsx

@@ -0,0 +1,105 @@
+/**
+ * OnboardingScaffold — the themed shell that wraps every step:
+ *   [ safe area ]
+ *     header   -> StepProgress (a numberless fill — never "Step X of N") + optional Skip
+ *     body     -> the rendered card (children), full-screen (flex: 1)
+ *     footer   -> optional Back link
+ *
+ * WHY a single scaffold: the body content changes every turn (it's an
+ * SDK-rendered card), but the chrome — progress, skip, back, padding, safe area —
+ * stays constant. Keeping it here means cards never re-implement the frame.
+ *
+ * The body no longer centers/scrolls the card: each card fills the body via the
+ * shared CardLayout, which owns its own scroll + bottom-pinned CTA (Cal-AI style).
+ * The safe area uses `react-native-safe-area-context` (top + bottom edges) — the
+ * 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 { StyleSheet, Text, TouchableOpacity, View } from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
+import { useOnboardingTheme } from "../theme/ThemeContext";
+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. */
+  step: number;
+  /** When true, the progress bar fills to 100% (flow finished). */
+  complete?: boolean;
+  /** Approximate total screens, if known — paces the bar (never shown). */
+  approxScreens?: number;
+  /** Optional Back action — hidden when omitted (e.g. on the first step). */
+  onBack?: () => void;
+  /** Optional Skip action — hidden when omitted. */
+  onSkip?: () => void;
+  skipLabel?: string;
+  backLabel?: string;
+  children: React.ReactNode;
+};
+
+const _OnboardingScaffold: React.FC<OnboardingScaffoldProps> = ({
+  step,
+  complete,
+  approxScreens,
+  onBack,
+  onSkip,
+  skipLabel = "Skip",
+  backLabel = "Back",
+  children,
+}) => {
+  const t = useOnboardingTheme();
+  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"]}
+      style={[styles.flex, { backgroundColor: t.colors.background }]}
+    >
+      <View style={[styles.header, { paddingHorizontal: t.spacing.md, paddingTop: t.spacing.md }]}>
+        <View style={styles.progressWrap}>
+          <StepProgress step={step} complete={complete} approxScreens={approxScreens} />
+        </View>
+        {onSkip ? (
+          <TouchableOpacity onPress={onSkip} hitSlop={hit} style={{ marginLeft: t.spacing.md }}>
+            <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>
+      </View>
+
+      {onBack ? (
+        <View style={[styles.footer, { paddingHorizontal: t.spacing.md, paddingBottom: t.spacing.sm }]}>
+          <TouchableOpacity onPress={onBack} hitSlop={hit}>
+            <Text style={[bodyStyle(t.fonts), { color: t.colors.textMuted }]}>{backLabel}</Text>
+          </TouchableOpacity>
+        </View>
+      ) : null}
+    </SafeAreaView>
+  );
+};
+
+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" },
+});

package/src/components/StepProgress.tsx

@@ -0,0 +1,85 @@
+/**
+ * StepProgress — a single themed progress bar that conveys forward motion. It never
+ * shows a "Step X of N" number (the count would read as a promise the model may not
+ * keep), but it can be *paced* two ways:
+ *
+ *  - Default (no `approxScreens`): an asymptotic curve of the step index — always
+ *    advances, never reaches the end until the flow actually completes.
+ *  - With `approxScreens`: when the host knows roughly how many screens the flow
+ *    runs (e.g. the backend's screen budget), the fill tracks `step / approxScreens`
+ *    (capped below 100% until `complete`). More truthful pacing, still no number.
+ */
+import React, { useEffect, useRef } from "react";
+import { Animated, Easing, StyleSheet, View } from "react-native";
+import { useOnboardingTheme } from "../theme/ThemeContext";
+import { PROGRESS_MS, WIRE_BEZIER, scaledMs, stateChangeDuration } from "../motion/motionSpec";
+import { useReducedMotion } from "../motion/useReducedMotion";
+
+const easeWire = Easing.bezier(...WIRE_BEZIER);
+
+export type StepProgressProps = {
+  /** 1-based index of the current step. Drives the fill. */
+  step: number;
+  /** When true, fill to 100% (flow finished). */
+  complete?: boolean;
+  /**
+   * Approximate total number of screens, if known (e.g. the backend screen budget).
+   * Paces the bar as `step / approxScreens` instead of the asymptotic curve. Never
+   * shown as a number — it only shapes the fill. Omit for the asymptotic default.
+   */
+  approxScreens?: number;
+};
+
+// Asymptotic default: each step closes ~38% of the remaining gap, so the bar always
+// moves but never hits the end on its own: step1≈38%, step2≈62%, step3≈76%…
+const DECAY = 0.62;
+const MIN_FILL = 0.08;
+// When pacing by an approximate total, never look finished until `complete`.
+const APPROX_CAP = 0.95;
+
+const targetFor = (step: number, complete?: boolean, approxScreens?: number): number => {
+  if (complete) return 1;
+  const s = Number.isFinite(step) && step > 0 ? Math.floor(step) : 1;
+  if (approxScreens && approxScreens > 0) {
+    return Math.max(MIN_FILL, Math.min(APPROX_CAP, s / approxScreens));
+  }
+  return Math.max(MIN_FILL, 1 - DECAY ** s);
+};
+
+const _StepProgress: React.FC<StepProgressProps> = ({ step, complete, approxScreens }) => {
+  const t = useOnboardingTheme();
+  const reduced = useReducedMotion();
+  const fill = useRef(new Animated.Value(targetFor(step, complete, approxScreens))).current;
+
+  // 400ms ease-wire per the design spec (design-refs/EXTRACTED-SPEC.md row 21).
+  // A growing total re-targets the same value, so the fill eases forward and never
+  // snaps back. Reduce motion: jump straight to the ratio.
+  useEffect(() => {
+    Animated.timing(fill, {
+      toValue: targetFor(step, complete, approxScreens),
+      duration: scaledMs(stateChangeDuration(reduced, PROGRESS_MS)),
+      easing: easeWire,
+      useNativeDriver: false, // animating width %
+    }).start();
+  }, [fill, step, complete, approxScreens, reduced]);
+
+  const width = fill.interpolate({ inputRange: [0, 1], outputRange: ["0%", "100%"] });
+
+  return (
+    <View style={[styles.track, { backgroundColor: t.colors.border, borderRadius: t.radius.full }]}>
+      <Animated.View
+        style={[
+          styles.fill,
+          { width, backgroundColor: t.colors.primary, borderRadius: t.radius.full },
+        ]}
+      />
+    </View>
+  );
+};
+
+export const StepProgress = React.memo(_StepProgress);
+
+const styles = StyleSheet.create({
+  track: { height: 6, width: "100%", overflow: "hidden" },
+  fill: { height: 6 },
+});

package/src/components/loaderChrome.ts

@@ -0,0 +1,28 @@
+/**
+ * loaderChrome — the seam that lets a loader center in the FULL flow area instead of
+ * the header-offset body it happens to render into.
+ *
+ * The between-turns loader lives inside the OnboardingScaffold body (so the card↔loader
+ * handoff stays one coordinated CardHandoff — see OnboardingFlow). But the body sits
+ * BELOW the header (the StepProgress bar), so a loader that only fills the body centers
+ * a little low — the "not centralized in the screen" device finding. The scaffold knows
+ * its own top chrome, so it publishes a vertical offset here; LoadingBlock reads it and
+ * shifts its centered content up by that much, landing it at the true screen center
+ * WITHOUT moving the body (the card underneath is untouched, so the handoff never jumps).
+ *
+ * Default 0: a LoadingBlock rendered OUTSIDE a scaffold (the standalone LoadingScreen used
+ * for cold-start / restoring / error) has no header above it, so it already centers in the
+ * full area and needs no shift.
+ */
+import { createContext, useContext } from "react";
+
+export type LoaderChrome = {
+  /** Vertical shift (px, usually negative = up) that re-centers a loader against the full flow area. */
+  offsetY: number;
+};
+
+const LoaderChromeContext = createContext<LoaderChrome>({ offsetY: 0 });
+
+export const LoaderChromeProvider = LoaderChromeContext.Provider;
+
+export const useLoaderChrome = (): LoaderChrome => useContext(LoaderChromeContext);

package/src/config/onboardingFlag.ts

@@ -0,0 +1,39 @@
+/**
+ * isOnboardingEnabled — the ONE standard gate for AI onboarding, so every app stops
+ * re-authoring `flag && hasConfig` (one app had `isAiOnboardingEnabled`, another had
+ * `isWireBackendConfigured` — same idea, two shapes).
+ *
+ * The gate is **transport presence**: `wireConfigFromEnv()` is non-null (the key + URL are
+ * set), and that is it. There is no separate on/off env flag — a missing key already means
+ * "off", so a second `EXPO_PUBLIC_AI_ONBOARDING_ENABLED` flag was redundant (and, read via
+ * computed access, it didn't even inline on device). An optional `remote` kill-switch lets an
+ * app turn it off without a release; the kit stays dependency-free (the app owns the remote
+ * read and hands us the boolean).
+ *
+ * Enabled ⇔ transport present AND `(remote ?? true)`.
+ *
+ *   if (!isOnboardingEnabled()) return goToStaticOnboarding();
+ *   // or, with a remote kill-switch the app already read:
+ *   if (!isOnboardingEnabled({ remote: remoteKillSwitchOn })) return goToStaticOnboarding();
+ */
+import { wireConfigFromEnv } from "./wireConfigFromEnv";
+import type { WireConfigOverrides } from "./wireConfigFromEnv";
+
+export type OnboardingFlagOptions = {
+  /**
+   * Optional remote kill-switch the app already read (Firebase/LD/etc.). When `false`, it
+   * disables onboarding even though transport is present. Omit (or `true`) to leave it on.
+   */
+  remote?: boolean;
+  /**
+   * Config overrides forwarded to `wireConfigFromEnv` for the transport-present check
+   * (e.g. a programmatic `apiKey`/`serverUrl`). Usually omitted.
+   */
+  config?: WireConfigOverrides;
+};
+
+export const isOnboardingEnabled = (opts?: OnboardingFlagOptions): boolean => {
+  const transportPresent = wireConfigFromEnv(opts?.config) !== null;
+  if (!transportPresent) return false;
+  return opts?.remote ?? true;
+};

package/src/config/wireConfigFromEnv.ts

@@ -0,0 +1,52 @@
+/**
+ * wireConfigFromEnv — stop re-authoring env gating in every app. Reads the Wire AI
+ * tenant key + server URL from the standard Expo public env vars and returns a
+ * ready `WireOnboardingConfig`, or `null` when the key/URL are missing (so a host
+ * can fall through to a static onboarding without writing the `if (!key)` itself).
+ *
+ *   EXPO_PUBLIC_WIREAI_API_KEY=...      (required)
+ *   EXPO_PUBLIC_WIREAI_SERVER_URL=...   (required)
+ *
+ *   const config = wireConfigFromEnv({ appId: "morrow" });
+ *   if (!config) return <StaticOnboarding />;
+ *   return <WireOnboarding config={config} ... />;
+ *
+ * `appId` defaults to `EXPO_PUBLIC_WIREAI_APP_ID` (or "default"); pass overrides to
+ * set `appId`/`metadata` or to substitute the key/URL programmatically.
+ */
+import type { WireOnboardingConfig } from "../types";
+
+export type WireConfigOverrides = Partial<WireOnboardingConfig>;
+
+/**
+ * Minimal `process.env` declaration so the kit stays RN-pure (no `@types/node`).
+ * In RN/Expo, `process.env.EXPO_PUBLIC_*` is provided/inlined by Metro at build
+ * time; we only read string env vars here.
+ *
+ * IMPORTANT: read each var via STATIC member access (`process.env.EXPO_PUBLIC_FOO`).
+ * Expo's `babel-preset-expo` `inline-env-vars` plugin ONLY inlines static
+ * `process.env.EXPO_PUBLIC_*` member expressions. Aliasing (`const env = process.env`)
+ * or computed access (`process.env[name]`) is left `undefined` in the Metro bundle, so
+ * the value reads fine in Jest (Node) but is null on a real device. Do not refactor
+ * these to an alias.
+ */
+declare const process: { env: Record<string, string | undefined> };
+
+export const wireConfigFromEnv = (
+  overrides?: WireConfigOverrides,
+): WireOnboardingConfig | null => {
+  const apiKey = overrides?.apiKey ?? process.env.EXPO_PUBLIC_WIREAI_API_KEY;
+  const serverUrl = overrides?.serverUrl ?? process.env.EXPO_PUBLIC_WIREAI_SERVER_URL;
+  const appId =
+    overrides?.appId ?? process.env.EXPO_PUBLIC_WIREAI_APP_ID ?? "default";
+
+  // Missing transport → null, so the host gates on one falsy check.
+  if (!apiKey || !serverUrl) return null;
+
+  return {
+    apiKey,
+    serverUrl,
+    appId,
+    ...(overrides?.metadata ? { metadata: overrides.metadata } : {}),
+  };
+};

package/src/device/deviceContext.ts

@@ -0,0 +1,158 @@
+/**
+ * deviceContext — collect a small, privacy-label-neutral snapshot of the device so
+ * onboarding analytics can segment the funnel (platform / form factor / locale) WITHOUT
+ * 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):
+ *   The kit stays dependency-free. Everything here comes from `Platform`, `Dimensions`,
+ *   `I18nManager`, and the standard `Intl` global. 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.
+ *
+ * DEFENSIVE BY DESIGN: `collectDeviceContext()` never throws. Every read is guarded and
+ * a missing/unavailable field is simply omitted (Hermes may ship without full `Intl`,
+ * `Platform.constants` differs per OS and RN version, etc.). Analytics must never be able
+ * to break onboarding.
+ */
+import { Dimensions, I18nManager, Platform } from "react-native";
+
+/** Coarse device class. iOS uses the reported interface idiom; else a screen-size heuristic. */
+export type DeviceFormFactor = "phone" | "tablet";
+
+/**
+ * A privacy-label-neutral device snapshot. ALL fields except `platform` are optional and are
+ * omitted when unavailable. Nothing here identifies a user or device uniquely.
+ */
+export type DeviceContext = {
+  /** `Platform.OS` — "ios" | "android" | "windows" | "macos" | "web". Always present. */
+  platform: typeof Platform.OS;
+  /** OS version string (iOS `osVersion`/`Platform.Version`, Android `Release`). */
+  osVersion?: string;
+  /** Android device brand (e.g. "samsung"). Android only. */
+  brand?: string;
+  /** Android device model (e.g. "SM-G991B"). Android only. */
+  model?: string;
+  /** iOS interface idiom ("phone" | "pad" | …), when reported. iOS only. */
+  interfaceIdiom?: string;
+  /** Derived device class. */
+  formFactor?: DeviceFormFactor;
+  /** `Dimensions.get('screen')` width in dp. */
+  screenWidth?: number;
+  /** `Dimensions.get('screen')` height in dp. */
+  screenHeight?: number;
+  /** Screen pixel density (`scale`). */
+  screenScale?: number;
+  /** Right-to-left layout (`I18nManager.isRTL`). */
+  isRTL?: boolean;
+  /** Resolved locale (e.g. "en-US"), from `Intl` when available. */
+  locale?: string;
+  /** 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).
+   */
+  appVersion?: string;
+};
+
+/** iOS idiom wins; otherwise the shortest side in dp (>= 600 → tablet) picks the class. */
+const deriveFormFactor = (
+  iosIdiom: string | undefined,
+  width: number | undefined,
+  height: number | undefined,
+): DeviceFormFactor | undefined => {
+  if (iosIdiom === "pad") return "tablet";
+  if (iosIdiom === "phone") return "phone";
+  if (typeof width === "number" && typeof height === "number") {
+    return Math.min(width, height) >= 600 ? "tablet" : "phone";
+  }
+  return undefined;
+};
+
+/**
+ * Collect the device snapshot. Pure, synchronous, and never throws — call it once per
+ * onboarding session. Missing fields are omitted rather than sent as null/undefined so the
+ * payload (and the server's stored dict) stays compact.
+ */
+export const collectDeviceContext = (): DeviceContext => {
+  const ctx: DeviceContext = { platform: Platform.OS };
+
+  // OS version (fallback; per-OS constants below may refine it).
+  try {
+    const version = Platform.Version;
+    if (version !== undefined && version !== null && String(version)) {
+      ctx.osVersion = String(version);
+    }
+  } catch {
+    // ignore
+  }
+
+  // `Platform.constants` shape differs by OS and RN version — read every field defensively.
+  let constants: Record<string, unknown> = {};
+  try {
+    constants = (Platform.constants ?? {}) as Record<string, unknown>;
+  } catch {
+    constants = {};
+  }
+
+  let iosIdiom: string | undefined;
+  try {
+    if (Platform.OS === "android") {
+      const brand = constants.Brand;
+      const model = constants.Model;
+      const release = constants.Release;
+      if (typeof brand === "string" && brand) ctx.brand = brand;
+      if (typeof model === "string" && model) ctx.model = model;
+      if (release !== undefined && release !== null && String(release)) {
+        ctx.osVersion = String(release);
+      }
+    } else if (Platform.OS === "ios") {
+      const osVersion = constants.osVersion;
+      const idiom = constants.interfaceIdiom;
+      if (osVersion !== undefined && osVersion !== null && String(osVersion)) {
+        ctx.osVersion = String(osVersion);
+      }
+      if (typeof idiom === "string" && idiom) {
+        ctx.interfaceIdiom = idiom;
+        iosIdiom = idiom;
+      }
+    }
+  } catch {
+    // ignore per-OS constant reads
+  }
+
+  // Screen dimensions + derived form factor.
+  try {
+    const screen = Dimensions.get("screen");
+    if (screen) {
+      if (typeof screen.width === "number") ctx.screenWidth = screen.width;
+      if (typeof screen.height === "number") ctx.screenHeight = screen.height;
+      if (typeof screen.scale === "number") ctx.screenScale = screen.scale;
+      const formFactor = deriveFormFactor(iosIdiom, screen.width, screen.height);
+      if (formFactor) ctx.formFactor = formFactor;
+    }
+  } catch {
+    // ignore
+  }
+
+  // Layout direction.
+  try {
+    ctx.isRTL = I18nManager.isRTL;
+  } catch {
+    // ignore
+  }
+
+  // Locale + time zone via the standard Intl global. Hermes may ship without full Intl,
+  // so referencing it can throw ReferenceError — the try/catch covers that too.
+  try {
+    const resolved = Intl.DateTimeFormat().resolvedOptions();
+    if (resolved.locale) ctx.locale = resolved.locale;
+    if (resolved.timeZone) ctx.timeZone = resolved.timeZone;
+  } catch {
+    // Intl unavailable — omit locale/timeZone.
+  }
+
+  return ctx;
+};

package/src/features/WireFeaturesProvider.tsx

@@ -0,0 +1,81 @@
+/**
+ * WireFeaturesProvider + useResolvedFeatures — the OPTIONAL one-fetch-serves-all-modules layer.
+ *
+ * Mount `WireFeaturesProvider` once near your app root with the tenant `config` and it fetches the
+ * flags ONCE; every gated surface below it (coachmarks / showcase / reviews) reads the same
+ * resolved value from context instead of each fetching its own. It is entirely optional: with no
+ * provider, every surface falls back to its own lazy fetch (when given a config) or to the all-on
+ * defaults, so modules work with zero setup and a host that never adopts flags is unchanged.
+ *
+ * NOTE on the built npm subpaths: React context is shared across the kit's subpath entries in the
+ * SOURCE-consumption path (the monorepo apps) and in this test suite — one module instance, one
+ * context. If you consume the built `wireai-onboarding/*` subpaths as separate bundles, pass the
+ * resolved flags (or a `featuresConfig`) to each surface explicitly instead of relying on context.
+ */
+import React, { createContext, useContext, useMemo } from "react";
+
+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);
+
+export interface WireFeaturesProviderProps {
+  /** Tenant creds (+ optional storage) to fetch the flags once for the whole tree. */
+  config?: WireFeaturesConfig;
+  /**
+   * Pre-resolved flags to provide directly instead of fetching (e.g. you already have them, or
+   * you drive them from your own remote-config). Takes precedence over `config`.
+   */
+  flags?: WireFeatures;
+  children: React.ReactNode;
+}
+
+/**
+ * Fetch (or accept) the flags once and broadcast them to descendants. The provider VALUE is
+ * memoized (performance rule #6) so a fresh object each render doesn't re-render every consumer.
+ */
+export const WireFeaturesProvider: React.FC<WireFeaturesProviderProps> = ({
+  config,
+  flags,
+  children,
+}) => {
+  // Always call the hook (rules of hooks); when `flags` is supplied we pass no config so it
+  // never fetches and the explicit flags win below.
+  const fetched = useWireFeatures(flags ? undefined : config);
+  const value = flags ?? fetched;
+  const stable = useMemo(() => value, [value]);
+  return <WireFeaturesContext.Provider value={stable}>{children}</WireFeaturesContext.Provider>;
+};
+
+WireFeaturesProvider.displayName = "WireFeaturesProvider";
+
+/** Raw context read — `null` when no `WireFeaturesProvider` is mounted above. */
+export const useWireFeaturesContext = (): WireFeatures | null =>
+  useContext(WireFeaturesContext);
+
+/** Options for `useResolvedFeatures`: an explicit override and/or a lazy-fetch config. */
+export interface ResolveFeaturesOptions {
+  /** Explicit flags — win over everything (a surface's own `features` prop). */
+  flags?: WireFeatures;
+  /** Lazy-fetch config, used ONLY when there is no explicit `flags` and no provider above. */
+  config?: WireFeaturesConfig;
+}
+
+/**
+ * The resolution every gated surface uses. Precedence:
+ *   1. explicit `options.flags` (a surface's own prop)  →
+ *   2. the nearest `WireFeaturesProvider` (context)     →
+ *   3. a lazy fetch from `options.config` (serverUrl + apiKey)  →
+ *   4. the all-on defaults.
+ * Always fail-open, always a stable reference for a given value (so it's safe in effect deps).
+ */
+export const useResolvedFeatures = (options?: ResolveFeaturesOptions): WireFeatures => {
+  const ctx = useWireFeaturesContext();
+  // Only lazily fetch when nothing else provides the flags — otherwise pass no config so the
+  // hook stays inert (defaults, no network). The hook is always called (rules of hooks).
+  const shouldFetch = !options?.flags && ctx == null;
+  const fetched = useWireFeatures(shouldFetch ? options?.config : undefined);
+  return options?.flags ?? ctx ?? fetched ?? defaultWireFeatures;
+};