@wireai/activation 0.1.0

package/src/coachmarks/CoachmarkProvider.tsx

@@ -0,0 +1,108 @@
+import React, { useEffect } from "react";
+
+import { useResolvedFeatures } from "../features/WireFeaturesProvider";
+import type { WireFeatures, WireFeaturesConfig } from "../features/types";
+import { CoachmarkOverlayHost } from "./CoachmarkOverlayHost";
+import {
+  getCoachmarkStorage,
+  setCoachmarkStorage,
+  setCoachmarksEnabled,
+  setCoachmarkTesting,
+} from "./runtime";
+import type { CoachmarkStorage } from "./types";
+
+export interface CoachmarkProviderProps {
+  /**
+   * SYNCHRONOUS gate storage (MMKV-friendly). Reads must not be async or a ring
+   * would flash before the "already seen" gate resolves. See CoachmarkStorage.
+   */
+  storage: CoachmarkStorage;
+  /**
+   * QA replay switch. When true, every seen-gate reads as unseen AND seen-writes
+   * are suppressed, so every tour + showcase replays on each mount. Flip ONE
+   * boolean to re-see the whole coachmark surface.
+   */
+  isTestingCoachmark?: boolean;
+  /** Ring + tooltip color for every tour. Defaults to the onboarding theme's `primary`. */
+  accentColor?: string;
+  /**
+   * Text/icon color on the accent surface (e.g. the tooltip's CTA label).
+   * Defaults to the onboarding theme's `onPrimary`.
+   */
+  accentTextColor?: string;
+  /**
+   * OPTIONAL feature-flag wiring. When `flags.coachmarks.enabled` is false, every tour + overlay
+   * request becomes a silent no-op (once-gates are NOT consumed, so re-enabling replays). Provide
+   * pre-resolved `features`, OR a `featuresConfig` (serverUrl + apiKey) to lazily fetch once, OR
+   * mount a `WireFeaturesProvider` above (context is read automatically). Omit all three and
+   * coachmarks stay on (fail-open) — zero behavior change for hosts that never adopt flags.
+   */
+  features?: WireFeatures;
+  /** Lazy-fetch config for the flags, used when `features` is absent and no provider is above. */
+  featuresConfig?: WireFeaturesConfig;
+  children: React.ReactNode;
+}
+
+/**
+ * Mount ONCE at the app root — wrap it around (or just inside) your
+ * NavigationContainer so the overlay host is a root-level sibling of the whole
+ * app tree. That placement is what lets a ring + blur paint ABOVE the bottom tab
+ * bar, which react-navigation renders over screen components.
+ *
+ * It feeds the sync storage + testing flag into the engine's module-level
+ * singletons so `useCoachmarkTour` / `useCoachmarkAnchor` work from anywhere in
+ * the tree without prop-drilling, then renders the overlay host as a sibling
+ * after `children` (the SpotlightOverlay self-positions absolute-fill at
+ * zIndex/elevation 9999).
+ *
+ * The singletons are set during render (not in an effect) so a child's mount
+ * effect — which runs BEFORE this parent's effects — already sees the storage
+ * when it reads its gate.
+ */
+export const CoachmarkProvider: React.FC<CoachmarkProviderProps> = ({
+  storage,
+  isTestingCoachmark = false,
+  accentColor,
+  accentTextColor,
+  features,
+  featuresConfig,
+  children,
+}) => {
+  // Resolve the coachmarks kill switch: explicit `features` → context → lazy fetch → all-on.
+  const flags = useResolvedFeatures({ flags: features, config: featuresConfig });
+  const coachmarksOn = flags.coachmarks.enabled;
+
+  // Apply during render so gates + the kill switch are readable before any child effect fires.
+  setCoachmarkStorage(storage);
+  setCoachmarkTesting(isTestingCoachmark);
+  setCoachmarksEnabled(coachmarksOn);
+
+  useEffect(() => {
+    setCoachmarkStorage(storage);
+    setCoachmarkTesting(isTestingCoachmark);
+    setCoachmarksEnabled(coachmarksOn);
+    return () => {
+      // Only clear if THIS provider's storage is still the live singleton — a
+      // newer provider that mounted before this one unmounts must not be wiped.
+      if (getCoachmarkStorage() === storage) {
+        setCoachmarkStorage(null);
+      }
+      // Restore the fail-open default so a torn-down provider never leaves coachmarks dark.
+      setCoachmarksEnabled(true);
+    };
+  }, [storage, isTestingCoachmark, coachmarksOn]);
+
+  return (
+    <>
+      {children}
+      <CoachmarkOverlayHost
+        accentColor={accentColor}
+        accentTextColor={accentTextColor}
+      />
+    </>
+  );
+};
+
+CoachmarkProvider.displayName = "CoachmarkProvider";
+
+export default CoachmarkProvider;

