@wireai/activation 0.14.1 → 0.14.3

package/src/coachmarks/SpotlightOverlay.tsx

@@ -1,4 +1,3 @@
-import { BlurView } from "expo-blur";
 import React, { useEffect, useMemo } from "react";
 import {
   Pressable,
@@ -7,7 +6,12 @@ import {
   useWindowDimensions,
   View,
 } from "react-native";
-import Animated, {
+
+import { useOnboardingTheme } from "../theme/ThemeContext";
+import { resolveBlurView } from "./expoBlur";
+import { GestureHint } from "./GestureHint";
+import {
+  Animated,
   FadeIn,
   FadeOut,
   useAnimatedProps,
@@ -17,14 +21,9 @@ import Animated, {
   withRepeat,
   withSequence,
   withTiming,
-} from "react-native-reanimated";
-
-import { useOnboardingTheme } from "../theme/ThemeContext";
-import { GestureHint } from "./GestureHint";
+} from "./reanimated";
 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 +50,25 @@ 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.
+ * glow is a single animated view, and with `react-native-reanimated` installed
+ * every animation runs on the UI thread. Reduce Motion drops the pulse.
+ *
+ * BOTH native peers are OPTIONAL, and each is resolved through a guarded lazy
+ * require, so the subpath never carries a static top-level import of either:
+ *   • `expo-blur` (`expoBlur.ts`) — absent, the frost drops to an equivalent
+ *     dimmed scrim. The animated component is built once, on first use.
+ *   • `react-native-reanimated` (`reanimated.ts`) — absent, the overlay renders
+ *     STATICALLY at its resting frame: the ring sits at scale 1 (no pulse), the
+ *     blur at full BLUR_INTENSITY (no fade-in), and the whole overlay appears
+ *     and leaves without the fade. Nothing moves; everything renders.
+ * A missing decoration must never blank a tour, so the ring, tooltip, copy and
+ * gestures are identical in all four combinations.
  */
 const SpotlightOverlayComponent: React.FC<SpotlightOverlayProps> = ({
   message,
@@ -76,6 +87,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 +157,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 +238,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;
+  }
+};

package/src/coachmarks/index.ts

@@ -2,8 +2,13 @@
  * @wireai/activation/coachmarks — the performance-first guided-tour engine.
  *
  * Subpath entry, kept OUT of the main barrel so the core kit stays dependency-
- * free: importing this pulls in the optional peers `react-native-reanimated` and
- * `expo-blur`. The app declares WHERE things anchor (useCoachmarkAnchor) and
+ * free. Importing this pulls in NO native peer: `react-native-reanimated` and
+ * `expo-blur` are both OPTIONAL and both reached through guarded lazy requires
+ * (`reanimated.ts`, `expoBlur.ts`). Installed, you get UI-thread animation and a
+ * frosted spotlight; absent, the tour still renders — statically, and with a
+ * plain dimmed scrim instead of the frost. (This doc used to say the subpath
+ * "pulls in" both peers, which was true until 0.14.2 / 0.14.3 removed the static
+ * imports.) The app declares WHERE things anchor (useCoachmarkAnchor) and
  * WHICH tour plays (useCoachmarkTour); the kit owns the animation, measuring,
  * blur, ring, gesture hand, and one-overlay-at-a-time queue.
  *

package/src/coachmarks/reanimated.ts

@@ -0,0 +1,342 @@
+/**
+ * reanimated — resolve `react-native-reanimated`, lazily and optionally.
+ *
+ * ── WHY THIS DOES NOT BREAK THE NO-NATIVE-DEPENDENCY POLICY ──────────────────────────────
+ *
+ * `react-native-reanimated` is an OPTIONAL peer of the coachmarks subpath. `SpotlightOverlay` and
+ * `GestureHint` animate with it WHEN it is installed, and fall back to a STATIC render of the same
+ * visual when it is not — same ring, same tooltip, same glyph, same copy, same gestures, just
+ * without motion. So a host that never installs it can still run the guided tour and the feature
+ * showcase, and an Expo Go / Lite build is not forced into a native module it cannot take.
+ *
+ * Before this file, both components did `import Animated, { … } from "react-native-reanimated"` at
+ * module scope, and `coachmarks/index.ts` re-exports them 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. `@wireai/activation/showcase` inherited the
+ * same edge through `GestureHint`. This resolver removes it. Same class as the 0.14.2 `expo-blur`
+ * fix (`expoBlur.ts`), same shape, one size up.
+ *
+ * ── THE SPECIFIER MUST BE A STRING LITERAL, INSIDE A TRY/CATCH ───────────────────────────
+ *
+ * This follows `icons/expoIcons.ts` and `coachmarks/expoBlur.ts` exactly, and expoIcons' 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 literally a string — an
+ * aliased callee (`const req = require; req(name)`) or a variable specifier is collected NOWHERE,
+ * so the module never enters the bundle (that shape shipped broken in 0.8.0). And the call sitting
+ * inside a TRY/CATCH is literally how Metro marks the dependency `isOptional`, which is what lets
+ * an absent peer degrade instead of failing the build. Do NOT "simplify" either half away.
+ *
+ * ── WHY THE EXPORTS ARE BARE FUNCTIONS WITH THE PEER'S OWN NAMES ─────────────────────────
+ *
+ * The call sites import `useAnimatedStyle` / `useAnimatedProps` / `withTiming` … from HERE instead
+ * of from the peer, and call them unqualified, exactly as before. That is load-bearing, not style:
+ * reanimated's Babel plugin decides what to workletize by the CALLEE NAME (`react-native-worklets`
+ * `plugin/index.js` → `reanimatedFunctionHooks` / `reanimatedFunctionArgsToWorkletize`; it reads
+ * `callee.name`, or `callee.property.name` for a member call, and never checks which module the
+ * name came from). Keeping the names identical keeps every worklet in `SpotlightOverlay` and
+ * `GestureHint` workletized byte-for-byte on a host that HAS the peer. Rename them and the
+ * animations silently stop running on the UI thread.
+ *
+ * ── THE DEGRADE: THE FINAL FRAME, NOT A DEAD ONE ─────────────────────────────────────────
+ *
+ * The shim resolves every animation to its RESTING value — `withTiming(to)` is `to`,
+ * `withSequence(a, b)` is `b`, `withRepeat(x)` is `x` — so a component lands on the pose it would
+ * have settled into anyway (ring at scale 1, glyph at full opacity, blur at BLUR_INTENSITY) rather
+ * than on frame zero, which for the blur would have meant a fully transparent overlay. Shared
+ * values are state-backed so a write from an effect actually reaches the next render; reanimated's
+ * own values do not need this because they drive the UI thread directly. The kit's own
+ * AccessibilityInfo-backed `useReducedMotion` stands in for the peer's, so the reduce-motion
+ * contract in ai_rules/rules/performance.md §3 holds with or without the peer.
+ *
+ * This is also what `ai_rules/rules/frequent_rules.md` #1 prescribes: when the kit needs motion
+ * without the optional peer, it uses core React Native, never Reanimated.
+ */
+import {
+  createElement,
+  forwardRef,
+  useReducer,
+  useRef,
+  type ComponentType,
+  type ReactNode,
+} from "react";
+import { View, type ViewProps, type ViewStyle } from "react-native";
+
+import { useReducedMotion as useOsReducedMotion } from "../motion/useReducedMotion";
+
+// 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;
+
+/** A reanimated shared value, narrowed to the one member the kit uses. */
+export interface SharedValue<T> {
+  value: T;
+}
+
+/** Props `Animated.View` accepts on top of a plain View (layout-animation descriptors). */
+export interface AnimatedViewProps extends ViewProps {
+  entering?: unknown;
+  exiting?: unknown;
+  children?: ReactNode;
+}
+
+/** A component built by `createAnimatedComponent`: its own props plus reanimated's driven props. */
+export type AnimatedComponent<P> = ComponentType<P & { animatedProps?: object }>;
+
+/** The slice of reanimated the coachmark surfaces actually use. */
+export interface ReanimatedApi {
+  /** True when the real peer resolved; false when this is the static fallback. */
+  present: boolean;
+  View: ComponentType<AnimatedViewProps>;
+  createAnimatedComponent: <P extends object>(component: ComponentType<P>) => AnimatedComponent<P>;
+  useSharedValue: <T>(initial: T) => SharedValue<T>;
+  useAnimatedStyle: (factory: () => ViewStyle) => ViewStyle;
+  useAnimatedProps: <P extends object>(factory: () => P) => P;
+  useReducedMotion: () => boolean;
+  withTiming: (toValue: number, config?: object) => number;
+  withRepeat: (animation: number, count?: number, reverse?: boolean) => number;
+  withSequence: (...animations: number[]) => number;
+  withDelay: (ms: number, animation: number) => number;
+  /** The `entering` / `exiting` descriptors, or undefined when the peer is absent. */
+  fadeIn: (durationMs: number) => unknown;
+  fadeOut: (durationMs: number) => 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 !== "react-native-reanimated") return undefined;
+  if (typeof require !== "function") return undefined;
+  try {
+    return require("react-native-reanimated");
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * TEST-ONLY seam. `SpotlightOverlay` / `GestureHint` have frozen public props, so neither can take
+ * a `requireModule` the way `WireIcon` does — this lets a component render exercise the PRESENT
+ * path. Production never sets it; `runtimeRequire` is the only resolver.
+ */
+let testRequire: OptionalRequire | undefined;
+export const __setReanimatedRequireForTests = (fn: OptionalRequire | undefined): void => {
+  testRequire = fn;
+  cached = undefined;
+};
+
+// ── the static fallback ───────────────────────────────────────────────────────
+
+/**
+ * A shared value that re-renders its owner on write. Reanimated's own value drives the UI thread
+ * and deliberately does NOT re-render; here the render IS the only output, so a value written from
+ * an effect (`intensity.value = withTiming(26)`) has to reach it or the overlay would sit on frame
+ * zero forever — a fully transparent blur. The box identity is stable for the component's lifetime,
+ * exactly like the real one, so it stays safe in a dependency list.
+ */
+const useStaticSharedValue = <T,>(initial: T): SharedValue<T> => {
+  const [, bump] = useReducer((n: number): number => n + 1, 0);
+  const box = useRef<SharedValue<T> | null>(null);
+  if (box.current === null) {
+    let current = initial;
+    box.current = {
+      get value(): T {
+        return current;
+      },
+      set value(next: T) {
+        if (Object.is(next, current)) return;
+        current = next;
+        bump();
+      },
+    };
+  }
+  return box.current;
+};
+
+/** Run a worklet body on the JS side. It must never throw into the render — degrade, don't crash. */
+const runWorklet = <R extends object>(factory: () => R, fallback: R): R => {
+  try {
+    return factory() ?? fallback;
+  } catch {
+    return fallback;
+  }
+};
+
+/** `Animated.View` without the peer: a plain View, with the layout-animation props dropped. */
+const StaticAnimatedView = forwardRef<View, AnimatedViewProps>(function StaticAnimatedView(
+  { entering: _entering, exiting: _exiting, children, ...rest },
+  ref,
+) {
+  return createElement(View, { ...rest, ref }, children);
+});
+
+/**
+ * `createAnimatedComponent` without the peer. The wrapper MERGES `animatedProps` into the real
+ * props, because that object is the only carrier for values the worklet would have driven (the
+ * spotlight's blur `intensity`). Built once per wrapped component at the call site's `useMemo`, so
+ * the returned type identity is stable and React never remounts the subtree.
+ */
+const staticCreateAnimatedComponent = <P extends object>(
+  component: ComponentType<P>,
+): AnimatedComponent<P> =>
+  function StaticAnimatedComponent({ animatedProps, ...rest }) {
+    return createElement(component, { ...(rest as P), ...(animatedProps as object) });
+  };
+
+/**
+ * The peer-absent API. Every animation resolves to its RESTING value, so components render the
+ * frame they would have settled on. Nothing here schedules work, allocates a native module, or
+ * throws.
+ */
+const staticApi: ReanimatedApi = {
+  present: false,
+  View: StaticAnimatedView,
+  createAnimatedComponent: staticCreateAnimatedComponent,
+  useSharedValue: useStaticSharedValue,
+  useAnimatedStyle: (factory) => runWorklet(factory, {}),
+  useAnimatedProps: (factory) => runWorklet(factory, {} as never),
+  useReducedMotion: useOsReducedMotion,
+  withTiming: (toValue) => toValue,
+  withRepeat: (animation) => animation,
+  withSequence: (...animations) => animations[animations.length - 1] ?? 0,
+  withDelay: (_ms, animation) => animation,
+  fadeIn: () => undefined,
+  fadeOut: () => undefined,
+};
+
+// ── the real peer ─────────────────────────────────────────────────────────────
+
+const isFunction = (value: unknown): boolean => typeof value === "function";
+
+/** A React component is a function, or an object carrying `$$typeof` (memo / forwardRef). */
+const isComponent = (value: unknown): boolean =>
+  typeof value === "function" || (!!value && typeof value === "object" && "$$typeof" in value);
+
+/**
+ * Build the API from a resolved module namespace, or undefined when it is not the module we expect.
+ *
+ * The hooks are NAMED exports; `View` and `createAnimatedComponent` live on the DEFAULT export (the
+ * `Animated` object). A CJS interop wrapper puts everything one level down under `default`, so both
+ * are looked up on the namespace first and the default second. EVERY member is verified before the
+ * namespace is accepted: a partial module must degrade to the static fallback, never crash halfway
+ * through a render.
+ */
+const fromModule = (mod: unknown): ReanimatedApi | undefined => {
+  if (!mod || typeof mod !== "object") return undefined;
+  const ns = mod as Record<string, unknown>;
+  const def =
+    ns.default && typeof ns.default === "object"
+      ? (ns.default as Record<string, unknown>)
+      : undefined;
+  const pick = (name: string): unknown => ns[name] ?? def?.[name];
+
+  const view = def?.View ?? ns.View;
+  const createAnimated = def?.createAnimatedComponent ?? ns.createAnimatedComponent;
+  const hooks = {
+    useSharedValue: pick("useSharedValue"),
+    useAnimatedStyle: pick("useAnimatedStyle"),
+    useAnimatedProps: pick("useAnimatedProps"),
+    useReducedMotion: pick("useReducedMotion"),
+    withTiming: pick("withTiming"),
+    withRepeat: pick("withRepeat"),
+    withSequence: pick("withSequence"),
+    withDelay: pick("withDelay"),
+  };
+  const fadeIn = pick("FadeIn");
+  const fadeOut = pick("FadeOut");
+
+  if (!isComponent(view) || !isFunction(createAnimated)) return undefined;
+  if (Object.values(hooks).some((member) => !isFunction(member))) return undefined;
+  if (!fadeIn || !fadeOut) return undefined;
+
+  // The single narrowing seam. Everything above proved the members exist and are callable; the peer
+  // is untyped here (it is resolved through `unknown`), so the cast happens once, at the boundary,
+  // and the exported signatures above are the contract from here on.
+  const api = {
+    present: true,
+    View: view,
+    createAnimatedComponent: createAnimated,
+    ...hooks,
+    fadeIn: (durationMs: number) => (fadeIn as { duration: (ms: number) => unknown }).duration(durationMs),
+    fadeOut: (durationMs: number) => (fadeOut as { duration: (ms: number) => unknown }).duration(durationMs),
+  } as unknown as ReanimatedApi;
+  return api;
+};
+
+/**
+ * Module-level memo. Holds the RESOLVED api (real or static), so an absent peer costs exactly one
+ * failed require per process, not one per mount — and, more importantly, so the implementation can
+ * never change between two renders of the same component, which would break the rules of hooks.
+ */
+let cached: ReanimatedApi | undefined;
+
+/** Reset the memo. TEST-ONLY seam — production never calls it. */
+export const resetReanimatedModuleCache = (): void => {
+  cached = undefined;
+};
+
+/**
+ * Resolve the reanimated API, or the static fallback when the peer is absent/unresolvable.
+ * Never throws and never returns undefined: an absent animation library must degrade to a still
+ * frame, never break the tour.
+ */
+export const resolveReanimated = (
+  requireModule: OptionalRequire = testRequire ?? runtimeRequire,
+): ReanimatedApi => {
+  try {
+    if (cached === undefined || requireModule !== runtimeRequire) {
+      const resolved = fromModule(requireModule("react-native-reanimated")) ?? staticApi;
+      // Don't poison the module memo from an injected test require.
+      if (requireModule === runtimeRequire) cached = resolved;
+      return resolved;
+    }
+    return cached;
+  } catch {
+    return staticApi;
+  }
+};
+
+// ── the call-site surface: the peer's own names, resolved lazily ──────────────
+//
+// Each one delegates on every call, so nothing is resolved at import time. `api()` is memoized, so
+// the delegation is a property read.
+
+const api = (): ReanimatedApi => resolveReanimated();
+
+/**
+ * The `Animated` namespace, with `View` behind a getter so merely importing this module never
+ * touches the peer. The component identity it returns is stable (the peer's own `Animated.View`, or
+ * the module-level `StaticAnimatedView`), so React never remounts the tree under it.
+ */
+export const Animated: {
+  readonly View: ComponentType<AnimatedViewProps>;
+  createAnimatedComponent: <P extends object>(component: ComponentType<P>) => AnimatedComponent<P>;
+} = {
+  get View() {
+    return api().View;
+  },
+  createAnimatedComponent: (component) => api().createAnimatedComponent(component),
+};
+
+/** Layout-animation descriptors. `.duration()` is the only builder the kit uses. */
+export const FadeIn = { duration: (durationMs: number): unknown => api().fadeIn(durationMs) };
+export const FadeOut = { duration: (durationMs: number): unknown => api().fadeOut(durationMs) };
+
+export const useSharedValue = <T,>(initial: T): SharedValue<T> => api().useSharedValue(initial);
+export const useAnimatedStyle = (factory: () => ViewStyle): ViewStyle =>
+  api().useAnimatedStyle(factory);
+export const useAnimatedProps = <P extends object>(factory: () => P): P =>
+  api().useAnimatedProps(factory);
+export const useReducedMotion = (): boolean => api().useReducedMotion();
+export const withTiming = (toValue: number, config?: object): number =>
+  api().withTiming(toValue, config);
+export const withRepeat = (animation: number, count?: number, reverse?: boolean): number =>
+  api().withRepeat(animation, count, reverse);
+export const withSequence = (...animations: number[]): number => api().withSequence(...animations);
+export const withDelay = (ms: number, animation: number): number => api().withDelay(ms, animation);