create-expo-boilerplate 1.1.0 → 1.1.1

package/overlays/react-navigation/src/shared/hooks/useScreenLoader.ts

@@ -0,0 +1,18 @@
+import { useEffect } from 'react';
+import { useIsFocused } from '@react-navigation/native';
+
+import { requestAppLoader } from '@/shared/utils/appLoader';
+
+/**
+ * Shows the app-wide loader while `active` is true and this screen is focused,
+ * so a tab or screen loading in the background never blocks the one in view.
+ */
+export function useScreenLoader(active: boolean): void {
+  const isFocused = useIsFocused();
+  const shouldShow = active && isFocused;
+
+  useEffect(() => {
+    if (!shouldShow) return;
+    return requestAppLoader();
+  }, [shouldShow]);
+}

package/overlays/styling/stylesheet/common/src/shared/components/FullScreenLoader.tsx

@@ -1,50 +1,64 @@
 import React from 'react';
-import { ActivityIndicator, Modal, Text, View } from 'react-native';
+import { ActivityIndicator, Text, View } from 'react-native';
 
 import { translate } from '@/localization/utils';
 import { ms } from '@/shared/utils';
 import { makeStyles, TextStyles, useAppTheme } from '@/theme';
 
-interface FullscreenLoaderProps {
+interface FullScreenLoaderProps {
   visible: boolean;
   size?: 'small' | 'large';
   color?: string;
+  /** Uses a lighter dim and theme-colored text, so a modal still looks solid. */
+  inModal?: boolean;
 }
 
-const FullscreenLoader: React.FC<FullscreenLoaderProps> = ({
+/**
+ * Loading overlay that fills its parent and blocks touches on what's beneath it.
+ *
+ * It is a plain view rather than a native `Modal`, so it can't get stuck over the
+ * app. Screens get it through `ScreenWrapper`'s `showLoader`. Inside a modal, pass
+ * `isModal` to `ScreenWrapper`, or render it here with `inModal` as the last child
+ * of the view to cover (give a view with rounded corners `overflow: 'hidden'`).
+ */
+const FullScreenLoader: React.FC<FullScreenLoaderProps> = ({
   visible = false,
   size = 'large',
   color,
+  inModal = false,
 }) => {
   const theme = useAppTheme();
   const styles = useStyles();
 
+  if (!visible) return null;
+
+  const label = translate('common.loading');
+
   return (
-    <Modal statusBarTranslucent transparent animationType="fade" visible={visible}>
-      <View style={styles.modalBackground}>
-        <View style={styles.activityIndicatorWrapper}>
-          <ActivityIndicator color={color || theme.colors.primary} size={size} />
-          <Text style={[TextStyles.label, styles.loadingText]}>{translate('common.loading')}</Text>
-        </View>
-      </View>
-    </Modal>
+    <View
+      accessibilityViewIsModal
+      accessible
+      accessibilityLabel={label}
+      accessibilityRole="progressbar"
+      style={styles.overlay}
+    >
+      <View style={inModal ? styles.modalBackdrop : styles.screenBackdrop} />
+      <ActivityIndicator color={color || theme.colors.primary} size={size} />
+      <Text style={[TextStyles.label, inModal ? styles.modalText : styles.screenText]}>
+        {label}
+      </Text>
+    </View>
   );
 };
 
+const fill = { position: 'absolute', top: 0, right: 0, bottom: 0, left: 0 } as const;
+
 const useStyles = makeStyles((theme) => ({
-  modalBackground: {
-    flex: 1,
-    justifyContent: 'center',
-    alignItems: 'center',
-    backgroundColor: theme.colors.opacity50,
-  },
-  activityIndicatorWrapper: {
-    padding: ms(20),
-    borderRadius: ms(10),
-    alignItems: 'center',
-    justifyContent: 'center',
-  },
-  loadingText: { color: theme.colors.white, marginTop: ms(10) },
+  overlay: { ...fill, justifyContent: 'center', alignItems: 'center' },
+  screenBackdrop: { ...fill, backgroundColor: theme.colors.opacity50 },
+  modalBackdrop: { ...fill, backgroundColor: 'rgba(0,0,0,0.35)' },
+  screenText: { color: theme.colors.white, marginTop: ms(10) },
+  modalText: { color: theme.colors.typography, marginTop: ms(10) },
 }));
 
-export default FullscreenLoader;
+export default FullScreenLoader;

package/overlays/styling/stylesheet/common/src/shared/components/ScreenWrapper.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import {
-  ImageBackground,
+  Image,
   type ImageResizeMode,
   type ImageSourcePropType,
   type ImageStyle,
@@ -11,7 +11,8 @@ import {
 import { KeyboardAwareScrollView } from 'react-native-keyboard-controller';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 
-import FullscreenLoader from '@/shared/components/FullScreenLoader';
+import FullScreenLoader from '@/shared/components/FullScreenLoader';
+import { useScreenLoader } from '@/shared/hooks/useScreenLoader';
 import { useAppTheme } from '@/theme';
 
 interface ScreenWrapperProps {
@@ -19,6 +20,8 @@ interface ScreenWrapperProps {
   /** Layout style (padding, justifyContent, alignItems, etc.). Routed to the content container in scrollable mode, or the outer View otherwise. */
   style?: ViewStyle;
   showLoader?: boolean;
+  /** Set on modal screens, and inside a React Native `<Modal>`: `showLoader` then covers only this content, not the whole app. */
+  isModal?: boolean;
   /** Enable for any screen with text inputs. Scrolls only when needed to keep the focused input above the keyboard. */
   scrollable?: boolean;
   /** Optional full-screen background image. Renders behind all content. */
@@ -35,12 +38,16 @@ const ScreenWrapper: React.FC<ScreenWrapperProps> = ({
   children,
   style,
   showLoader = false,
+  isModal = false,
   scrollable = false,
   backgroundImage,
   backgroundImageStyle,
   backgroundImageResizeMode = 'cover',
   keyboardBottomOffset = 20,
 }) => {
+  useScreenLoader(showLoader && !isModal);
+  const modalLoader = isModal ? <FullScreenLoader inModal visible={showLoader} /> : null;
+
   const theme = useAppTheme();
   const insets = useSafeAreaInsets();
   const wrapperStyle = [styles.wrapper, { backgroundColor: theme.colors.background }];
@@ -60,24 +67,19 @@ const ScreenWrapper: React.FC<ScreenWrapperProps> = ({
     <View style={[styles.viewContainer, bottomInset, style]}>{children}</View>
   );
 
-  const body = backgroundImage ? (
-    <ImageBackground
-      imageStyle={backgroundImageStyle}
-      resizeMode={backgroundImageResizeMode}
-      source={backgroundImage}
-      style={wrapperStyle}
-    >
-      {content}
-    </ImageBackground>
-  ) : (
-    <View style={wrapperStyle}>{content}</View>
-  );
-
   return (
-    <>
-      {body}
-      <FullscreenLoader visible={showLoader} />
-    </>
+    <View style={wrapperStyle}>
+      {backgroundImage ? (
+        <Image
+          accessibilityIgnoresInvertColors
+          resizeMode={backgroundImageResizeMode}
+          source={backgroundImage}
+          style={[styles.backgroundImage, backgroundImageStyle]}
+        />
+      ) : null}
+      {content}
+      {modalLoader}
+    </View>
   );
 };
 
@@ -87,6 +89,13 @@ const styles = StyleSheet.create({
   wrapper: {
     flex: 1,
   },
+  // The explicit size overrides the file's own dimensions, which `Image` applies
+  // to a `require`d source and which would otherwise beat the absolute edges.
+  backgroundImage: {
+    position: 'absolute',
+    width: '100%',
+    height: '100%',
+  },
   container: {
     flex: 1,
   },

package/overlays/styling/tailwind/common/src/shared/components/FullScreenLoader.tsx

@@ -1,34 +1,54 @@
 import React from 'react';
-import { ActivityIndicator, Modal, Text, View } from 'react-native';
+import { ActivityIndicator, Text, View } from 'react-native';
 
 import { translate } from '@/localization/utils';
 import { useAppTheme } from '@/theme';
 
-interface FullscreenLoaderProps {
+interface FullScreenLoaderProps {
   visible: boolean;
   size?: 'small' | 'large';
   color?: string;
+  /** Uses a lighter dim and theme-colored text, so a modal still looks solid. */
+  inModal?: boolean;
 }
 
-const FullscreenLoader: React.FC<FullscreenLoaderProps> = ({
+/**
+ * Loading overlay that fills its parent and blocks touches on what's beneath it.
+ *
+ * It is a plain view rather than a native `Modal`, so it can't get stuck over the
+ * app. Screens get it through `ScreenWrapper`'s `showLoader`. Inside a modal, pass
+ * `isModal` to `ScreenWrapper`, or render it here with `inModal` as the last child
+ * of the view to cover (give a view with rounded corners `overflow-hidden`).
+ */
+const FullScreenLoader: React.FC<FullScreenLoaderProps> = ({
   visible = false,
   size = 'large',
   color,
+  inModal = false,
 }) => {
   const theme = useAppTheme();
 
+  if (!visible) return null;
+
+  const label = translate('common.loading');
+
   return (
-    <Modal statusBarTranslucent transparent animationType="fade" visible={visible}>
-      <View className="flex-1 items-center justify-center bg-opacity50">
-        <View className="items-center justify-center rounded-[10px] p-5">
-          <ActivityIndicator color={color || theme.colors.primary} size={size} />
-          <Text className="text-label font-opensans-bold mt-2.5 text-white">
-            {translate('common.loading')}
-          </Text>
-        </View>
-      </View>
-    </Modal>
+    <View
+      accessibilityViewIsModal
+      accessible
+      accessibilityLabel={label}
+      accessibilityRole="progressbar"
+      className="absolute inset-0 items-center justify-center"
+    >
+      <View className={`absolute inset-0 ${inModal ? 'bg-black/35' : 'bg-opacity50'}`} />
+      <ActivityIndicator color={color || theme.colors.primary} size={size} />
+      <Text
+        className={`text-label font-opensans-bold mt-2.5 ${inModal ? 'text-typography' : 'text-white'}`}
+      >
+        {label}
+      </Text>
+    </View>
   );
 };
 
-export default FullscreenLoader;
+export default FullScreenLoader;

package/overlays/styling/tailwind/common/src/shared/components/ScreenWrapper.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import {
-  ImageBackground,
+  Image,
   type ImageResizeMode,
   type ImageSourcePropType,
   View,
@@ -8,13 +8,16 @@ import {
 import { KeyboardAwareScrollView } from 'react-native-keyboard-controller';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 
-import FullscreenLoader from '@/shared/components/FullScreenLoader';
+import FullScreenLoader from '@/shared/components/FullScreenLoader';
+import { useScreenLoader } from '@/shared/hooks/useScreenLoader';
 
 interface ScreenWrapperProps {
   children: React.ReactNode;
   /** Layout classes (padding, justify-*, items-*, …). Applied to the content in both scrollable and static mode. */
   className?: string;
   showLoader?: boolean;
+  /** Set on modal screens, and inside a React Native `<Modal>`: `showLoader` then covers only this content, not the whole app. */
+  isModal?: boolean;
   /** Enable for any screen with text inputs. Scrolls only when needed to keep the focused input above the keyboard. */
   scrollable?: boolean;
   /** Optional full-screen background image. Renders behind all content. */
@@ -31,12 +34,16 @@ const ScreenWrapper: React.FC<ScreenWrapperProps> = ({
   children,
   className = '',
   showLoader = false,
+  isModal = false,
   scrollable = false,
   backgroundImage,
   backgroundImageClassName,
   backgroundImageResizeMode = 'cover',
   keyboardBottomOffset = 20,
 }) => {
+  useScreenLoader(showLoader && !isModal);
+  const modalLoader = isModal ? <FullScreenLoader inModal visible={showLoader} /> : null;
+
   const insets = useSafeAreaInsets();
   const bottomInset = { paddingBottom: insets.bottom };
 
@@ -60,24 +67,21 @@ const ScreenWrapper: React.FC<ScreenWrapperProps> = ({
     </View>
   );
 
-  const body = backgroundImage ? (
-    <ImageBackground
-      className="flex-1 bg-background"
-      imageClassName={backgroundImageClassName}
-      resizeMode={backgroundImageResizeMode}
-      source={backgroundImage}
-    >
-      {content}
-    </ImageBackground>
-  ) : (
-    <View className="flex-1 bg-background">{content}</View>
-  );
-
   return (
-    <>
-      {body}
-      <FullscreenLoader visible={showLoader} />
-    </>
+    <View className="flex-1 bg-background">
+      {backgroundImage ? (
+        <Image
+          accessibilityIgnoresInvertColors
+          // The explicit size overrides the file's own dimensions, which `Image`
+          // applies to a `require`d source and which would otherwise beat `inset-0`.
+          className={`absolute h-full w-full ${backgroundImageClassName ?? ''}`}
+          resizeMode={backgroundImageResizeMode}
+          source={backgroundImage}
+        />
+      ) : null}
+      {content}
+      {modalLoader}
+    </View>
   );
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-expo-boilerplate",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Scaffold a production-ready Expo app from the React-Native-Expo-Boilterplate, with your choice of state management, navigation, language and tooling.",
   "type": "module",
   "bin": {

package/template/.env.example

@@ -42,6 +42,3 @@ EXPO_PUBLIC_APP_ENV=development
 # .env.development is seeded with https://dummyjson.com/ (a free demo API) so
 # the Home screen's posts example works out of the box. Swap it for your own.
 EXPO_PUBLIC_API_URL=https://your-api.example.com/
-
-# WebSocket server URL (must be a valid http(s) URL).
-EXPO_PUBLIC_SOCKET_URL=https://your-socket.example.com/

package/template/.skills/api-hook-creation.md

@@ -326,7 +326,7 @@ These are the call-site idioms you'll see in `app/(tabs)/home.tsx` etc. — repe
 **Loading + error states:**
 ```tsx
 const { data, isLoading, error } = usePosts();
-if (isLoading) return <FullScreenLoader />;
+return <ScreenWrapper showLoader={isLoading}>{/* screen content */}</ScreenWrapper>;
 // Error toast is already shown by the Axios interceptor; render an empty/retry state if needed.
 ```
 

package/template/.skills/ui-creation.md

@@ -119,7 +119,7 @@ Before building anything new, check `src/shared/components/`:
 | `Button` | Any tappable CTA. Variants: `primary`, `secondary`, `disabled`. Supports `leftIcon` / `rightIcon` / `isLoading`. |
 | `TextField` | Uncontrolled text input with focus animation, error border, optional left/end icons. |
 | `ControlledTextField` | `react-hook-form`-bound `TextField`. Use this in forms — never wire `TextField` to RHF directly. |
-| `FullScreenLoader` | Modal spinner overlay — usually triggered via `ScreenWrapper`'s `showLoader` prop. |
+| `FullScreenLoader` | Spinner overlay that blocks touches beneath it. On screens, use `ScreenWrapper`'s `showLoader`. In a modal, add `isModal` to `ScreenWrapper`, or render `<FullScreenLoader inModal visible={isLoading} />` as the last child of the view to cover. Give a view with rounded corners hidden overflow. |
 | `TabBarIcon` / `TabBarLabel` | Tab navigator UI bits. |
 
 If a new pattern recurs ≥3 times across screens, lift it into `src/shared/components/` rather than copy-pasting JSX.
@@ -143,7 +143,8 @@ Props:
 - `style` — layout style (padding, `justifyContent`, `alignItems`, etc.). Routed to the content container in scrollable mode, or the outer `View` otherwise. **Caller never thinks about which.**
 <!-- @cli:ui-wrapper-style-prop-end -->
 - `scrollable` — opt-in when the screen has text inputs or content that may exceed the viewport. Uses `KeyboardAwareScrollView` from `react-native-keyboard-controller`, which scrolls **only when the focused input would be obscured** by the keyboard. Centered layouts stay centered when there is room.
-- `showLoader` — toggles full-screen `ActivityIndicator` overlay.
+- `showLoader` — shows the app-wide `FullScreenLoader` above the tab bar and header while this screen is focused. A screen loading in the background doesn't show it.
+- `isModal` — set on modal screens and inside a React Native `<Modal>`. `showLoader` then covers only this content, and the modal stays solid instead of being dimmed.
 - `backgroundImage` / `backgroundImageStyle` / `backgroundImageResizeMode` — full-screen background art.
 - `keyboardBottomOffset` — gap between the keyboard top and the focused input (default `20`).
 

package/template/__mocks__/@env.ts

@@ -5,7 +5,6 @@ const Env = {
   EXPO_PUBLIC_PACKAGE_NAME: 'com.expo.template',
   EXPO_PUBLIC_VERSION: '1.0.0',
   EXPO_PUBLIC_API_URL: 'https://test-api.example.com/',
-  EXPO_PUBLIC_SOCKET_URL: 'https://test-socket.example.com',
 };
 
 export default Env;

package/template/env.ts

@@ -33,7 +33,6 @@ const envSchema = z.object({
 
   // Runtime variables (from .env.* files)
   EXPO_PUBLIC_API_URL: z.string().url('EXPO_PUBLIC_API_URL must be a valid URL'),
-  EXPO_PUBLIC_SOCKET_URL: z.string().url('EXPO_PUBLIC_SOCKET_URL must be a valid URL'),
 });
 
 // ─────────────────────────────────────────────────────────────
@@ -86,7 +85,6 @@ const _env: z.infer<typeof envSchema> = {
   EXPO_PUBLIC_PACKAGE_NAME: PACKAGE_NAME,
   EXPO_PUBLIC_VERSION: packageJSON.version,
   EXPO_PUBLIC_API_URL: process.env.EXPO_PUBLIC_API_URL ?? '',
-  EXPO_PUBLIC_SOCKET_URL: process.env.EXPO_PUBLIC_SOCKET_URL ?? '',
 };
 
 // ─────────────────────────────────────────────────────────────

package/template/src/providers/AppProviders.tsx

@@ -2,12 +2,11 @@ import React from 'react';
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
 import { KeyboardProvider } from 'react-native-keyboard-controller';
 import { SafeAreaProvider } from 'react-native-safe-area-context';
-import Toast from 'react-native-toast-message';
 import { NavigationBar } from 'expo-navigation-bar';
 import { StatusBar } from 'expo-status-bar';
 
 import { APIProvider } from '@/services/api-provider';
-import { toastConfig } from '@/shared/utils/toast';
+import { AppOverlay } from '@/shared/components/AppOverlay';
 import { StoreProvider } from '@/store';
 import { useAppTheme } from '@/theme';
 
@@ -31,7 +30,7 @@ export function AppProviders({ children }: { children: React.ReactNode }): React
             </StoreProvider>
           </SafeAreaProvider>
         </KeyboardProvider>
-        <Toast config={toastConfig} position="top" />
+        <AppOverlay />
       </GestureHandlerRootView>
     </>
   );

package/template/src/shared/components/AppOverlay.tsx

@@ -0,0 +1,32 @@
+import React from 'react';
+import { Platform, View, type ViewStyle } from 'react-native';
+import { FullWindowOverlay } from 'react-native-screens';
+import Toast from 'react-native-toast-message';
+
+import FullScreenLoader from '@/shared/components/FullScreenLoader';
+import { useIsAppLoaderVisible } from '@/shared/utils/appLoader';
+import { toastConfig } from '@/shared/utils/toast';
+
+// On iOS, native modal screens are presented above the app's root view, so toasts
+// need FullWindowOverlay to stay visible over them. On Android they share the root
+// view, and rendering last is enough.
+const Container = Platform.OS === 'ios' ? FullWindowOverlay : React.Fragment;
+
+// A plain object: this file is shared by every styling option.
+const fillParent: ViewStyle = { position: 'absolute', top: 0, right: 0, bottom: 0, left: 0 };
+
+/** App-wide layer above the navigator: the loader, with toasts on top of it. */
+export function AppOverlay(): React.JSX.Element {
+  const isLoaderVisible = useIsAppLoaderVisible();
+
+  return (
+    <Container>
+      {/* FullWindowOverlay stacks children in mount order, ignoring their order
+          here, so this one view keeps the toast above a loader that mounts later. */}
+      <View collapsable={false} pointerEvents="box-none" style={fillParent}>
+        <FullScreenLoader visible={isLoaderVisible} />
+        <Toast config={toastConfig} position="top" />
+      </View>
+    </Container>
+  );
+}

package/template/src/shared/components/FullScreenLoader.tsx

@@ -1,50 +1,64 @@
 import React from 'react';
-import { ActivityIndicator, Modal, Text, View } from 'react-native';
+import { ActivityIndicator, Text, View } from 'react-native';
 import { StyleSheet, useUnistyles } from 'react-native-unistyles';
 
 import { translate } from '@/localization/utils';
 import { ms } from '@/shared/utils';
 import { TextStyles } from '@/theme';
 
-interface FullscreenLoaderProps {
+interface FullScreenLoaderProps {
   visible: boolean;
   size?: 'small' | 'large';
   color?: string;
+  /** Uses a lighter dim and theme-colored text, so a modal still looks solid. */
+  inModal?: boolean;
 }
 
-const FullscreenLoader: React.FC<FullscreenLoaderProps> = ({
+/**
+ * Loading overlay that fills its parent and blocks touches on what's beneath it.
+ *
+ * It is a plain view rather than a native `Modal`, so it can't get stuck over the
+ * app. Screens get it through `ScreenWrapper`'s `showLoader`. Inside a modal, pass
+ * `isModal` to `ScreenWrapper`, or render it here with `inModal` as the last child
+ * of the view to cover (give a view with rounded corners `overflow: 'hidden'`).
+ */
+const FullScreenLoader: React.FC<FullScreenLoaderProps> = ({
   visible = false,
   size = 'large',
   color,
+  inModal = false,
 }) => {
   const { theme } = useUnistyles();
 
+  if (!visible) return null;
+
+  const label = translate('common.loading');
+
   return (
-    <Modal statusBarTranslucent transparent animationType="fade" visible={visible}>
-      <View style={styles.modalBackground}>
-        <View style={styles.activityIndicatorWrapper}>
-          <ActivityIndicator color={color || theme.colors.primary} size={size} />
-          <Text style={[TextStyles.label, styles.loadingText]}>{translate('common.loading')}</Text>
-        </View>
-      </View>
-    </Modal>
+    <View
+      accessibilityViewIsModal
+      accessible
+      accessibilityLabel={label}
+      accessibilityRole="progressbar"
+      style={styles.overlay}
+    >
+      <View style={inModal ? styles.modalBackdrop : styles.screenBackdrop} />
+      <ActivityIndicator color={color || theme.colors.primary} size={size} />
+      <Text style={[TextStyles.label, inModal ? styles.modalText : styles.screenText]}>
+        {label}
+      </Text>
+    </View>
   );
 };
 
+const fill = { position: 'absolute', top: 0, right: 0, bottom: 0, left: 0 } as const;
+
 const styles = StyleSheet.create((theme) => ({
-  modalBackground: {
-    flex: 1,
-    justifyContent: 'center',
-    alignItems: 'center',
-    backgroundColor: theme.colors.opacity50,
-  },
-  activityIndicatorWrapper: {
-    padding: ms(20),
-    borderRadius: ms(10),
-    alignItems: 'center',
-    justifyContent: 'center',
-  },
-  loadingText: { color: theme.colors.white, marginTop: ms(10) },
+  overlay: { ...fill, justifyContent: 'center', alignItems: 'center' },
+  screenBackdrop: { ...fill, backgroundColor: theme.colors.opacity50 },
+  modalBackdrop: { ...fill, backgroundColor: 'rgba(0,0,0,0.35)' },
+  screenText: { color: theme.colors.white, marginTop: ms(10) },
+  modalText: { color: theme.colors.typography, marginTop: ms(10) },
 }));
 
-export default FullscreenLoader;
+export default FullScreenLoader;

package/template/src/shared/components/ScreenWrapper.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import {
-  ImageBackground,
+  Image,
   type ImageResizeMode,
   type ImageSourcePropType,
   type ImageStyle,
@@ -10,13 +10,16 @@ import {
 import { KeyboardAwareScrollView } from 'react-native-keyboard-controller';
 import { StyleSheet } from 'react-native-unistyles';
 
-import FullscreenLoader from '@/shared/components/FullScreenLoader';
+import FullScreenLoader from '@/shared/components/FullScreenLoader';
+import { useScreenLoader } from '@/shared/hooks/useScreenLoader';
 
 interface ScreenWrapperProps {
   children: React.ReactNode;
   /** Layout style (padding, justifyContent, alignItems, etc.). Routed to the content container in scrollable mode, or the outer View otherwise. */
   style?: ViewStyle;
   showLoader?: boolean;
+  /** Set on modal screens, and inside a React Native `<Modal>`: `showLoader` then covers only this content, not the whole app. */
+  isModal?: boolean;
   /** Enable for any screen with text inputs. Scrolls only when needed to keep the focused input above the keyboard. */
   scrollable?: boolean;
   /** Optional full-screen background image. Renders behind all content. */
@@ -33,12 +36,16 @@ const ScreenWrapper: React.FC<ScreenWrapperProps> = ({
   children,
   style,
   showLoader = false,
+  isModal = false,
   scrollable = false,
   backgroundImage,
   backgroundImageStyle,
   backgroundImageResizeMode = 'cover',
   keyboardBottomOffset = 20,
 }) => {
+  useScreenLoader(showLoader && !isModal);
+  const modalLoader = isModal ? <FullScreenLoader inModal visible={showLoader} /> : null;
+
   const content = scrollable ? (
     <KeyboardAwareScrollView
       bottomOffset={keyboardBottomOffset}
@@ -53,24 +60,19 @@ const ScreenWrapper: React.FC<ScreenWrapperProps> = ({
     <View style={[styles.viewContainer, style]}>{children}</View>
   );
 
-  const body = backgroundImage ? (
-    <ImageBackground
-      imageStyle={backgroundImageStyle}
-      resizeMode={backgroundImageResizeMode}
-      source={backgroundImage}
-      style={styles.wrapper}
-    >
-      {content}
-    </ImageBackground>
-  ) : (
-    <View style={styles.wrapper}>{content}</View>
-  );
-
   return (
-    <>
-      {body}
-      <FullscreenLoader visible={showLoader} />
-    </>
+    <View style={styles.wrapper}>
+      {backgroundImage ? (
+        <Image
+          accessibilityIgnoresInvertColors
+          resizeMode={backgroundImageResizeMode}
+          source={backgroundImage}
+          style={[styles.backgroundImage, backgroundImageStyle]}
+        />
+      ) : null}
+      {content}
+      {modalLoader}
+    </View>
   );
 };
 
@@ -81,6 +83,13 @@ const styles = StyleSheet.create((theme, rt) => ({
     flex: 1,
     backgroundColor: theme.colors.background,
   },
+  // The explicit size overrides the file's own dimensions, which `Image` applies
+  // to a `require`d source and which would otherwise beat the absolute edges.
+  backgroundImage: {
+    position: 'absolute',
+    width: '100%',
+    height: '100%',
+  },
   container: {
     flex: 1,
   },

package/template/src/shared/constants/index.ts

@@ -1,3 +1 @@
-export * as DeviceInfo from '@/shared/constants/deviceInfo';
 export { NAVIGATION } from '@/shared/constants/navigation';
-export { STATUS } from '@/shared/constants/status';

package/template/src/shared/hooks/index.ts

@@ -1,3 +1,4 @@
 export { useAppState, useOnAppForeground } from './useAppState';
 export { useBlockBackNavigation } from './useBlockBackNavigation';
 export { useDebounce } from './useDebounce';
+export { useScreenLoader } from './useScreenLoader';

package/template/src/shared/hooks/useScreenLoader.ts

@@ -0,0 +1,18 @@
+import { useEffect } from 'react';
+import { useIsFocused } from 'expo-router';
+
+import { requestAppLoader } from '@/shared/utils/appLoader';
+
+/**
+ * Shows the app-wide loader while `active` is true and this screen is focused,
+ * so a tab or screen loading in the background never blocks the one in view.
+ */
+export function useScreenLoader(active: boolean): void {
+  const isFocused = useIsFocused();
+  const shouldShow = active && isFocused;
+
+  useEffect(() => {
+    if (!shouldShow) return;
+    return requestAppLoader();
+  }, [shouldShow]);
+}

package/template/src/shared/utils/__tests__/appLoader.test.ts

@@ -0,0 +1,44 @@
+import { act, renderHook } from '@testing-library/react-native';
+
+import { requestAppLoader, useIsAppLoaderVisible } from '@/shared/utils/appLoader';
+
+describe('appLoader', () => {
+  it('stays visible until every request is released', () => {
+    const { result } = renderHook(() => useIsAppLoaderVisible());
+    expect(result.current).toBe(false);
+
+    let releaseFirst = () => {};
+    let releaseSecond = () => {};
+    act(() => {
+      releaseFirst = requestAppLoader();
+      releaseSecond = requestAppLoader();
+    });
+    expect(result.current).toBe(true);
+
+    act(() => releaseFirst());
+    expect(result.current).toBe(true);
+
+    act(() => releaseSecond());
+    expect(result.current).toBe(false);
+  });
+
+  it('ignores a second release of the same request', () => {
+    const { result } = renderHook(() => useIsAppLoaderVisible());
+
+    let releaseFirst = () => {};
+    let releaseSecond = () => {};
+    act(() => {
+      releaseFirst = requestAppLoader();
+      releaseSecond = requestAppLoader();
+    });
+
+    act(() => {
+      releaseFirst();
+      releaseFirst();
+    });
+    expect(result.current).toBe(true);
+
+    act(() => releaseSecond());
+    expect(result.current).toBe(false);
+  });
+});

package/template/src/shared/utils/appLoader.ts

@@ -0,0 +1,33 @@
+import { useSyncExternalStore } from 'react';
+
+// How many screens currently want the app-wide loader. A count rather than a
+// boolean, so one screen finishing can't hide the loader for another.
+let activeRequests = 0;
+const listeners = new Set<() => void>();
+
+const notify = () => listeners.forEach((listener) => listener());
+
+const subscribe = (listener: () => void) => {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+/** Shows the app-wide loader until the returned function is called. */
+export function requestAppLoader(): () => void {
+  activeRequests += 1;
+  notify();
+
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    activeRequests -= 1;
+    notify();
+  };
+}
+
+export function useIsAppLoaderVisible(): boolean {
+  return useSyncExternalStore(subscribe, () => activeRequests > 0);
+}

package/template/src/shared/constants/ApiUrls.ts

@@ -1,4 +0,0 @@
-import Env from '@env';
-
-export const BASE_URL = Env.EXPO_PUBLIC_API_URL;
-export const SOCKET_URL = Env.EXPO_PUBLIC_SOCKET_URL;

package/template/src/shared/constants/deviceInfo.ts

@@ -1,11 +0,0 @@
-import { Dimensions, Platform } from 'react-native';
-import Constants from 'expo-constants';
-
-export const { width: windowWidth, height: windowHeight } = Dimensions.get('window');
-
-export const { version, ios, android } = Constants?.expoConfig ?? {};
-
-export const OS = Platform.OS;
-export const isWeb = Platform.OS === 'web';
-export const isIOS = Platform.OS === 'ios';
-export const isAndroid = Platform.OS === 'android';