@oxyhq/bloom 0.68.0 → 0.69.0

package/src/connection-status/netinfo.ts

@@ -0,0 +1,131 @@
+/**
+ * The optional-peer boundary for `@react-native-community/netinfo`.
+ *
+ * netinfo is an OPTIONAL peer, and a static `import` contradicts that: an
+ * optional peer that is omitted does not degrade, it fails to RESOLVE, and Metro
+ * aborts the whole bundle with `Unable to resolve module
+ * @react-native-community/netinfo` — naming a package the app never mentions.
+ * Bloom's other optional-peer static imports are immune by accident (`expo-font`
+ * ships inside `expo`; `react-dom` is required by react-native-web), but netinfo
+ * arrives with nothing, so for this one the failure is real.
+ *
+ * Metro treats a `require()` of a STRING LITERAL inside a `try` block as an
+ * optional dependency: it resolves the real module when installed, and writes
+ * `null` into the dependency map when it is not, so the failure moves from build
+ * time to the `catch` below. Three constraints the shape has to respect, each
+ * checked against metro 0.83.5's own `collectDependencies`:
+ *
+ *   - The specifier must be STATICALLY EVALUABLE, and a literal is the only form
+ *     worth relying on. Metro rewrites a require it cannot evaluate — the
+ *     specifier arriving as a function parameter, say — into a thrower ("Dynamic
+ *     require defined at line N; not supported by Metro"), collecting no
+ *     dependency at all, so it resolves nothing whether or not the package is
+ *     installed. That is the defect that made Bloom's haptics, spinner and
+ *     native color scoping silently dead before it was swept out.
+ *   - The require must be a DIRECT statement of the try block.
+ *     `isOptionalDependency` walks up from the call and returns at the first
+ *     BlockStatement it meets, marking the dependency optional only if that
+ *     block belongs to a `try`. One `if`/`else` of nesting is enough to lose it,
+ *     and a non-optional dependency that cannot be resolved fails the BUILD —
+ *     precisely what this boundary exists to avoid. Hence the `typeof require`
+ *     guard below sits outside the try rather than inside it.
+ *   - `require` may not exist at all (this file also backs the `import`
+ *     condition, i.e. an ESM build under Node), hence that guard.
+ *
+ * The caller degrades to inert rather than throwing: an absent netinfo costs the
+ * outage toast and nothing else, and crashing an app root over a missing
+ * cosmetic affordance would be a worse trade than the build failure this
+ * replaces. The degradation is silent by construction — a connection toast that
+ * never appears looks exactly like a connection that never dropped — so
+ * {@link warnNetInfoUnavailable} names the missing package once, in dev.
+ */
+
+/**
+ * Declared locally rather than taken from the ambient `NodeRequire`, which
+ * returns `any`: `unknown` forces the module handle to be narrowed below instead
+ * of leaking an untyped value into the caller.
+ */
+declare const require: (moduleName: string) => unknown;
+
+/** The slice of netinfo's state this component reads. */
+export interface NetInfoStateLike {
+  isConnected: boolean | null;
+  isInternetReachable: boolean | null | undefined;
+}
+
+/**
+ * The slice of netinfo's module surface this component calls.
+ *
+ * Hand-written rather than `typeof import('@react-native-community/netinfo')` so
+ * no netinfo type reaches Bloom's emitted declarations — a consumer that skips
+ * the optional peer must not inherit a TS7016 from Bloom's own `.d.ts`. The two
+ * are kept in step by the assignability check in
+ * `__tests__/connection-status-netinfo.test.tsx`, which is excluded from the
+ * build and so may name the real package.
+ */
+export interface NetInfoLike {
+  addEventListener: (listener: (state: NetInfoStateLike) => void) => () => void;
+}
+
+/** `undefined` until the first load attempt, then the module or `null`. */
+let netInfoModule: NetInfoLike | null | undefined;
+/** Why the load failed, quoted verbatim in the dev warning. */
+let unavailableReason = '';
+let hasWarned = false;
+
+/** The netinfo module, or `null` when the optional peer is not installed. */
+export function loadNetInfo(): NetInfoLike | null {
+  if (netInfoModule !== undefined) return netInfoModule;
+  netInfoModule = null;
+
+  // The `typeof require` guard sits OUTSIDE the try on purpose — see the second
+  // constraint above. Nested one `if`/`else` deeper, the require is no longer a
+  // direct statement of the try block, Metro stops marking it optional, and an
+  // app without netinfo fails to BUILD instead of losing the outage toast.
+  if (typeof require === 'undefined') {
+    unavailableReason = 'this bundle has no CommonJS `require`';
+    return netInfoModule;
+  }
+
+  try {
+    // netinfo exposes `addEventListener` both as a named export and on its
+    // default export; which one comes back depends on whether the bundler
+    // resolved the CommonJS build or the ESM/source entry.
+    const loaded = require('@react-native-community/netinfo') as
+      | (Partial<NetInfoLike> & { default?: Partial<NetInfoLike> })
+      | null
+      | undefined;
+    const resolved = typeof loaded?.addEventListener === 'function' ? loaded : loaded?.default;
+
+    if (typeof resolved?.addEventListener === 'function') {
+      netInfoModule = resolved as NetInfoLike;
+    } else {
+      unavailableReason = 'the module resolved without an `addEventListener` export';
+    }
+  } catch (error) {
+    unavailableReason = error instanceof Error ? error.message : String(error);
+  }
+
+  return netInfoModule;
+}
+
+/**
+ * One warning per module lifetime, and none in production — the same mechanism
+ * as `toast/use-single-outlet-guard.ts`. Metro and Vite/Rolldown both fold the
+ * `NODE_ENV` check statically, so a production bundle keeps neither the branch
+ * nor the message.
+ */
+export function warnNetInfoUnavailable(): void {
+  if (process.env.NODE_ENV === 'production' || hasWarned) return;
+  hasWarned = true;
+  // Internal Bloom diagnostic: only the consumer's package.json can fix this,
+  // so it names the package, the install command and the alternative.
+  // eslint-disable-next-line no-console
+  console.warn(
+    '[Bloom] ConnectionStatusToasts is inert: the optional peer ' +
+      '`@react-native-community/netinfo` could not be loaded, so connection changes ' +
+      'are never observed and no offline / reconnecting / restored toast will ever ' +
+      'appear. Install it (`npx expo install @react-native-community/netinfo`) or ' +
+      `stop rendering <ConnectionStatusToasts>. Reason: ${unavailableReason}`,
+  );
+}

