@wireai/activation 0.14.1 → 0.14.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "private": false,
   "description": "Premium, fully-themable drop-in AI onboarding kit for React Native / Expo, on top of the open-source wireai-rn SDK.",
   "author": "Malik Chohra <malik@getwireai.com>",

package/src/coachmarks/SpotlightOverlay.tsx

@@ -1,4 +1,3 @@
-import { BlurView } from "expo-blur";
 import React, { useEffect, useMemo } from "react";
 import {
   Pressable,
@@ -20,11 +19,10 @@ import Animated, {
 } from "react-native-reanimated";
 
 import { useOnboardingTheme } from "../theme/ThemeContext";
+import { resolveBlurView } from "./expoBlur";
 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. */
@@ -51,13 +49,20 @@ export interface SpotlightOverlayProps {
 }
 
 /**
- * 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.
+ * A single coachmark step: the whole screen is frosted with an animated blur
+ * (or a plain dimmed scrim when the optional `expo-blur` peer is absent), 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.
+ *
+ * `expo-blur` is OPTIONAL. It is resolved through a guarded lazy require (see
+ * `expoBlur.ts`) and the animated component is built once on first use, so the
+ * subpath never carries a static top-level import of the peer. When it is not
+ * installed the frost drops to an equivalent dimmed scrim — a decorative frost
+ * missing must never blank a tour, so the ring, copy and gestures are unchanged.
  */
 const SpotlightOverlayComponent: React.FC<SpotlightOverlayProps> = ({
   message,
@@ -76,6 +81,14 @@ const SpotlightOverlayComponent: React.FC<SpotlightOverlayProps> = ({
   const accent = accentColor ?? theme.colors.primary;
   const accentText = accentTextColor ?? theme.colors.onPrimary;
 
+  // Resolve the optional `expo-blur` peer and build its animated component ONCE, on first render,
+  // instead of at module scope — so merely importing this file (and thus the coachmarks subpath)
+  // never needs the peer. `null` = the peer is absent → the scrim path renders instead.
+  const AnimatedBlurView = useMemo(() => {
+    const BlurView = resolveBlurView();
+    return BlurView ? Animated.createAnimatedComponent(BlurView) : null;
+  }, []);
+
   // 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.
@@ -138,11 +151,20 @@ const SpotlightOverlayComponent: React.FC<SpotlightOverlayProps> = ({
       entering={FadeIn.duration(FADE_MS)}
       exiting={FadeOut.duration(FADE_MS)}
     >
-      <AnimatedBlurView
-        tint="dark"
-        animatedProps={blurAnimatedProps}
-        style={StyleSheet.absoluteFill}
-      />
+      {AnimatedBlurView ? (
+        <AnimatedBlurView
+          tint="dark"
+          animatedProps={blurAnimatedProps}
+          style={StyleSheet.absoluteFill}
+        />
+      ) : (
+        // `expo-blur` absent → a plain dimmed scrim stands in for the frost. Same dark backdrop
+        // the tour reads against, so the ring, tooltip and gestures behave identically.
+        <Animated.View
+          style={[StyleSheet.absoluteFill, styles.scrim]}
+          pointerEvents="none"
+        />
+      )}
 
       {/* Tap-the-backdrop to move on (dismisses the tour on the last step). */}
       <Pressable
@@ -210,6 +232,11 @@ const styles = StyleSheet.create({
     zIndex: 9999,
     elevation: 9999,
   },
+  // Fallback backdrop when `expo-blur` is absent. A structural dim (not a brand token), tuned to
+  // read like the dark blur at BLUR_INTENSITY so the ring + tooltip keep the same contrast.
+  scrim: {
+    backgroundColor: "rgba(0, 0, 0, 0.55)",
+  },
   ring: {
     position: "absolute",
     borderWidth: 2.5,

package/src/coachmarks/expoBlur.ts

@@ -0,0 +1,135 @@
+/**
+ * expoBlur — resolve `expo-blur`'s `BlurView`, lazily and optionally.
+ *
+ * ── WHY THIS DOES NOT BREAK THE NO-NATIVE-DEPENDENCY POLICY ──────────────────────────────
+ *
+ * `expo-blur` is an OPTIONAL peer of the coachmarks subpath. The spotlight overlay frosts the
+ * screen with it WHEN it is installed, and degrades to a plain dimmed scrim when it is not — the
+ * ring, tooltip and gestures behave identically either way (see SpotlightOverlay). So a host that
+ * never installs `expo-blur` can still run the guided tour, and the free tier that must load under
+ * Expo Go is not forced into a native module it cannot take.
+ *
+ * Before this file, `SpotlightOverlay` did `import { BlurView } from "expo-blur"` at module scope,
+ * and `coachmarks/index.ts` re-exports the overlay with no wildcard escape — so importing ANYTHING
+ * from `@wireai/activation/coachmarks`, even `setCoachmarkStorage`, dragged the peer in and a host
+ * without it hit a Metro resolution failure. This resolver removes that static edge.
+ *
+ * ── THE SPECIFIER MUST BE A STRING LITERAL, INSIDE A TRY/CATCH ───────────────────────────
+ *
+ * This follows `icons/expoIcons.ts` exactly, and its header carries the full autopsy. In short:
+ *
+ *   • Metro collects dependencies STATICALLY, matching a call whose callee is literally the
+ *     identifier `require` and whose argument is a STRING LITERAL. A variable specifier
+ *     (`const req = require; req(name)`) is collected NOWHERE, so the module never enters the
+ *     bundle — and the aliased `require` is Metro's own numeric-id-keyed `metroRequire`, which can
+ *     never resolve a package-name string. That shape shipped broken once; do not restore it.
+ *   • The call sitting inside a TRY/CATCH is literally how Metro marks the dependency `isOptional`:
+ *     when the peer is absent Metro puts `null` in the dependencyMap and the require throws "Cannot
+ *     find module" straight into the catch below. Do NOT "simplify" the try/catch away — it is what
+ *     keeps the peer optional, not just tidy. (`withWireOnboarding` in metro/index.js adds a
+ *     stub-to-empty-module safety net for hosts that disable Metro's `allowOptionalDependencies`.)
+ */
+import type { ComponentType } from "react";
+
+// Metro injects a module-scoped `require`; it is ABSENT in a pure-ESM runtime (the kit's own
+// tests run under `node --test` as ESM). 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 literal require. */
+export type OptionalRequire = (moduleName: string) => unknown;
+
+/** The minimal prop shape the overlay uses from `expo-blur`'s `BlurView`. */
+export type BlurViewComponent = ComponentType<{
+  intensity?: number;
+  tint?: "light" | "dark" | "default";
+  style?: unknown;
+  children?: unknown;
+}>;
+
+/**
+ * The production resolver. The specifier is a LITERAL so Metro collects it (see the header); the
+ * `moduleName` parameter exists only to keep the `OptionalRequire` seam shape, so anything other
+ * than the one module this file owns resolves to undefined.
+ */
+const runtimeRequire: OptionalRequire = (moduleName) => {
+  if (moduleName !== "expo-blur") return undefined;
+  if (typeof require !== "function") return undefined;
+  try {
+    return require("expo-blur");
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * TEST-ONLY seam. `SpotlightOverlay`'s public props are frozen, so it cannot take a `requireModule`
+ * the way `WireIcon` does — this lets a component render exercise the PRESENT path without the
+ * native peer installed. Production never sets it; `runtimeRequire` is the only resolver.
+ */
+let testRequire: OptionalRequire | undefined;
+export const __setBlurRequireForTests = (fn: OptionalRequire | undefined): void => {
+  testRequire = fn;
+  cached = 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 ns = mod as Record<string, unknown>;
+  // `expo-blur` exposes `BlurView` as a NAMED export; prefer the namespace when it already carries
+  // it, and only fall back to `default` for a CJS-interop wrapper.
+  if (ns.BlurView) return ns;
+  const def = (mod as { default?: unknown }).default;
+  if (def && typeof def === "object") return def as Record<string, unknown>;
+  return ns;
+};
+
+/**
+ * Narrow an unknown export to something mountable. `BlurView` is a real React component (function
+ * or class across versions), and React.memo / forwardRef wrappers are objects carrying `$$typeof`.
+ * Reject anything else rather than handing the reconciler a non-component.
+ */
+const asComponent = (value: unknown): BlurViewComponent | undefined => {
+  if (typeof value === "function") return value as BlurViewComponent;
+  if (value && typeof value === "object" && "$$typeof" in (value as object)) {
+    return value as BlurViewComponent;
+  }
+  return undefined;
+};
+
+/**
+ * Module-level memo. `null` = "we looked and it is not there" (distinct from "not looked yet"),
+ * so an absent peer costs exactly one failed require per process, not one per overlay mount.
+ */
+let cached: BlurViewComponent | null | undefined;
+
+/** Reset the memo. TEST-ONLY seam — production never calls it. */
+export const resetBlurModuleCache = (): void => {
+  cached = undefined;
+};
+
+/**
+ * Resolve the `BlurView` component, or undefined when the peer is absent/unresolvable.
+ * Never throws: an absent blur must degrade to a plain scrim, never break the tour.
+ *
+ * `requireModule` is injectable so tests can exercise BOTH the found and absent paths without
+ * installing the native peer (same convention as `resolveIconFamily` / `detectAppVersion`).
+ */
+export const resolveBlurView = (
+  requireModule: OptionalRequire = testRequire ?? runtimeRequire,
+): BlurViewComponent | undefined => {
+  try {
+    if (cached === undefined || requireModule !== runtimeRequire) {
+      const resolved = interop(requireModule("expo-blur"));
+      const component = resolved ? asComponent(resolved.BlurView) : undefined;
+      // Don't poison the module memo from an injected test require.
+      if (requireModule === runtimeRequire) cached = component ?? null;
+      return component;
+    }
+    if (cached === null) return undefined;
+    return cached;
+  } catch {
+    return undefined;
+  }
+};