package/src/coachmarks/GestureHint.tsx

@@ -0,0 +1,331 @@
+import React, { useEffect, useMemo, type ReactNode } from "react";
+import { StyleSheet, View } from "react-native";
+import Animated, {
+  useAnimatedStyle,
+  useReducedMotion,
+  useSharedValue,
+  withDelay,
+  withRepeat,
+  withSequence,
+  withTiming,
+} from "react-native-reanimated";
+
+import type { GestureKind } from "./types";
+
+/**
+ * Abstract gesture pictogram shown beside a coachmark tooltip. Pure reanimated —
+ * every animation runs on the UI thread (shared values + worklets), never
+ * setState, so it costs nothing on the JS thread. Honors Reduce Motion by
+ * dropping the motion loop and rendering the glyph static.
+ *
+ * NO drawn-hand anatomy. Swipes render the standard two-finger swipe glyph: two
+ * rounded vertical capsules (an abstract index + middle finger, slightly
+ * different heights) with a short, fading motion track trailing behind them along
+ * the swipe axis. The whole glyph is rotated per direction (up/down/left/right)
+ * and the capsules slide along the axis, fading, in a UI-thread loop. Pinch/zoom
+ * reuse the two-capsule abstraction spreading apart. Tap / double-tap render a
+ * minimal pulsing tap-target (ring + dot).
+ *
+ * Every glyph is a self-drawn primitive built from Views/borders (no vector-icon
+ * dependency, like AnimatedSparkle). Pass `renderHand` — the glyph slot — to
+ * substitute your own node while keeping the tuned motion. (The name is kept for
+ * backward compatibility; despite it, the default is a glyph, not a drawn hand.)
+ *
+ * NOTE: the coachmark path (SpotlightOverlay) and the showcase path
+ * (FeatureShowcase) both SKIP this component for `tap` / `double_tap` — those
+ * steps show only the highlight ring + tooltip, no glyph. The tap visual here
+ * exists for direct / standalone use.
+ */
+export interface GestureHintProps {
+  type: GestureKind;
+  /** Overall glyph size in px. */
+  size?: number;
+  /** Glyph color. Defaults to white (reads on the dark blur backdrop). */
+  color?: string;
+  /**
+   * Provide a custom glyph node in place of the default self-drawn primitive; it
+   * inherits the tuned motion (slide+fade for swipes, pulse for tap). Kept as
+   * `renderHand` for backward compatibility — despite the name it is just the
+   * glyph slot, no longer a drawn hand.
+   */
+  renderHand?: (props: { size: number; color: string }) => ReactNode;
+}
+
+/** Travel distance for the directional swipe loop (local glyph axis). */
+const TRAVEL = 26;
+const SWIPE_MS = 700;
+const TAP_MS = 320;
+const SPREAD_MS = 620;
+
+/**
+ * Per-direction rotation of the whole glyph. Canonical orientation is "up":
+ * capsules point up, travel up, motion track trailing below. Rotating the
+ * container reorients both the capsules and the track together, and rotates the
+ * local translate axis so the same upward loop reads correctly per direction.
+ */
+const GLYPH_ROTATION: Record<string, string> = {
+  swipe_up: "0deg",
+  swipe_down: "180deg",
+  swipe_left: "-90deg",
+  swipe_right: "90deg",
+};
+
+/**
+ * The two-finger abstraction: two rounded vertical capsules side by side with
+ * slightly different heights (index taller than middle), aligned at the base —
+ * the standard swipe pictogram look. Self-drawn from Views only.
+ */
+const FingerPair: React.FC<{ size: number; color: string }> = ({ size, color }) => {
+  const { row, index, middle } = useMemo(() => {
+    const w = size * 0.2;
+    const r = w / 2;
+    return {
+      row: { flexDirection: "row" as const, alignItems: "flex-end" as const, gap: size * 0.08 },
+      index: { width: w, height: size * 0.54, borderRadius: r, backgroundColor: color },
+      middle: { width: w, height: size * 0.44, borderRadius: r, backgroundColor: color },
+    };
+  }, [size, color]);
+
+  return (
+    <View style={row} pointerEvents="none">
+      <View style={index} />
+      <View style={middle} />
+    </View>
+  );
+};
+
+/**
+ * A short, tapering motion track that sits behind the capsules (below, in the
+ * canonical "up" orientation) — two slim, fading ticks that shrink and dim with
+ * distance. Subtle: it reads as the path the fingers just travelled, not a comet
+ * tail. Static (the capsules carry the motion via the slide loop).
+ */
+const MotionTrack: React.FC<{ size: number; color: string }> = ({ size, color }) => {
+  const { wrap, tick0, tick1 } = useMemo(() => {
+    const h = Math.max(2, size * 0.05);
+    return {
+      wrap: { alignItems: "center" as const, marginTop: size * 0.1, gap: size * 0.06 },
+      tick0: {
+        width: size * 0.3,
+        height: h,
+        borderRadius: h / 2,
+        backgroundColor: color,
+        opacity: 0.4,
+      },
+      tick1: {
+        width: size * 0.18,
+        height: h,
+        borderRadius: h / 2,
+        backgroundColor: color,
+        opacity: 0.16,
+      },
+    };
+  }, [size, color]);
+
+  return (
+    <View style={wrap} pointerEvents="none">
+      <View style={tick0} />
+      <View style={tick1} />
+    </View>
+  );
+};
+
+const GestureHintComponent: React.FC<GestureHintProps> = ({
+  type,
+  size = 34,
+  color = "white",
+  renderHand,
+}) => {
+  const translate = useSharedValue(0);
+  const opacity = useSharedValue(1);
+  const pulse = useSharedValue(1);
+  const spread = useSharedValue(0);
+  const reduced = useReducedMotion();
+
+  const isSwipe =
+    type === "swipe_up" ||
+    type === "swipe_down" ||
+    type === "swipe_left" ||
+    type === "swipe_right";
+  const isSpread = type === "pinch" || type === "zoom";
+  const isTap = type === "tap" || type === "double_tap";
+
+  useEffect(() => {
+    if (type === "none" || reduced) return undefined;
+
+    if (isTap) {
+      pulse.value = withRepeat(
+        withSequence(
+          withTiming(0.82, { duration: TAP_MS }),
+          withTiming(1, { duration: TAP_MS }),
+        ),
+        -1,
+        false,
+      );
+      opacity.value = withRepeat(
+        withSequence(
+          withTiming(0.55, { duration: TAP_MS }),
+          withTiming(1, { duration: TAP_MS }),
+        ),
+        -1,
+        false,
+      );
+      return undefined;
+    }
+
+    if (isSpread) {
+      // Two capsules easing apart and back — a minimal pinch/zoom abstraction.
+      spread.value = withRepeat(
+        withSequence(
+          withTiming(size * 0.26, { duration: SPREAD_MS }),
+          withTiming(0, { duration: SPREAD_MS }),
+        ),
+        -1,
+        false,
+      );
+      return undefined;
+    }
+
+    // Directional swipe: slide the capsules along the local "up" axis, fading
+    // out, then snap back and repeat. The container rotation (below) reorients
+    // this loop per direction, so the local motion is always the same.
+    translate.value = withRepeat(
+      withSequence(
+        withTiming(0, { duration: 0 }),
+        withTiming(-TRAVEL, { duration: SWIPE_MS }),
+        withDelay(140, withTiming(0, { duration: 0 })),
+      ),
+      -1,
+      false,
+    );
+    opacity.value = withRepeat(
+      withSequence(
+        withTiming(1, { duration: SWIPE_MS / 2 }),
+        withTiming(0, { duration: SWIPE_MS / 2 }),
+        withDelay(140, withTiming(1, { duration: 0 })),
+      ),
+      -1,
+      false,
+    );
+    return undefined;
+  }, [type, reduced, isTap, isSpread, translate, opacity, pulse, spread, size]);
+
+  const swipeAnimatedStyle = useAnimatedStyle(() => ({
+    opacity: opacity.value,
+    transform: [{ translateY: translate.value }],
+  }));
+  const tapAnimatedStyle = useAnimatedStyle(() => ({
+    opacity: opacity.value,
+    transform: [{ scale: pulse.value }],
+  }));
+  const spreadLeftStyle = useAnimatedStyle(() => ({
+    transform: [{ translateX: -spread.value }],
+  }));
+  const spreadRightStyle = useAnimatedStyle(() => ({
+    transform: [{ translateX: spread.value }],
+  }));
+
+  if (type === "none") return null;
+
+  const customGlyph = renderHand ? renderHand({ size, color }) : null;
+
+  if (isSwipe) {
+    return (
+      <View
+        style={{ transform: [{ rotate: GLYPH_ROTATION[type] ?? "0deg" }] }}
+        pointerEvents="none"
+      >
+        <View style={styles.swipeStack}>
+          <Animated.View style={swipeAnimatedStyle} pointerEvents="none">
+            {customGlyph ?? <FingerPair size={size} color={color} />}
+          </Animated.View>
+          <MotionTrack size={size} color={color} />
+        </View>
+      </View>
+    );
+  }
+
+  if (isSpread) {
+    const w = size * 0.2;
+    const capsule = {
+      width: w,
+      height: size * 0.5,
+      borderRadius: w / 2,
+      backgroundColor: color,
+    };
+    return (
+      <View style={[styles.spreadRow, { gap: size * 0.12 }]} pointerEvents="none">
+        <Animated.View style={spreadLeftStyle}>
+          <View style={capsule} />
+        </Animated.View>
+        <Animated.View style={spreadRightStyle}>
+          <View style={capsule} />
+        </Animated.View>
+      </View>
+    );
+  }
+
+  // tap / double_tap — a minimal pulsing tap-target (ring + center dot).
+  const ringSize = size * 0.86;
+  const ringBorder = Math.max(2, size * 0.08);
+  const dotSize = size * 0.32;
+  return (
+    <View style={[styles.tapWrap, { width: size, height: size }]} pointerEvents="none">
+      {customGlyph ? (
+        <Animated.View style={tapAnimatedStyle} pointerEvents="none">
+          {customGlyph}
+        </Animated.View>
+      ) : (
+        <>
+          <Animated.View
+            style={[
+              styles.tapRing,
+              {
+                width: ringSize,
+                height: ringSize,
+                borderRadius: ringSize / 2,
+                borderWidth: ringBorder,
+                borderColor: color,
+              },
+              tapAnimatedStyle,
+            ]}
+            pointerEvents="none"
+          />
+          <View
+            style={{
+              position: "absolute",
+              width: dotSize,
+              height: dotSize,
+              borderRadius: dotSize / 2,
+              backgroundColor: color,
+            }}
+          />
+        </>
+      )}
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  swipeStack: {
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  spreadRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  tapWrap: {
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  tapRing: {
+    backgroundColor: "transparent",
+  },
+});
+
+export const GestureHint = React.memo(GestureHintComponent);
+GestureHint.displayName = "GestureHint";
+
+export default GestureHint;

package/src/coachmarks/SpotlightOverlay.tsx

@@ -0,0 +1,254 @@
+import { BlurView } from "expo-blur";
+import React, { useEffect, useMemo } from "react";
+import {
+  Pressable,
+  StyleSheet,
+  Text,
+  useWindowDimensions,
+  View,
+} from "react-native";
+import Animated, {
+  FadeIn,
+  FadeOut,
+  useAnimatedProps,
+  useAnimatedStyle,
+  useReducedMotion,
+  useSharedValue,
+  withRepeat,
+  withSequence,
+  withTiming,
+} from "react-native-reanimated";
+
+import { useOnboardingTheme } from "../theme/ThemeContext";
+import { GestureHint } from "./GestureHint";
+import type { GestureKind, Placement, TargetRect } from "./types";
+
+const AnimatedBlurView = Animated.createAnimatedComponent(BlurView);
+
+const BLUR_INTENSITY = 26;
+const FADE_MS = 280;
+/** Breathing room between the highlighted element and the glowing ring. */
+const RING_PADDING = 10;
+/** Gap between the ring and the tooltip pill. */
+const TOOLTIP_GAP = 14;
+const SIDE_MARGIN = 20;
+const PILL_MAX_WIDTH = 260;
+
+export interface SpotlightOverlayProps {
+  message: string;
+  /** Window-space rect of the element to highlight. Null → centered hint (e.g. a scroll gesture). */
+  targetRect?: TargetRect | null;
+  gesture?: GestureKind;
+  placement?: Placement;
+  /** Tapping the highlighted target or the pill — advance / act. */
+  onEngage: () => void;
+  /** Tapping the dimmed backdrop — advance to the next step (ends the tour only on the last step). */
+  onDismiss: () => void;
+  /** Ring + tooltip color. Defaults to the onboarding theme's `primary`. */
+  accentColor?: string;
+  /** Tooltip label color. Defaults to the theme's `onPrimary`. */
+  accentTextColor?: string;
+}
+
+/**
+ * A single coachmark step: the whole screen is frosted with an animated blur,
+ * and a bright pulsing ring + tooltip point at one measured target. Mounted at
+ * the app root (above the tab bar) via CoachmarkOverlayHost.
+ *
+ * Performance: one BlurView (mounted only while a step is visible), the ring
+ * glow is a single reanimated view, and all animation runs on the UI thread.
+ * Reduce Motion drops the pulse.
+ */
+const SpotlightOverlayComponent: React.FC<SpotlightOverlayProps> = ({
+  message,
+  targetRect,
+  gesture = "none",
+  placement = "bottom",
+  onEngage,
+  onDismiss,
+  accentColor,
+  accentTextColor,
+}) => {
+  const { height: screenH } = useWindowDimensions();
+  const reduced = useReducedMotion();
+  const theme = useOnboardingTheme();
+
+  const accent = accentColor ?? theme.colors.primary;
+  const accentText = accentTextColor ?? theme.colors.onPrimary;
+
+  // Tap / double-tap steps show ONLY the ring + tooltip — no gesture glyph. The
+  // pulsing highlight ring already reads as "tap here", so an extra glyph is
+  // noise. Every app inherits this centrally, with no config change.
+  const showGesture =
+    gesture !== "none" && gesture !== "tap" && gesture !== "double_tap";
+
+  const intensity = useSharedValue(0);
+  const ringScale = useSharedValue(1);
+
+  useEffect(() => {
+    intensity.value = withTiming(BLUR_INTENSITY, { duration: FADE_MS });
+  }, [intensity]);
+
+  useEffect(() => {
+    if (reduced) return;
+    ringScale.value = withRepeat(
+      withSequence(
+        withTiming(1.06, { duration: 700 }),
+        withTiming(1, { duration: 700 }),
+      ),
+      -1,
+      true,
+    );
+  }, [reduced, ringScale]);
+
+  const blurAnimatedProps = useAnimatedProps(() => ({
+    intensity: intensity.value,
+  }));
+
+  const ringAnimatedStyle = useAnimatedStyle(() => ({
+    transform: [{ scale: ringScale.value }],
+  }));
+
+  // Geometry for the ring + tooltip, derived from the measured target.
+  const geometry = useMemo(() => {
+    if (!targetRect) return null;
+    const ringLeft = targetRect.x - RING_PADDING;
+    const ringTop = targetRect.y - RING_PADDING;
+    const ringW = targetRect.width + RING_PADDING * 2;
+    const ringH = targetRect.height + RING_PADDING * 2;
+    return {
+      ring: {
+        left: ringLeft,
+        top: ringTop,
+        width: ringW,
+        height: ringH,
+        borderRadius: Math.min(ringW, ringH) / 2,
+      },
+      // Tooltip above or below the ring depending on placement.
+      tooltip:
+        placement === "top"
+          ? { bottom: screenH - ringTop + TOOLTIP_GAP }
+          : { top: ringTop + ringH + TOOLTIP_GAP },
+    };
+  }, [targetRect, placement, screenH]);
+
+  return (
+    <Animated.View
+      style={[StyleSheet.absoluteFill, styles.root]}
+      entering={FadeIn.duration(FADE_MS)}
+      exiting={FadeOut.duration(FADE_MS)}
+    >
+      <AnimatedBlurView
+        tint="dark"
+        animatedProps={blurAnimatedProps}
+        style={StyleSheet.absoluteFill}
+      />
+
+      {/* Tap-the-backdrop to move on (dismisses the tour on the last step). */}
+      <Pressable
+        style={StyleSheet.absoluteFill}
+        onPress={onDismiss}
+        accessibilityRole="button"
+        accessibilityLabel="Next hint"
+      />
+
+      {/* Glowing ring over the highlighted target (tap = engage). */}
+      {geometry && (
+        <Animated.View
+          style={[
+            styles.ring,
+            geometry.ring,
+            { borderColor: accent, shadowColor: accent },
+            ringAnimatedStyle,
+          ]}
+          pointerEvents="box-none"
+        >
+          <Pressable
+            style={StyleSheet.absoluteFill}
+            onPress={onEngage}
+            accessibilityRole="button"
+            accessibilityLabel={message}
+          />
+        </Animated.View>
+      )}
+
+      {/* Tooltip pill: anchored to the ring, or centered for a target-less hint. */}
+      <View
+        style={[
+          styles.tooltipWrapper,
+          geometry
+            ? geometry.tooltip
+            : { top: screenH * 0.42, alignItems: "center" },
+        ]}
+        pointerEvents="box-none"
+      >
+        {showGesture && (
+          <View style={styles.gestureSlot} pointerEvents="none">
+            <GestureHint type={gesture} color={accent} />
+          </View>
+        )}
+        <Pressable
+          onPress={onEngage}
+          style={[styles.pill, { backgroundColor: accent }]}
+          accessibilityRole="button"
+          accessibilityLabel={message}
+        >
+          <Text numberOfLines={3} style={[styles.pillText, { color: accentText }]}>
+            {message}
+          </Text>
+        </Pressable>
+      </View>
+    </Animated.View>
+  );
+};
+
+const styles = StyleSheet.create({
+  // High elevation/zIndex so the whole overlay (incl. the frosted blur) sits
+  // above the bottom tab bar on Android, where sibling z-order follows
+  // elevation, not tree order.
+  root: {
+    zIndex: 9999,
+    elevation: 9999,
+  },
+  ring: {
+    position: "absolute",
+    borderWidth: 2.5,
+    backgroundColor: "transparent",
+    shadowOffset: { width: 0, height: 0 },
+    shadowOpacity: 0.9,
+    shadowRadius: 12,
+    elevation: 10,
+  },
+  tooltipWrapper: {
+    position: "absolute",
+    left: SIDE_MARGIN,
+    right: SIDE_MARGIN,
+    alignItems: "center",
+    gap: 10,
+  },
+  gestureSlot: {
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  pill: {
+    maxWidth: PILL_MAX_WIDTH,
+    paddingVertical: 12,
+    paddingHorizontal: 18,
+    borderRadius: 18,
+    shadowColor: "#000",
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.25,
+    shadowRadius: 6,
+    elevation: 6,
+  },
+  pillText: {
+    fontSize: 14,
+    fontWeight: "800",
+    textAlign: "center",
+  },
+});
+
+export const SpotlightOverlay = React.memo(SpotlightOverlayComponent);
+SpotlightOverlay.displayName = "SpotlightOverlay";
+
+export default SpotlightOverlay;