package/src/hooks/haptics-module.ts

@@ -0,0 +1,118 @@
+/**
+ * The optional-peer boundary for `expo-haptics`.
+ *
+ * The load has to be dynamic — an optional peer that is omitted does not
+ * degrade when it is imported statically, it fails to RESOLVE and Metro aborts
+ * the whole bundle naming a package the app never mentions. But it also has to
+ * be dynamic in the ONE shape Metro understands: a `require()` of a STRING
+ * LITERAL inside a `try` block, which Metro collects as an optional dependency
+ * (resolving the real module when installed, writing `null` into the dependency
+ * map when it is not, so the failure lands in the `catch` below at evaluation
+ * time instead of at build time).
+ *
+ * The shape this replaced — the deleted `utils/lazy-require.ts`, which took the
+ * specifier as a function PARAMETER — satisfied neither. Metro can only collect
+ * a dependency whose specifier it can evaluate statically; a parameter it
+ * cannot, so it collected nothing and rewrote the call into a thrower ("Dynamic
+ * require defined at line N; not supported by Metro"). From a consumer's
+ * `node_modules` that resolved NOTHING, installed or not: `expo-haptics` was
+ * never loaded on any device and every haptic in Bloom was a silent no-op. It
+ * only ever worked under jest, which is CommonJS with a real dynamic `require`.
+ *
+ * `require` may also not exist at all (this file backs the `import` condition
+ * too, i.e. an ESM build under Node), hence the `typeof` guard.
+ *
+ * A missing haptic is invisible — indistinguishable from a device with haptics
+ * turned off — so {@link warnHapticsUnavailable} names the package once, in dev.
+ *
+ * @see connection-status/netinfo.ts — the same boundary for netinfo.
+ */
+
+/**
+ * Declared locally rather than taken from the ambient `NodeRequire`, which
+ * returns `any`: `unknown` forces the module handle to be narrowed below instead
+ * of leaking an untyped value into the caller.
+ */
+declare const require: (moduleName: string) => unknown;
+
+/**
+ * The slice of expo-haptics' module surface this hook calls.
+ *
+ * Hand-written rather than `typeof import('expo-haptics')` so no expo-haptics
+ * type reaches Bloom's emitted declarations — a consumer that skips the optional
+ * peer must not inherit a TS7016 from Bloom's own `.d.ts`. The two are kept in
+ * step by the assignability check in `__tests__/useHaptics.test.tsx`, which is
+ * excluded from the build and so may name the real package.
+ *
+ * `impactAsync` is declared in METHOD syntax deliberately: `strictFunctionTypes`
+ * exempts method parameters from contravariance, which is what keeps the real
+ * `(style?: ImpactFeedbackStyle) => Promise<void>` assignable to a `string`
+ * parameter here. The widening cannot admit a bad value in practice — the only
+ * arguments passed are read straight back out of `ImpactFeedbackStyle`.
+ */
+export interface HapticsLike {
+  ImpactFeedbackStyle: Record<'Light' | 'Medium' | 'Heavy', string>;
+  impactAsync(style?: string): Promise<void>;
+}
+
+/** `undefined` until the first load attempt, then the module or `null`. */
+let hapticsModule: HapticsLike | null | undefined;
+/** Why the load failed, quoted verbatim in the dev warning. */
+let unavailableReason = '';
+let hasWarned = false;
+
+/** The expo-haptics module, or `null` when the optional peer is not installed. */
+export function loadHaptics(): HapticsLike | null {
+  if (hapticsModule !== undefined) return hapticsModule;
+  hapticsModule = null;
+
+  // The `typeof require` guard sits OUTSIDE the try on purpose. Metro's
+  // `isOptionalDependency` walks up from the require call and returns as soon as
+  // it meets a BlockStatement, marking the dependency optional only if THAT
+  // block is a try block — so a require nested one `if`/`else` deeper is
+  // resolved eagerly like any other import, and an app without the peer fails to
+  // BUILD. Keeping the require a direct statement of the try block is the whole
+  // difference between degrading and not building.
+  if (typeof require === 'undefined') {
+    unavailableReason = 'this bundle has no CommonJS `require`';
+    return hapticsModule;
+  }
+
+  try {
+    const loaded = require('expo-haptics') as Partial<HapticsLike> | null | undefined;
+
+    if (
+      typeof loaded?.impactAsync === 'function' &&
+      typeof loaded.ImpactFeedbackStyle?.Light === 'string'
+    ) {
+      hapticsModule = loaded as HapticsLike;
+    } else {
+      unavailableReason =
+        'the module resolved without an `impactAsync` / `ImpactFeedbackStyle` export';
+    }
+  } catch (error) {
+    unavailableReason = error instanceof Error ? error.message : String(error);
+  }
+
+  return hapticsModule;
+}
+
+/**
+ * One warning per module lifetime, and none in production — the same mechanism
+ * as `connection-status/netinfo.ts` and `toast/use-single-outlet-guard.ts`.
+ * Metro and Vite/Rolldown both fold the `NODE_ENV` check statically, so a
+ * production bundle keeps neither the branch nor the message.
+ */
+export function warnHapticsUnavailable(): void {
+  if (process.env.NODE_ENV === 'production' || hasWarned) return;
+  hasWarned = true;
+  // Internal Bloom diagnostic: only the consumer's package.json can fix this,
+  // so it names the package, the install command and the alternative.
+  // eslint-disable-next-line no-console
+  console.warn(
+    '[Bloom] useHaptics is inert: the optional peer `expo-haptics` could not be ' +
+      'loaded, so every haptic in Bloom is a silent no-op. Install it ' +
+      '(`npx expo install expo-haptics`) or disable haptics explicitly with ' +
+      `<BloomHapticsProvider enabled={false}>. Reason: ${unavailableReason}`,
+  );
+}

