@wireai/activation 0.14.2 → 0.14.3

package/src/coachmarks/SpotlightOverlay.tsx

@@ -6,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,
@@ -16,11 +21,7 @@ import Animated, {
   withRepeat,
   withSequence,
   withTiming,
-} from "react-native-reanimated";
-
-import { useOnboardingTheme } from "../theme/ThemeContext";
-import { resolveBlurView } from "./expoBlur";
-import { GestureHint } from "./GestureHint";
+} from "./reanimated";
 import type { GestureKind, Placement, TargetRect } from "./types";
 
 const BLUR_INTENSITY = 26;
@@ -55,14 +56,19 @@ export interface SpotlightOverlayProps {
  * 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.
  *
- * `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.
+ * 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,

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);

package/src/showcase/FeatureShowcase.tsx

@@ -1,8 +1,8 @@
-import Onboarding, {
-  type OnboardingColors,
-  type OnboardingFonts,
-  type OnboardingProps,
-  type OnboardingStep,
+import type {
+  OnboardingColors,
+  OnboardingFonts,
+  OnboardingProps,
+  OnboardingStep,
 } from "@blazejkustra/react-native-onboarding";
 import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { type ImageSourcePropType, StyleSheet, View } from "react-native";
@@ -12,6 +12,7 @@ import { hasSeenGate, markSeenGate, showcaseGateKey } from "../coachmarks/runtim
 import { useResolvedFeatures } from "../features/WireFeaturesProvider";
 import { useOnboardingTheme } from "../theme/ThemeContext";
 import type { OnboardingTheme } from "../theme/types";
+import { resolveShowcaseOnboarding } from "./blazejOnboarding";
 import { showcaseColorsFromTheme, showcasePanelBackground } from "./showcaseColors";
 import type { FeatureShowcaseProps } from "./types";
 
@@ -47,6 +48,13 @@ const mergeThemeOver = (
  *
  * When the gate says "seen", it renders nothing and calls `onDone` from an
  * effect (never during render).
+ *
+ * The underlying package is an OPTIONAL peer, resolved through the guarded lazy
+ * require in `blazejOnboarding.ts` rather than a static import, so the showcase
+ * subpath builds on a host that never installed it. Absent, this takes the SAME
+ * path as the kill switch — render null, call `onDone`, write no gate — so the
+ * host's flow always advances and the showcase still plays once if the peer is
+ * added later.
  */
 const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
   config,
@@ -71,14 +79,20 @@ const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
   const flags = useResolvedFeatures({ flags: features, config: featuresConfig });
   const disabled = !flags.showcase.enabled;
 
+  // The optional pager peer. Resolved once, on first render, instead of at module scope — so
+  // merely importing this file (and thus the showcase subpath) never needs it. Absent → treated
+  // exactly like the kill switch below: no render, no gate write, `onDone` from the effect.
+  const Onboarding = useMemo(() => resolveShowcaseOnboarding(), []);
+
   const gateKey = showcaseGateKey(config.id);
   const seen = useMemo(
     () => hasSeenGate(gateKey, storage, isTesting),
     [gateKey, storage, isTesting],
   );
-  // Either already-seen OR feature-disabled short-circuits the showcase. Only the seen path is a
-  // gate write (in `finish`); the disabled path never persists, so it replays when re-enabled.
-  const skip = seen || disabled;
+  // Already-seen, feature-disabled OR the peer missing short-circuits the showcase. Only the seen
+  // path is a gate write (in `finish`); the other two never persist, so the showcase replays once
+  // the feature is re-enabled or the peer is installed.
+  const skip = seen || disabled || !Onboarding;
 
   const doneRef = useRef(false);
   const finish = useCallback(() => {
@@ -177,7 +191,9 @@ const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
     [t],
   );
 
-  if (skip) return null;
+  // `!Onboarding` is already folded into `skip`; it is repeated here so the narrowing is explicit
+  // to the reader and to the compiler at the JSX below.
+  if (skip || !Onboarding) return null;
 
   const activeGesture = config.slides[activeIndex]?.gesture;
   // Same rule as the coachmark path: tap / double-tap slides show no glyph.

package/src/showcase/blazejOnboarding.ts

@@ -0,0 +1,136 @@
+/**
+ * blazejOnboarding — resolve `@blazejkustra/react-native-onboarding`, lazily and optionally.
+ *
+ * ── WHY THIS DOES NOT BREAK THE NO-NATIVE-DEPENDENCY POLICY ──────────────────────────────
+ *
+ * `@blazejkustra/react-native-onboarding` is an OPTIONAL peer of the showcase subpath — it is the
+ * slide pager `FeatureShowcase` wraps. Before this file, `FeatureShowcase.tsx` imported its default
+ * export at module scope, and `showcase/index.ts` re-exports the component with no wildcard escape,
+ * so importing ANYTHING from `@wireai/activation/showcase` (even `selectShowcaseSlides`) dragged
+ * the peer in, and a host that skipped the "optional" peer hit a Metro resolution failure. This
+ * resolver removes that static edge. Same class and same shape as the 0.14.2 `expo-blur` fix
+ * (`coachmarks/expoBlur.ts`), whose header carries the reasoning in full.
+ *
+ * The TYPES stay statically imported on purpose: a type-only import is erased by every toolchain
+ * (babel, esbuild and sucrase all drop it), so it creates no runtime edge and no bundle dependency,
+ * and `showcaseColors.ts` already relies on exactly that.
+ *
+ * ── THE SPECIFIER MUST BE A STRING LITERAL, INSIDE A TRY/CATCH ───────────────────────────
+ *
+ * Metro collects dependencies statically and matches only a call whose callee is literally the
+ * identifier `require` and whose argument is literally a string; the try/catch around it is what
+ * marks the dependency `isOptional`. Both halves are load-bearing — see `icons/expoIcons.ts` for
+ * the full autopsy of the 0.8.0 shape that aliased the callee and was collected nowhere.
+ *
+ * ── THE DEGRADE ─────────────────────────────────────────────────────────────────────────
+ *
+ * Absent → `FeatureShowcase` renders null and calls `onDone` from an effect, which is the SAME path
+ * the feature kill switch already takes. The host's flow always advances (a showcase that cannot
+ * render must never strand the user on a blank screen), and the seen-gate is deliberately NOT
+ * written, so installing the peer later still plays the showcase once.
+ */
+import type { ComponentType } from "react";
+
+import type { OnboardingProps } from "@blazejkustra/react-native-onboarding";
+
+// 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 pager component `FeatureShowcase` wraps. */
+export type OnboardingComponent = ComponentType<OnboardingProps>;
+
+const MODULE_NAME = "@blazejkustra/react-native-onboarding";
+
+/**
+ * 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 !== MODULE_NAME) return undefined;
+  if (typeof require !== "function") return undefined;
+  try {
+    return require("@blazejkustra/react-native-onboarding");
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * TEST-ONLY seam. `FeatureShowcase`'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 peer
+ * installed. Production never sets it; `runtimeRequire` is the only resolver.
+ */
+let testRequire: OptionalRequire | undefined;
+export const __setShowcaseOnboardingRequireForTests = (fn: OptionalRequire | undefined): void => {
+  testRequire = fn;
+  cached = undefined;
+};
+
+/**
+ * Read the component off the module. The package ships it as a DEFAULT export; a CJS build may put
+ * the component directly on `module.exports` instead, so both shapes are accepted.
+ */
+const interop = (mod: unknown): unknown => {
+  if (typeof mod === "function") return mod;
+  if (!mod || typeof mod !== "object") return undefined;
+  const ns = mod as Record<string, unknown>;
+  if (ns.default) return ns.default;
+  // `module.exports = forwardRef(...)`: the component IS the namespace, and it is an object rather
+  // than a function, so it would slip past the check above.
+  if ("$$typeof" in ns) return ns;
+  return undefined;
+};
+
+/**
+ * Narrow an unknown export to something mountable: a real component (function or class) or a
+ * React.memo / forwardRef wrapper (an object carrying `$$typeof`). Reject anything else rather than
+ * handing the reconciler a non-component.
+ */
+const asComponent = (value: unknown): OnboardingComponent | undefined => {
+  if (typeof value === "function") return value as OnboardingComponent;
+  if (value && typeof value === "object" && "$$typeof" in (value as object)) {
+    return value as OnboardingComponent;
+  }
+  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 showcase mount.
+ */
+let cached: OnboardingComponent | null | undefined;
+
+/** Reset the memo. TEST-ONLY seam — production never calls it. */
+export const resetShowcaseOnboardingCache = (): void => {
+  cached = undefined;
+};
+
+/**
+ * Resolve the pager component, or undefined when the peer is absent/unresolvable. Never throws: an
+ * absent showcase must advance the host's flow, never break it.
+ *
+ * `requireModule` is injectable so tests can exercise BOTH the found and absent paths without
+ * installing the peer (same convention as `resolveBlurView` / `resolveIconFamily`).
+ */
+export const resolveShowcaseOnboarding = (
+  requireModule: OptionalRequire = testRequire ?? runtimeRequire,
+): OnboardingComponent | undefined => {
+  try {
+    if (cached === undefined || requireModule !== runtimeRequire) {
+      const component = asComponent(interop(requireModule(MODULE_NAME)));
+      // 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/showcase/index.ts

@@ -2,10 +2,14 @@
  * @wireai/activation/showcase — the pre-onboarding feature showcase ("app intro").
  *
  * Subpath entry, kept OUT of the main barrel so the core kit stays dependency-
- * free: importing this pulls in the optional peer
- * `@blazejkustra/react-native-onboarding` (and, transitively via GestureHint,
- * `react-native-reanimated`). The app supplies a declarative ShowcaseConfig; the
- * kit bakes in the Wire theme + optional per-slide gesture hand and gates once.
+ * free. Importing this pulls in NO native peer (0.14.3): the pager
+ * `@blazejkustra/react-native-onboarding` is reached through the guarded lazy
+ * require in `blazejOnboarding.ts`, and the transitive edge through GestureHint
+ * to `react-native-reanimated` is guarded the same way in `coachmarks/reanimated.ts`.
+ * Without the pager the showcase renders null and calls `onDone` so the host's
+ * flow advances; without reanimated the gesture glyph renders static. The app
+ * supplies a declarative ShowcaseConfig; the kit bakes in the Wire theme +
+ * optional per-slide gesture hand and gates once.
  *
  *   import { FeatureShowcase, selectShowcaseSlides } from "@wireai/activation/showcase";
  */