package/src/hooks/useHaptics.tsx

@@ -1,13 +1,7 @@
 import React, { createContext, useCallback, useContext, useMemo } from 'react';
 import { Platform } from 'react-native';
 
-import { lazyRequire } from '../utils/lazy-require';
-
-/**
- * Lazily loads `expo-haptics`, returning `null` when it is not installed. The
- * dependency is an optional peer, so calls degrade to a no-op when absent.
- */
-const getHapticsModule = lazyRequire<typeof import('expo-haptics')>('expo-haptics');
+import { loadHaptics, warnHapticsUnavailable } from './haptics-module';
 
 /** Impact strength requested by a caller. */
 export type HapticStrength = 'light' | 'medium' | 'heavy';
@@ -52,8 +46,11 @@ export function useHaptics(): (strength?: HapticStrength) => void {
     (strength: HapticStrength = 'light') => {
       if (!enabled || Platform.OS === 'web') return;
 
-      const haptics = getHapticsModule();
-      if (!haptics) return;
+      const haptics = loadHaptics();
+      if (!haptics) {
+        warnHapticsUnavailable();
+        return;
+      }
 
       const { ImpactFeedbackStyle } = haptics;
       let style = ImpactFeedbackStyle.Light;

package/src/loading/SpinnerIcon.tsx

@@ -1,5 +1,5 @@
 import React, { useEffect } from 'react';
-import { ActivityIndicator, type ViewStyle } from 'react-native';
+import { type ViewStyle } from 'react-native';
 import Animated, {
   Easing,
   useAnimatedStyle,
@@ -7,18 +7,7 @@ import Animated, {
   withRepeat,
   withTiming,
 } from 'react-native-reanimated';
-
-import { lazyRequire } from '../utils/lazy-require';
-
-// react-native-svg is loaded lazily so the loading module can fall back to
-// ActivityIndicator when the host app doesn't ship SVG support. Reanimated,
-// by contrast, MUST be statically imported: the worklets Babel plugin
-// performs build-time closure analysis (`__closure` metadata) that fails on
-// runtime requires, which would crash the UI thread with
-// "Tried to synchronously call a non-worklet function `addListener`".
-type SvgModuleType = typeof import('react-native-svg');
-
-const getSvgModule = lazyRequire<SvgModuleType>('react-native-svg');
+import Svg, { Rect } from 'react-native-svg';
 
 interface SpinnerIconProps {
   size?: number;
@@ -27,24 +16,24 @@ interface SpinnerIconProps {
   style?: ViewStyle;
 }
 
-type AnimatedSpinnerProps = Omit<SpinnerIconProps, 'className'> & {
-  className?: string;
-  svg: NonNullable<SvgModuleType>;
-};
-
 /**
- * Inner component that unconditionally calls Reanimated hooks.
- * Only rendered when react-native-svg is available.
+ * iOS-style SVG spinner with 8 rotating rectangles and an opacity gradient trail.
+ *
+ * `react-native-svg` and `react-native-reanimated` are both REQUIRED peers and
+ * both are imported statically. Reanimated in particular must never be loaded at
+ * runtime: the worklets Babel plugin performs build-time closure analysis
+ * (`__closure` metadata) that fails on a runtime require, which crashes the UI
+ * thread with "Tried to synchronously call a non-worklet function `addListener`".
+ *
+ * Native only — `SpinnerIcon.web.tsx` draws the same shape with CSS, so this
+ * file is never reached by a web bundler.
  */
-const AnimatedSpinner: React.FC<AnimatedSpinnerProps> = ({
+export const SpinnerIcon: React.FC<SpinnerIconProps> = ({
   color = 'currentColor',
   size = 26,
   className,
   style,
-  svg,
 }) => {
-  const { default: Svg, Rect } = svg;
-
   const rotation = useSharedValue(0);
 
   useEffect(() => {
@@ -97,32 +86,4 @@ const AnimatedSpinner: React.FC<AnimatedSpinnerProps> = ({
   );
 };
 
-/**
- * iOS-style SVG spinner with 8 rotating rectangles and an opacity gradient trail.
- * Requires react-native-svg (lazy) and react-native-reanimated (static).
- * Falls back to ActivityIndicator if react-native-svg is missing.
- */
-export const SpinnerIcon: React.FC<SpinnerIconProps> = ({
-  color = 'currentColor',
-  size = 26,
-  className,
-  style,
-}) => {
-  const svg = getSvgModule();
-
-  if (!svg) {
-    return <ActivityIndicator size={size > 30 ? 'large' : 'small'} color={color} />;
-  }
-
-  return (
-    <AnimatedSpinner
-      color={color}
-      size={size}
-      className={className}
-      style={style}
-      svg={svg}
-    />
-  );
-};
-
 SpinnerIcon.displayName = 'SpinnerIcon';

package/src/loading/index.web.ts

@@ -1,8 +1,8 @@
 // Web variant of the `./loading` barrel.
 //
 // The default barrel (`./index.ts`) re-exports from `./Loading` and
-// `./SpinnerIcon`, which statically import `react-native-reanimated` (and lazily
-// `react-native-svg`). Reanimated has no web build — its worklets Babel plugin
+// `./SpinnerIcon`, which statically import `react-native-reanimated` and
+// `react-native-svg`. Reanimated has no web build — its worklets Babel plugin
 // is native-only and importing it statically breaks every web bundler (Vite,
 // webpack, Metro-web). The web forks (`./Loading.web`, `./SpinnerIcon.web`)
 // render the same components with CSS keyframes/transitions and no native deps.

package/src/theme/adaptive-colors.ts

@@ -1,13 +1,30 @@
 import { Platform } from 'react-native';
 import type { ThemeColors } from './types';
 
+/**
+ * `expo-router`'s `Color` proxy is read through a `require()` of a STRING
+ * LITERAL as a direct statement of a `try` block — the shape Metro collects as
+ * an optional dependency, resolving the real module when installed and writing
+ * `null` into the dependency map when it is not, so an app without the optional
+ * `expo-router` peer loses the adaptive palette and nothing else.
+ *
+ * The specifier was previously bound to a local `const` first. That still
+ * worked — Metro evaluates the constant — but the literal is what the rule can
+ * be stated and checked as, and it does not rest on a constant-folding pass
+ * every bundler happens to share. What must never come back is a specifier
+ * Metro CANNOT evaluate (a function parameter, a computed value): it collects no
+ * dependency and rewrites the call into a thrower, so it resolves nothing on any
+ * device.
+ *
+ * @see connection-status/netinfo.ts — the same boundary, with the full rule.
+ */
+
 const c = (v: unknown): string => v as string;
 
 function getAndroidColors(): ThemeColors | null {
   try {
     if (typeof require === 'undefined') return null;
-    const moduleName = 'expo-router';
-    const { Color } = require(moduleName);
+    const { Color } = require('expo-router');
     const d = Color.android.dynamic;
     return {
       background: c(d.surface),
@@ -52,8 +69,7 @@ function getAndroidColors(): ThemeColors | null {
 function getIOSColors(): ThemeColors | null {
   try {
     if (typeof require === 'undefined') return null;
-    const moduleName = 'expo-router';
-    const { Color } = require(moduleName);
+    const { Color } = require('expo-router');
     const i = Color.ios;
     return {
       background: c(i.systemBackground),

package/src/theme/color-scope/style-builder.ts

@@ -4,7 +4,49 @@ import { Platform, type StyleProp, type ViewStyle } from 'react-native';
 import { CANONICAL_TOKENS, getResolvedTokens } from '../token-registry';
 import type { AppColorName } from '../color-presets';
 import type { ExplicitAccents } from '../preset-vars';
-import { lazyRequire } from '../../utils/lazy-require';
+
+/**
+ * The optional-peer boundary for `nativewind`.
+ *
+ * The consumer's OWN nativewind has to be the one that answers: its version
+ * decides which var mechanism exists (`VariableContextProvider` under
+ * NativeWind 5 / react-native-css@3, `vars()` before it), and a scope built
+ * against a second copy would publish into a context nothing reads. That rules
+ * out reaching for Bloom's own `react-native-css` dependency, and an optional
+ * peer rules out a static import — Metro resolves those eagerly, so an app
+ * without nativewind would fail to BUILD rather than degrade.
+ *
+ * What is left is the one dynamic shape Metro understands: `require()` of a
+ * STRING LITERAL as a DIRECT statement of a `try` block, collected as an
+ * optional dependency. Both halves matter, and both were verified against metro
+ * 0.83.5's own `collectDependencies`:
+ *
+ *   - The shape this replaced — the deleted `utils/lazy-require.ts`, which took
+ *     the specifier as a function PARAMETER — is not statically evaluable, so
+ *     Metro collected no dependency at all and rewrote the call into a thrower
+ *     ("Dynamic require defined at line N; not supported by Metro"). It resolved
+ *     NOTHING from a consumer's `node_modules` whether or not nativewind was
+ *     installed, and `BloomColorScope` could never scope NativeWind classes on a
+ *     device.
+ *   - `isOptionalDependency` returns at the first BlockStatement above the call,
+ *     so one `if`/`else` of nesting inside the try loses the optional marking and
+ *     an absent nativewind fails the BUILD. Hence the `typeof require` guard
+ *     below sits outside the try.
+ *
+ * `require` may not exist at all (this file also backs the `import` condition,
+ * i.e. an ESM build under Node), hence that guard. Both callers below return
+ * before loading on web, where the vars are written to `document.documentElement`
+ * instead.
+ *
+ * @see connection-status/netinfo.ts — the same boundary for netinfo.
+ */
+
+/**
+ * Declared locally rather than taken from the ambient `NodeRequire`, which
+ * returns `any`: `unknown` forces the module handle to be narrowed below instead
+ * of leaking an untyped value into the caller.
+ */
+declare const require: (moduleName: string) => unknown;
 
 /**
  * Component that provides inline CSS variables to a subtree via NativeWind's
@@ -17,12 +59,69 @@ export type VariableContextProviderComponent = React.ComponentType<{
   children: React.ReactNode;
 }>;
 
+/**
+ * The slice of nativewind's surface Bloom uses. Hand-written so no nativewind
+ * type reaches Bloom's emitted declarations — a consumer that skips the optional
+ * peer must not inherit a TS7016 from Bloom's own `.d.ts`.
+ */
 interface NativeWindVarsModule {
   vars: (record: Record<string, string>) => StyleProp<ViewStyle>;
   VariableContextProvider?: VariableContextProviderComponent;
 }
 
-const getNativeWindVars = lazyRequire<NativeWindVarsModule>('nativewind');
+/** `undefined` until the first load attempt, then the module or `null`. */
+let nativeWindModule: NativeWindVarsModule | null | undefined;
+/** Why the scope cannot be applied, quoted verbatim in the dev warning. */
+let unavailableReason = '';
+let hasWarned = false;
+
+/** The nativewind module, or `null` when the optional peer is not installed. */
+function loadNativeWindVars(): NativeWindVarsModule | null {
+  if (nativeWindModule !== undefined) return nativeWindModule;
+  nativeWindModule = null;
+
+  // The `typeof require` guard sits OUTSIDE the try on purpose — see the second
+  // constraint above. Nested one `if`/`else` deeper, the require stops counting
+  // as optional and an app without nativewind fails to BUILD.
+  if (typeof require === 'undefined') {
+    unavailableReason = 'this bundle has no CommonJS `require`';
+    return nativeWindModule;
+  }
+
+  try {
+    const loaded = require('nativewind') as Partial<NativeWindVarsModule> | null | undefined;
+
+    if (typeof loaded?.vars === 'function') {
+      nativeWindModule = loaded as NativeWindVarsModule;
+    } else {
+      unavailableReason = 'the module resolved without a `vars` export';
+    }
+  } catch (error) {
+    unavailableReason = error instanceof Error ? error.message : String(error);
+  }
+
+  return nativeWindModule;
+}
+
+/**
+ * One warning per module lifetime, and none in production — the same mechanism
+ * as `connection-status/netinfo.ts`. A scope that does not scope is invisible:
+ * the subtree keeps rendering, just in the app-wide palette instead of the
+ * requested one.
+ */
+function warnScopeInert(detail: string): void {
+  if (process.env.NODE_ENV === 'production' || hasWarned) return;
+  hasWarned = true;
+  // Internal Bloom diagnostic: only the consumer's package.json can fix this,
+  // so it names the package and the install command.
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[Bloom] BloomColorScope cannot scope NativeWind classes on native: ${detail} ` +
+      'Descendants keep resolving `var(--primary)` and friends against the ' +
+      'app-wide preset. Install the optional peer (`npx expo install nativewind`) ' +
+      `to enable scoped presets. Reason: ${unavailableReason}`,
+  );
+}
 
 /**
  * Build the CSS custom-property map for a preset, ready to be applied to a
@@ -67,8 +166,18 @@ export function buildScopeVars(
  */
 export function getVariableContextProvider(): VariableContextProviderComponent | null {
   if (Platform.OS === 'web') return null;
-  const module = getNativeWindVars();
-  if (!module || typeof module.VariableContextProvider !== 'function') return null;
+  const module = loadNativeWindVars();
+  if (!module) {
+    warnScopeInert('the optional peer `nativewind` could not be loaded.');
+    return null;
+  }
+  if (typeof module.VariableContextProvider !== 'function') {
+    warnScopeInert(
+      'the installed `nativewind` exports no `VariableContextProvider` (the ' +
+        'NativeWind 5 / react-native-css@3 API this needs).',
+    );
+    return null;
+  }
   return module.VariableContextProvider;
 }
 
@@ -90,7 +199,10 @@ export function buildNativePresetStyle(
   mode: 'light' | 'dark',
 ): StyleProp<ViewStyle> {
   if (Platform.OS === 'web') return undefined;
-  const module = getNativeWindVars();
-  if (!module || typeof module.vars !== 'function') return undefined;
+  const module = loadNativeWindVars();
+  if (!module) {
+    warnScopeInert('the optional peer `nativewind` could not be loaded.');
+    return undefined;
+  }
   return module.vars(buildScopeVars(colorPreset, mode));
 }

package/src/theme/init-css-interop.ts

@@ -76,20 +76,22 @@ function tryCallSetFlag(): void {
   let mod: CssInteropModule | undefined;
   // `require` does not exist in an ES module, so guard before touching it —
   // an unguarded reference is a ReferenceError, not a resolution failure.
-  // Matches the pattern used by every other optional-module load in Bloom
-  // (`utils/lazy-require.ts`, `theme/adaptive-colors.ts`,
-  // `bottom-sheet/index.tsx`).
   if (typeof require === 'undefined') return;
   try {
-    // Dynamic require: css-interop is not a Bloom dependency. If the host
-    // app ships it (via NativeWind or directly), this resolves. Otherwise
-    // the require throws and we silently move on — there is nothing to
-    // initialize because css-interop is not in the bundle.
+    // Dynamic require: css-interop is neither a Bloom dependency nor a declared
+    // peer. The specifier goes through a variable to keep a plain-text
+    // `require('react-native-css-interop')` out of the file, so bundlers that
+    // scan for one do not try to resolve (and warn about, or fail on) a module
+    // Bloom never asked for.
     //
-    // The specifier goes through a variable on purpose: a literal
-    // `require('react-native-css-interop')` is statically analysable, so
-    // bundlers try to resolve (and warn about, or fail on) a module that is
-    // intentionally absent. The indirection keeps this a pure runtime lookup.
+    // Metro is not among them: its dependency collector EVALUATES the argument,
+    // folds this `const`, and treats the call exactly as it would a literal —
+    // optional, because it is a direct statement of a `try` block. So the
+    // indirection buys nothing under Metro and costs nothing either. It is not a
+    // pattern to copy: a specifier Metro cannot evaluate (a function parameter,
+    // a computed value) collects no dependency at all and is rewritten into a
+    // thrower, which is how `lazyRequire` silently killed four subsystems. See
+    // `connection-status/netinfo.ts` for the shape a real peer must use.
     const moduleName = 'react-native-css-interop';
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     mod = require(moduleName) as CssInteropModule;

package/lib/commonjs/avatar/svg-module.js

@@ -1,15 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.getSvgModule = void 0;
-var _lazyRequire = require("../utils/lazy-require.js");
-/**
- * Lazily loads `react-native-svg`, returning `null` when it is not installed
- * (e.g. a web bundle that does not ship the optional peer). Shared by the
- * squircle avatar image clip in `Avatar.tsx` and the `AvatarRing` so there is a
- * single loader rather than one per call site.
- */
-const getSvgModule = exports.getSvgModule = (0, _lazyRequire.lazyRequire)('react-native-svg');
-//# sourceMappingURL=svg-module.js.map

package/lib/commonjs/avatar/svg-module.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["_lazyRequire","require","getSvgModule","exports","lazyRequire"],"sourceRoot":"../../../src","sources":["avatar/svg-module.ts"],"mappings":";;;;;;AAAA,IAAAA,YAAA,GAAAC,OAAA;AAIA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMC,YAAY,GAAAC,OAAA,CAAAD,YAAA,GAAG,IAAAE,wBAAW,EAAgB,kBAAkB,CAAC","ignoreList":[]}