From c101bb0c3b950ba26e31d89c82290c8a4cf43064 Mon Sep 17 00:00:00 2001
From: Arkadiusz Kubaczkowski <arek.kubaczkowski@gmail.com>
Date: Wed, 21 Jan 2026 15:15:53 +0100
Subject: [PATCH 1/7] feat: persistent bottom sheet

---
 example/src/App.tsx                        |   6 +
 example/src/bottom-sheet.d.ts              |   1 +
 example/src/screens/HomeScreen.tsx         |  10 +-
 example/src/sheets/ScannerNestedSheets.tsx |  79 +++++++++
 example/src/sheets/ScannerSheet.tsx        | 189 +++++++++++++++++++++
 example/src/sheets/index.ts                |   1 +
 src/BottomSheetBackdrop.tsx                |  23 ++-
 src/BottomSheetHost.tsx                    |  79 ++++++---
 src/BottomSheetManaged.tsx                 |  21 ++-
 src/BottomSheetPersistent.tsx              |  70 ++++++++
 src/bottomSheet.store.ts                   | 124 +++++++++++---
 src/bottomSheetCoordinator.ts              |  18 +-
 src/index.tsx                              |   1 +
 src/useBottomSheetControl.ts               |  10 +-
 14 files changed, 564 insertions(+), 68 deletions(-)
 create mode 100644 example/src/sheets/ScannerNestedSheets.tsx
 create mode 100644 example/src/sheets/ScannerSheet.tsx
 create mode 100644 src/BottomSheetPersistent.tsx

diff --git a/example/src/App.tsx b/example/src/App.tsx
index 4e3205f..925aae4 100644
--- a/example/src/App.tsx
+++ b/example/src/App.tsx
@@ -1,6 +1,7 @@
 import {
   BottomSheetHost,
   BottomSheetManagerProvider,
+  BottomSheetPersistent,
   BottomSheetScaleView,
 } from 'react-native-bottom-sheet-stack';
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
@@ -8,6 +9,7 @@ import { SafeAreaProvider } from 'react-native-safe-area-context';
 
 import { UserProvider } from './context/UserContext';
 import { HomeScreen } from './screens';
+import { ScannerSheet } from './sheets';
 import { sharedStyles } from './styles/theme';
 
 export default function App() {
@@ -24,6 +26,10 @@ export default function App() {
             </UserProvider>
           </BottomSheetScaleView>
           <BottomSheetHost />
+          {/* Persistent sheet - always mounted, opens instantly */}
+          <BottomSheetPersistent id="scanner-sheet">
+            <ScannerSheet />
+          </BottomSheetPersistent>
         </BottomSheetManagerProvider>
       </GestureHandlerRootView>
     </SafeAreaProvider>
diff --git a/example/src/bottom-sheet.d.ts b/example/src/bottom-sheet.d.ts
index 8342bfd..cbbd7bc 100644
--- a/example/src/bottom-sheet.d.ts
+++ b/example/src/bottom-sheet.d.ts
@@ -7,5 +7,6 @@ declare module 'react-native-bottom-sheet-stack' {
     };
     'portal-mode-sheet-a': true;
     'portal-mode-sheet-b': true;
+    'scanner-sheet': true;
   }
 }
diff --git a/example/src/screens/HomeScreen.tsx b/example/src/screens/HomeScreen.tsx
index bd2175f..c62ceef 100644
--- a/example/src/screens/HomeScreen.tsx
+++ b/example/src/screens/HomeScreen.tsx
@@ -1,4 +1,4 @@
-import { StyleSheet, ScrollView, Text, View } from 'react-native';
+import { ScrollView, StyleSheet, Text, View } from 'react-native';
 import {
   BottomSheetPortal,
   useBottomSheetControl,
@@ -23,6 +23,7 @@ export function HomeScreen() {
   const { openBottomSheet } = useBottomSheetManager();
   const portalSheetControl = useBottomSheetControl('context-portal-sheet');
   const portalModeSheetA = useBottomSheetControl('portal-mode-sheet-a');
+  const scannerControl = useBottomSheetControl('scanner-sheet');
 
   return (
     <View style={sharedStyles.container}>
@@ -112,6 +113,13 @@ export function HomeScreen() {
               openBottomSheet(<HeavySheet />, { scaleBackground: true })
             }
           />
+
+          <DemoCard
+            title="Persistent Scanner"
+            description="Pre-mounted sheet with keepMounted - opens instantly"
+            color={colors.cyan}
+            onPress={() => scannerControl.open({ scaleBackground: true })}
+          />
         </View>
 
         {/* Features */}
diff --git a/example/src/sheets/ScannerNestedSheets.tsx b/example/src/sheets/ScannerNestedSheets.tsx
new file mode 100644
index 0000000..a942e7b
--- /dev/null
+++ b/example/src/sheets/ScannerNestedSheets.tsx
@@ -0,0 +1,79 @@
+import type { BottomSheetMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
+import { forwardRef } from 'react';
+import { Text, View } from 'react-native';
+import {
+  useBottomSheetManager,
+  useBottomSheetState,
+} from 'react-native-bottom-sheet-stack';
+
+import { Badge, Button, SecondaryButton, Sheet } from '../components';
+import { colors, sharedStyles } from '../styles/theme';
+
+export const ScannerNestedSheet2 = forwardRef<BottomSheetMethods>((_, ref) => {
+  const { close } = useBottomSheetState();
+
+  const mockHistory = [
+    { id: 'QR-A1B2C3D4', date: '2 min ago' },
+    { id: 'QR-E5F6G7H8', date: '15 min ago' },
+    { id: 'QR-I9J0K1L2', date: '1 hour ago' },
+  ];
+
+  return (
+    <Sheet ref={ref} snapPoints={['45%']} backgroundColor={colors.nested2}>
+      <Badge label="Nested Level 2" color={colors.purple} />
+      <Text style={sharedStyles.h1}>Scan History</Text>
+      <Text style={sharedStyles.text}>Recent scans from this session:</Text>
+      <View style={{ gap: 8, marginVertical: 16 }}>
+        {mockHistory.map((item) => (
+          <View
+            key={item.id}
+            style={{
+              flexDirection: 'row',
+              justifyContent: 'space-between',
+              padding: 12,
+              backgroundColor: colors.background,
+              borderRadius: 8,
+            }}
+          >
+            <Text style={{ color: colors.text, fontFamily: 'monospace' }}>
+              {item.id}
+            </Text>
+            <Text style={{ color: colors.textMuted }}>{item.date}</Text>
+          </View>
+        ))}
+      </View>
+      <View style={{ gap: 12, marginTop: 'auto' }}>
+        <Button title="Close" onPress={close} />
+      </View>
+    </Sheet>
+  );
+});
+
+ScannerNestedSheet2.displayName = 'ScannerNestedSheet2';
+
+export const ScannerNestedSheet1 = forwardRef<BottomSheetMethods>((_, ref) => {
+  const { close } = useBottomSheetState();
+  const { openBottomSheet } = useBottomSheetManager();
+
+  return (
+    <Sheet ref={ref} snapPoints={['50%']} backgroundColor={colors.nested1}>
+      <Badge label="Nested Level 1" />
+      <Text style={sharedStyles.h1}>Scan Options</Text>
+      <Text style={sharedStyles.text}>
+        Configure your scan settings or view scan history. This sheet was opened
+        from a persistent (keepMounted) sheet.
+      </Text>
+      <View style={{ gap: 12, marginTop: 'auto' }}>
+        <Button
+          title="Open Scan History"
+          onPress={() =>
+            openBottomSheet(<ScannerNestedSheet2 />, { scaleBackground: true })
+          }
+        />
+        <SecondaryButton title="Close" onPress={close} />
+      </View>
+    </Sheet>
+  );
+});
+
+ScannerNestedSheet1.displayName = 'ScannerNestedSheet1';
diff --git a/example/src/sheets/ScannerSheet.tsx b/example/src/sheets/ScannerSheet.tsx
new file mode 100644
index 0000000..b65de0e
--- /dev/null
+++ b/example/src/sheets/ScannerSheet.tsx
@@ -0,0 +1,189 @@
+import type { BottomSheetMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
+import { forwardRef, useCallback, useState } from 'react';
+import { StyleSheet, Text, View } from 'react-native';
+import {
+  useBottomSheetContext,
+  useBottomSheetManager,
+} from 'react-native-bottom-sheet-stack';
+
+import { Badge, Button, SecondaryButton, Sheet } from '../components';
+import { ScannerNestedSheet1 } from './ScannerNestedSheets';
+import { colors, sharedStyles } from '../styles/theme';
+
+export const ScannerSheet = forwardRef<BottomSheetMethods>((_, ref) => {
+  const { close } = useBottomSheetContext();
+  const { openBottomSheet } = useBottomSheetManager();
+  const [isScanning, setIsScanning] = useState(false);
+  const [scanResult, setScanResult] = useState<string | null>(null);
+
+  const handleStartScan = useCallback(() => {
+    setIsScanning(true);
+    setScanResult(null);
+
+    // Simulate scanning delay
+    setTimeout(() => {
+      setIsScanning(false);
+      setScanResult(
+        `QR-${Math.random().toString(36).substring(2, 10).toUpperCase()}`
+      );
+    }, 2000);
+  }, []);
+
+  const handleReset = useCallback(() => {
+    setIsScanning(false);
+    setScanResult(null);
+  }, []);
+
+  return (
+    <Sheet ref={ref} enableDynamicSizing>
+      <Badge label="Persistent Sheet" color={colors.cyan} />
+      <Text style={sharedStyles.h1}>QR Scanner</Text>
+      <Text style={sharedStyles.text}>
+        This sheet is always mounted (keepMounted). It opens instantly without
+        mount delay and preserves state between open/close cycles.
+      </Text>
+
+      {/* Scanner viewport */}
+      <View style={styles.scannerViewport}>
+        {isScanning ? (
+          <View style={styles.scanningOverlay}>
+            <View style={styles.scanLine} />
+            <Text style={styles.scanningText}>Scanning...</Text>
+          </View>
+        ) : scanResult ? (
+          <View style={styles.resultContainer}>
+            <Text style={styles.resultLabel}>Scanned Code:</Text>
+            <Text style={styles.resultValue}>{scanResult}</Text>
+          </View>
+        ) : (
+          <View style={styles.placeholderContainer}>
+            <Text style={styles.placeholderIcon}>[ ]</Text>
+            <Text style={styles.placeholderText}>Ready to scan</Text>
+          </View>
+        )}
+      </View>
+
+      {/* Actions */}
+      <View style={styles.actions}>
+        {scanResult ? (
+          <>
+            <Button title="Scan Again" onPress={handleReset} />
+            <Button
+              title="Open Nested Sheet"
+              onPress={() =>
+                openBottomSheet(<ScannerNestedSheet1 />, {
+                  scaleBackground: true,
+                  mode: 'switch',
+                })
+              }
+            />
+            <SecondaryButton title="Close" onPress={close} />
+          </>
+        ) : (
+          <>
+            <Button
+              title={isScanning ? 'Scanning...' : 'Start Scan'}
+              onPress={isScanning ? () => {} : handleStartScan}
+            />
+            <Button
+              title="Open Nested Sheet"
+              onPress={() =>
+                openBottomSheet(<ScannerNestedSheet1 />, {
+                  scaleBackground: true,
+                  mode: 'switch',
+                })
+              }
+            />
+            <SecondaryButton title="Close" onPress={close} />
+          </>
+        )}
+      </View>
+
+      {/* Info box */}
+      <View style={styles.infoBox}>
+        <Text style={styles.infoText}>
+          Try closing and reopening - the sheet appears instantly because it's
+          pre-mounted with keepMounted flag.
+        </Text>
+      </View>
+    </Sheet>
+  );
+});
+
+ScannerSheet.displayName = 'ScannerSheet';
+
+const styles = StyleSheet.create({
+  scannerViewport: {
+    height: 180,
+    backgroundColor: colors.background,
+    borderRadius: 16,
+    borderWidth: 2,
+    borderColor: colors.border,
+    borderStyle: 'dashed',
+    marginVertical: 16,
+    overflow: 'hidden',
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  scanningOverlay: {
+    flex: 1,
+    width: '100%',
+    justifyContent: 'center',
+    alignItems: 'center',
+    backgroundColor: 'rgba(0, 0, 0, 0.3)',
+  },
+  scanLine: {
+    width: '80%',
+    height: 2,
+    backgroundColor: colors.cyan,
+    marginBottom: 16,
+  },
+  scanningText: {
+    color: colors.cyan,
+    fontSize: 16,
+    fontWeight: '600',
+  },
+  resultContainer: {
+    alignItems: 'center',
+  },
+  resultLabel: {
+    color: colors.textSecondary,
+    fontSize: 14,
+    marginBottom: 8,
+  },
+  resultValue: {
+    color: colors.success,
+    fontSize: 24,
+    fontWeight: '700',
+    fontFamily: 'monospace',
+  },
+  placeholderContainer: {
+    alignItems: 'center',
+  },
+  placeholderIcon: {
+    fontSize: 48,
+    color: colors.textMuted,
+    marginBottom: 8,
+  },
+  placeholderText: {
+    color: colors.textMuted,
+    fontSize: 14,
+  },
+  actions: {
+    gap: 12,
+  },
+  infoBox: {
+    backgroundColor: colors.background,
+    borderRadius: 12,
+    padding: 14,
+    marginTop: 16,
+    borderWidth: 1,
+    borderColor: colors.border,
+  },
+  infoText: {
+    color: colors.textSecondary,
+    fontSize: 13,
+    lineHeight: 18,
+    textAlign: 'center',
+  },
+});
diff --git a/example/src/sheets/index.ts b/example/src/sheets/index.ts
index 2c5a953..1ef9cd0 100644
--- a/example/src/sheets/index.ts
+++ b/example/src/sheets/index.ts
@@ -8,3 +8,4 @@ export { HeavySheet } from './DynamicContentSheet';
 export { SheetA, SheetB, SheetC, SheetD } from './NavigationSheets';
 export { NestedSheet1, NestedSheet2, NestedSheet3 } from './NestedScaleSheets';
 export { PortalModeSheetA, PortalModeSheetB } from './PortalModeSheets';
+export { ScannerSheet } from './ScannerSheet';
diff --git a/src/BottomSheetBackdrop.tsx b/src/BottomSheetBackdrop.tsx
index 76bc451..10d4d45 100644
--- a/src/BottomSheetBackdrop.tsx
+++ b/src/BottomSheetBackdrop.tsx
@@ -12,8 +12,6 @@ interface BottomSheetBackdropProps {
   onPress?: () => void;
 }
 
-const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
-
 /**
  * Custom backdrop component rendered separately from the scaled sheet content.
  * This ensures the backdrop doesn't scale with the sheet.
@@ -28,7 +26,8 @@ export function BottomSheetBackdrop({
   );
 
   const animatedIndex = getAnimatedIndex(sheetId);
-  const isVisible = status === 'opening' || status === 'open';
+  // Only allow interaction when fully open - prevents animation conflicts
+  const isInteractive = status === 'open';
 
   const animatedStyle = useAnimatedStyle(() => {
     const opacity = interpolate(
@@ -42,17 +41,23 @@ export function BottomSheetBackdrop({
   });
 
   return (
-    <AnimatedPressable
-      style={[styles.backdrop, animatedStyle]}
-      onPress={onPress}
-      pointerEvents={isVisible ? 'auto' : 'none'}
-    />
+    <Pressable
+      style={StyleSheet.absoluteFillObject}
+      onPress={() => {
+        if (isInteractive) {
+          onPress?.();
+        }
+      }}
+    >
+      <Animated.View
+        style={[StyleSheet.absoluteFillObject, animatedStyle, styles.backdrop]}
+      />
+    </Pressable>
   );
 }
 
 const styles = StyleSheet.create({
   backdrop: {
-    ...StyleSheet.absoluteFillObject,
     backgroundColor: 'rgba(0, 0, 0, 0.5)',
   },
 });
diff --git a/src/BottomSheetHost.tsx b/src/BottomSheetHost.tsx
index 9fbf3b2..5118f38 100644
--- a/src/BottomSheetHost.tsx
+++ b/src/BottomSheetHost.tsx
@@ -27,7 +27,7 @@ function PortalHostWrapper({
 }
 
 function BottomSheetHostComp() {
-  const queueIds = useQueueIds();
+  const { activeIds, hiddenKeepMountedIds } = useAllSheetIds();
   const clearGroup = useBottomSheetStore((store) => store.clearGroup);
 
   const { groupId } = useBottomSheetManagerContext();
@@ -47,18 +47,30 @@ function BottomSheetHostComp() {
 
   return (
     <>
-      {queueIds.map((id, index) => (
-        <QueueItem key={id} id={id} stackIndex={index} />
+      {hiddenKeepMountedIds.map((id) => (
+        <QueueItem key={id} id={id} stackIndex={-1} isActive={false} />
+      ))}
+      {activeIds.map((id, index) => (
+        <QueueItem key={id} id={id} stackIndex={index} isActive={true} />
       ))}
     </>
   );
 }
 
-function QueueItem({ id, stackIndex }: { id: string; stackIndex: number }) {
-  const { content, usePortal, startClosing } = useBottomSheetStore(
+function QueueItem({
+  id,
+  stackIndex,
+  isActive,
+}: {
+  id: string;
+  stackIndex: number;
+  isActive: boolean;
+}) {
+  const { content, usePortal, startClosing, keepMounted } = useBottomSheetStore(
     (state) => ({
       content: state.sheetsById[id]?.content,
       usePortal: state.sheetsById[id]?.usePortal,
+      keepMounted: state.sheetsById[id]?.keepMounted,
       startClosing: state.startClosing,
     }),
     shallow
@@ -66,27 +78,34 @@ function QueueItem({ id, stackIndex }: { id: string; stackIndex: number }) {
 
   const { width, height } = useSafeAreaFrame();
   const value = { id };
-
   const scaleStyle = useScaleAnimatedStyle({ id });
 
   useEffect(() => {
     return () => {
-      cleanupSheetRef(id);
-      cleanupAnimatedIndex(id);
+      if (!keepMounted) {
+        cleanupSheetRef(id);
+        cleanupAnimatedIndex(id);
+      }
     };
-  }, [id]);
+  }, [id, keepMounted]);
 
   const backdropZIndex = stackIndex * 2;
   const contentZIndex = stackIndex * 2 + 1;
 
   return (
     <BottomSheetContext.Provider value={value}>
-      <View style={[StyleSheet.absoluteFillObject, { zIndex: backdropZIndex }]}>
-        <BottomSheetBackdrop sheetId={id} onPress={() => startClosing(id)} />
-      </View>
+      {isActive && (
+        <View
+          style={[StyleSheet.absoluteFillObject, { zIndex: backdropZIndex }]}
+          pointerEvents="box-none"
+        >
+          <BottomSheetBackdrop sheetId={id} onPress={() => startClosing(id)} />
+        </View>
+      )}
 
       {/* Sheet content - rendered with scaling */}
       <Animated.View
+        pointerEvents="box-none"
         style={[
           StyleSheet.absoluteFillObject,
           styles.container,
@@ -104,22 +123,36 @@ function QueueItem({ id, stackIndex }: { id: string; stackIndex: number }) {
   );
 }
 
-const useQueueIds = () => {
+const useAllSheetIds = () => {
   const { groupId } = useBottomSheetManagerContext();
 
-  return useBottomSheetStore(
-    (state) =>
-      state.stackOrder.filter(
-        (sheetId) => state.sheetsById[sheetId]?.groupId === groupId
-      ),
-    shallow
-  );
+  return useBottomSheetStore((state) => {
+    // Active sheets from stackOrder
+    const activeIds = state.stackOrder.filter(
+      (sheetId) => state.sheetsById[sheetId]?.groupId === groupId
+    );
+
+    // Hidden keepMounted sheets (in sheetsById but not in stackOrder)
+    const stackOrderSet = new Set(state.stackOrder);
+    const hiddenKeepMountedIds = Object.keys(state.sheetsById).filter(
+      (sheetId) => {
+        const sheet = state.sheetsById[sheetId];
+        return (
+          sheet &&
+          sheet.groupId === groupId &&
+          sheet.keepMounted &&
+          sheet.status === 'hidden' &&
+          !stackOrderSet.has(sheetId)
+        );
+      }
+    );
+
+    return { activeIds, hiddenKeepMountedIds };
+  }, shallow);
 };
 
 export const BottomSheetHost = BottomSheetHostComp;
 
 const styles = StyleSheet.create({
-  container: {
-    pointerEvents: 'box-none',
-  },
+  container: {},
 });
diff --git a/src/BottomSheetManaged.tsx b/src/BottomSheetManaged.tsx
index 51fe933..ac7342e 100644
--- a/src/BottomSheetManaged.tsx
+++ b/src/BottomSheetManaged.tsx
@@ -6,6 +6,7 @@ import { type BottomSheetMethods } from '@gorhom/bottom-sheet/lib/typescript/typ
 import React from 'react';
 
 import { getAnimatedIndex } from './animatedRegistry';
+import { useBottomSheetStore } from './bottomSheet.store';
 import { createSheetEventHandlers } from './bottomSheetCoordinator';
 import { useBottomSheetContext } from './useBottomSheetContext';
 
@@ -23,18 +24,25 @@ export const BottomSheetManaged = React.forwardRef<
     {
       children,
       onAnimate,
+      onChange,
       onClose,
       enablePanDownToClose = true,
       backdropComponent = nullBackdrop,
       animatedIndex: externalAnimatedIndex,
+      index: externalIndex,
       ...props
     },
     ref
   ) => {
     const { id } = useBottomSheetContext();
 
+    const status = useBottomSheetStore((s) => s.sheetsById[id]?.status);
+    const shouldBeClosed = status === 'hidden' || status === 'closing';
+    const index = externalIndex ?? (shouldBeClosed ? -1 : 0);
+
     const animatedIndex = externalAnimatedIndex ?? getAnimatedIndex(id);
-    const { handleAnimate, handleClose } = createSheetEventHandlers(id);
+    const { handleAnimate, handleChange, handleClose } =
+      createSheetEventHandlers(id);
 
     const wrappedOnAnimate: BottomSheetProps['onAnimate'] = (
       fromIndex: number,
@@ -46,6 +54,15 @@ export const BottomSheetManaged = React.forwardRef<
       onAnimate?.(fromIndex, toIndex, fromPosition, toPosition);
     };
 
+    const wrappedOnChange: BottomSheetProps['onChange'] = (
+      index: number,
+      position: number,
+      type
+    ) => {
+      handleChange(index);
+      onChange?.(index, position, type);
+    };
+
     const wrappedOnClose = () => {
       onClose?.();
       handleClose();
@@ -62,7 +79,9 @@ export const BottomSheetManaged = React.forwardRef<
         animationConfigs={config}
         ref={ref}
         {...props}
+        index={index}
         animatedIndex={animatedIndex}
+        onChange={wrappedOnChange}
         onClose={wrappedOnClose}
         onAnimate={wrappedOnAnimate}
         backdropComponent={backdropComponent}
diff --git a/src/BottomSheetPersistent.tsx b/src/BottomSheetPersistent.tsx
new file mode 100644
index 0000000..0515a8b
--- /dev/null
+++ b/src/BottomSheetPersistent.tsx
@@ -0,0 +1,70 @@
+import React, { cloneElement, useEffect, useRef, useState } from 'react';
+import { Portal } from 'react-native-teleport';
+import type { BottomSheetMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
+
+import { BottomSheetContext } from './BottomSheet.context';
+import { useBottomSheetStore } from './bottomSheet.store';
+import { useMaybeBottomSheetManagerContext } from './BottomSheetManager.provider';
+import type { BottomSheetPortalId } from './portal.types';
+import { setSheetRef, cleanupSheetRef } from './refsMap';
+
+interface BottomSheetPersistentProps {
+  id: BottomSheetPortalId;
+  children: React.ReactElement;
+}
+
+export function BottomSheetPersistent({
+  id,
+  children,
+}: BottomSheetPersistentProps) {
+  const bottomSheetManagerContext = useMaybeBottomSheetManagerContext();
+  const mount = useBottomSheetStore((state) => state.mount);
+  const unmount = useBottomSheetStore((state) => state.unmount);
+
+  const sheetExists = useBottomSheetStore(
+    (state) => !!state.sheetsById[id]?.id
+  );
+
+  const sheetRef = useRef<BottomSheetMethods>(null);
+  const [childWithRef, setChildWithRef] = useState<React.ReactElement | null>(
+    null
+  );
+
+  // Clone element with ref in useEffect (not during render)
+  useEffect(() => {
+    setChildWithRef(
+      cloneElement(children, { ref: sheetRef } as { ref: typeof sheetRef })
+    );
+  }, [children]);
+
+  // Mount sheet and sync ref to global refsMap
+  useEffect(() => {
+    const groupId = bottomSheetManagerContext?.groupId || 'default';
+
+    setSheetRef(id, sheetRef);
+    mount({
+      id,
+      groupId,
+      content: null,
+      usePortal: true,
+      keepMounted: true,
+    });
+
+    return () => {
+      unmount(id);
+      cleanupSheetRef(id);
+    };
+  }, [id, bottomSheetManagerContext?.groupId, mount, unmount]);
+
+  if (!sheetExists || !childWithRef) {
+    return null;
+  }
+
+  return (
+    <Portal hostName={`bottomsheet-${id}`}>
+      <BottomSheetContext.Provider value={{ id }}>
+        {childWithRef}
+      </BottomSheetContext.Provider>
+    </Portal>
+  );
+}
diff --git a/src/bottomSheet.store.ts b/src/bottomSheet.store.ts
index 2fecf7e..44414c2 100644
--- a/src/bottomSheet.store.ts
+++ b/src/bottomSheet.store.ts
@@ -13,6 +13,7 @@ export interface BottomSheetState {
   scaleBackground?: boolean;
   usePortal?: boolean;
   params?: Record<string, unknown>;
+  keepMounted?: boolean;
 }
 
 type TriggerState = Omit<BottomSheetState, 'status'>;
@@ -30,10 +31,45 @@ interface BottomSheetStoreActions {
   updateParams(id: string, params: Record<string, unknown> | undefined): void;
   clearGroup(groupId: string): void;
   clearAll(): void;
+  mount(sheet: Omit<BottomSheetState, 'status'>): void;
+  unmount(id: string): void;
 }
 
 export type BottomSheetStore = BottomSheetStoreState & BottomSheetStoreActions;
 
+// --- Pure helper functions (outside store for testability) ---
+
+const MODE_STATUS_MAP: Record<OpenMode, BottomSheetStatus | null> = {
+  push: null,
+  switch: 'hidden',
+  replace: 'closing',
+};
+
+function applyModeToTopSheet(
+  sheetsById: Record<string, BottomSheetState>,
+  stackOrder: string[],
+  mode: OpenMode
+): void {
+  const targetStatus = MODE_STATUS_MAP[mode];
+  if (!targetStatus) return;
+
+  const topId = stackOrder[stackOrder.length - 1];
+  if (!topId) return;
+
+  const topSheet = sheetsById[topId];
+  if (topSheet) {
+    sheetsById[topId] = { ...topSheet, status: targetStatus };
+  }
+}
+
+function isActivatableKeepMounted(
+  sheet: BottomSheetState | undefined
+): sheet is BottomSheetState {
+  return Boolean(sheet?.keepMounted && sheet.status === 'hidden');
+}
+
+// --- Store ---
+
 export const useBottomSheetStore = create(
   subscribeWithSelector<BottomSheetStore>((set) => ({
     sheetsById: {},
@@ -41,28 +77,27 @@ export const useBottomSheetStore = create(
 
     open: (sheet, mode = 'push') =>
       set((state) => {
-        if (state.sheetsById[sheet.id]) {
+        const existingSheet = state.sheetsById[sheet.id];
+
+        // Sheet already active - no-op
+        if (existingSheet && !isActivatableKeepMounted(existingSheet)) {
           return state;
         }
 
         const newSheetsById = { ...state.sheetsById };
-        const topId = state.stackOrder[state.stackOrder.length - 1];
-
-        if (mode === 'switch' && topId && newSheetsById[topId]) {
-          newSheetsById[topId] = {
-            ...newSheetsById[topId],
-            status: 'hidden',
-          };
-        }
+        applyModeToTopSheet(newSheetsById, state.stackOrder, mode);
 
-        if (mode === 'replace' && topId && newSheetsById[topId]) {
-          newSheetsById[topId] = {
-            ...newSheetsById[topId],
-            status: 'closing',
-          };
-        }
+        const newSheet: BottomSheetState = existingSheet
+          ? {
+              ...existingSheet,
+              status: 'opening',
+              scaleBackground:
+                sheet.scaleBackground ?? existingSheet.scaleBackground,
+              params: sheet.params ?? existingSheet.params,
+            }
+          : { ...sheet, status: 'opening' };
 
-        newSheetsById[sheet.id] = { ...sheet, status: 'opening' };
+        newSheetsById[sheet.id] = newSheet;
 
         return {
           sheetsById: newSheetsById,
@@ -107,12 +142,19 @@ export const useBottomSheetStore = create(
 
     finishClosing: (id) =>
       set((state) => {
-        if (!state.sheetsById[id]) {
+        const sheet = state.sheetsById[id];
+        if (!sheet) {
           return state;
         }
 
         const newSheetsById = { ...state.sheetsById };
-        delete newSheetsById[id];
+
+        // For keepMounted sheets, set status to 'hidden' instead of deleting
+        if (sheet.keepMounted) {
+          newSheetsById[id] = { ...sheet, status: 'hidden' };
+        } else {
+          delete newSheetsById[id];
+        }
 
         const newStackOrder = state.stackOrder.filter(
           (sheetId) => sheetId !== id
@@ -147,16 +189,16 @@ export const useBottomSheetStore = create(
 
     clearGroup: (groupId) =>
       set((state) => {
-        const idsToRemove = new Set(
-          state.stackOrder.filter(
-            (id) => state.sheetsById[id]?.groupId === groupId
-          )
+        // Find all sheets in this group (both in stackOrder and keepMounted hidden)
+        const idsInGroup = Object.keys(state.sheetsById).filter(
+          (id) => state.sheetsById[id]?.groupId === groupId
         );
 
-        if (idsToRemove.size === 0) {
+        if (idsInGroup.length === 0) {
           return state;
         }
 
+        const idsToRemove = new Set(idsInGroup);
         const newSheetsById = { ...state.sheetsById };
         idsToRemove.forEach((id) => {
           delete newSheetsById[id];
@@ -169,5 +211,41 @@ export const useBottomSheetStore = create(
       }),
 
     clearAll: () => set(() => ({ sheetsById: {}, stackOrder: [] })),
+
+    mount: (sheet) =>
+      set((state) => {
+        // Don't mount if already exists
+        if (state.sheetsById[sheet.id]) {
+          return state;
+        }
+
+        return {
+          sheetsById: {
+            ...state.sheetsById,
+            [sheet.id]: { ...sheet, status: 'hidden' },
+          },
+        };
+      }),
+
+    unmount: (id) =>
+      set((state) => {
+        const sheet = state.sheetsById[id];
+        if (!sheet) {
+          return state;
+        }
+
+        const newSheetsById = { ...state.sheetsById };
+        delete newSheetsById[id];
+
+        // Also remove from stackOrder if present
+        const newStackOrder = state.stackOrder.filter(
+          (sheetId) => sheetId !== id
+        );
+
+        return {
+          sheetsById: newSheetsById,
+          stackOrder: newStackOrder,
+        };
+      }),
   }))
 );
diff --git a/src/bottomSheetCoordinator.ts b/src/bottomSheetCoordinator.ts
index 484c7e1..f94f603 100644
--- a/src/bottomSheetCoordinator.ts
+++ b/src/bottomSheetCoordinator.ts
@@ -43,19 +43,20 @@ export function createSheetEventHandlers(sheetId: string) {
   const { startClosing, finishClosing, markOpen } =
     useBottomSheetStore.getState();
 
-  const handleAnimate = (fromIndex: number, toIndex: number) => {
+  const handleAnimate = (_fromIndex: number, toIndex: number) => {
     const state = useBottomSheetStore.getState();
     const currentStatus = state.sheetsById[sheetId]?.status;
 
-    // Sheet is closing (animating to -1)
-    if (toIndex === -1) {
-      if (currentStatus === 'open' || currentStatus === 'opening') {
-        startClosing(sheetId);
-      }
+    if (toIndex === -1 && currentStatus === 'open') {
+      startClosing(sheetId);
     }
+  };
+
+  const handleChange = (index: number) => {
+    const state = useBottomSheetStore.getState();
+    const currentStatus = state.sheetsById[sheetId]?.status;
 
-    // Sheet finished opening (animating from -1 to visible)
-    if (fromIndex === -1 && toIndex >= 0) {
+    if (index >= 0 && currentStatus === 'opening') {
       markOpen(sheetId);
     }
   };
@@ -71,6 +72,7 @@ export function createSheetEventHandlers(sheetId: string) {
 
   return {
     handleAnimate,
+    handleChange,
     handleClose,
   };
 }
diff --git a/src/index.tsx b/src/index.tsx
index f7a698a..4d9b423 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -4,6 +4,7 @@ export { BottomSheetHost } from './BottomSheetHost';
 export { BottomSheetScaleView } from './BottomSheetScaleView';
 export { BottomSheetManaged, type BottomSheetRef } from './BottomSheetManaged';
 export { BottomSheetPortal } from './BottomSheetPortal';
+export { BottomSheetPersistent } from './BottomSheetPersistent';
 
 // Hooks
 export { useBottomSheetManager } from './useBottomSheetManager';
diff --git a/src/useBottomSheetControl.ts b/src/useBottomSheetControl.ts
index bb6dd31..306a40b 100644
--- a/src/useBottomSheetControl.ts
+++ b/src/useBottomSheetControl.ts
@@ -8,7 +8,7 @@ import type {
   BottomSheetPortalParams,
   HasParams,
 } from './portal.types';
-import { setSheetRef } from './refsMap';
+import { getSheetRef, setSheetRef } from './refsMap';
 
 interface BaseOpenOptions<TParams> {
   mode?: OpenMode;
@@ -48,8 +48,12 @@ export function useBottomSheetControl<T extends BottomSheetPortalId>(
   const open = (options?: OpenOptions<T>) => {
     const groupId = bottomSheetManagerContext?.groupId || 'default';
 
-    const ref = React.createRef<BottomSheetMethods>();
-    setSheetRef(id, ref);
+    // Only create ref if it doesn't exist (keepMounted sheets already have one)
+    const existingRef = getSheetRef(id);
+    if (!existingRef) {
+      const ref = React.createRef<BottomSheetMethods>();
+      setSheetRef(id, ref);
+    }
 
     storeOpen(
       {

From b5d8e882f963093b30b86522959da9813457d719 Mon Sep 17 00:00:00 2001
From: Arkadiusz Kubaczkowski <arek.kubaczkowski@gmail.com>
Date: Wed, 21 Jan 2026 16:02:44 +0100
Subject: [PATCH 2/7] chore: refactor

---
 example/src/bottom-sheet.d.ts           |   5 +-
 example/src/screens/HomeScreen.tsx      |   7 +-
 example/src/sheets/NavigationSheets.tsx |  14 +++
 example/src/sheets/ScannerSheet.tsx     |  22 +++-
 src/BottomSheet.context.ts              |   4 +-
 src/BottomSheetHost.tsx                 | 141 ++----------------------
 src/BottomSheetManaged.tsx              |   5 +-
 src/BottomSheetPersistent.tsx           |  48 ++++----
 src/BottomSheetRef.context.ts           |  14 +++
 src/QueueItem.tsx                       |  81 ++++++++++++++
 src/animatedRegistry.ts                 |   8 ++
 src/bottomSheet.store.ts                |   2 +-
 src/index.tsx                           |   4 +
 src/refsMap.ts                          |   8 ++
 src/useEvent.ts                         |  17 +++
 src/useScaleAnimation.ts                |   3 +-
 src/useSheetRenderData.ts               |  74 +++++++++++++
 17 files changed, 291 insertions(+), 166 deletions(-)
 create mode 100644 src/BottomSheetRef.context.ts
 create mode 100644 src/QueueItem.tsx
 create mode 100644 src/useEvent.ts
 create mode 100644 src/useSheetRenderData.ts

diff --git a/example/src/bottom-sheet.d.ts b/example/src/bottom-sheet.d.ts
index cbbd7bc..ef2dc84 100644
--- a/example/src/bottom-sheet.d.ts
+++ b/example/src/bottom-sheet.d.ts
@@ -7,6 +7,9 @@ declare module 'react-native-bottom-sheet-stack' {
     };
     'portal-mode-sheet-a': true;
     'portal-mode-sheet-b': true;
-    'scanner-sheet': true;
+    'scanner-sheet': {
+      source: 'home' | 'navigation';
+      title?: string;
+    };
   }
 }
diff --git a/example/src/screens/HomeScreen.tsx b/example/src/screens/HomeScreen.tsx
index c62ceef..5f84839 100644
--- a/example/src/screens/HomeScreen.tsx
+++ b/example/src/screens/HomeScreen.tsx
@@ -118,7 +118,12 @@ export function HomeScreen() {
             title="Persistent Scanner"
             description="Pre-mounted sheet with keepMounted - opens instantly"
             color={colors.cyan}
-            onPress={() => scannerControl.open({ scaleBackground: true })}
+            onPress={() =>
+              scannerControl.open({
+                scaleBackground: true,
+                params: { source: 'home', title: 'Scanner from Home' },
+              })
+            }
           />
         </View>
 
diff --git a/example/src/sheets/NavigationSheets.tsx b/example/src/sheets/NavigationSheets.tsx
index d4ff17f..8376101 100644
--- a/example/src/sheets/NavigationSheets.tsx
+++ b/example/src/sheets/NavigationSheets.tsx
@@ -2,6 +2,7 @@ import type { BottomSheetMethods } from '@gorhom/bottom-sheet/lib/typescript/typ
 import { forwardRef } from 'react';
 import { Text, View } from 'react-native';
 import {
+  useBottomSheetControl,
   useBottomSheetManager,
   useBottomSheetState,
 } from 'react-native-bottom-sheet-stack';
@@ -12,6 +13,7 @@ import { colors, sharedStyles } from '../styles/theme';
 export const SheetA = forwardRef<BottomSheetMethods>((_, ref) => {
   const { openBottomSheet } = useBottomSheetManager();
   const { close } = useBottomSheetState();
+  const scannerSheet = useBottomSheetControl('scanner-sheet');
 
   return (
     <Sheet ref={ref}>
@@ -43,6 +45,18 @@ export const SheetA = forwardRef<BottomSheetMethods>((_, ref) => {
           title="Switch to Sheet B"
           onPress={() => openBottomSheet(<SheetB />, { mode: 'switch' })}
         />
+        <Button
+          title="Open Scanner (Persistent)"
+          onPress={() =>
+            scannerSheet.open({
+              scaleBackground: true,
+              params: {
+                source: 'navigation',
+                title: 'Scanner from Navigation',
+              },
+            })
+          }
+        />
         <SecondaryButton title="Close" onPress={close} />
       </View>
     </Sheet>
diff --git a/example/src/sheets/ScannerSheet.tsx b/example/src/sheets/ScannerSheet.tsx
index b65de0e..87a635f 100644
--- a/example/src/sheets/ScannerSheet.tsx
+++ b/example/src/sheets/ScannerSheet.tsx
@@ -11,11 +11,15 @@ import { ScannerNestedSheet1 } from './ScannerNestedSheets';
 import { colors, sharedStyles } from '../styles/theme';
 
 export const ScannerSheet = forwardRef<BottomSheetMethods>((_, ref) => {
-  const { close } = useBottomSheetContext();
+  const { close, params } = useBottomSheetContext<'scanner-sheet'>();
   const { openBottomSheet } = useBottomSheetManager();
   const [isScanning, setIsScanning] = useState(false);
   const [scanResult, setScanResult] = useState<string | null>(null);
 
+  const title = params?.title ?? 'QR Scanner';
+  const sourceLabel =
+    params?.source === 'navigation' ? 'From Navigation' : 'From Home';
+
   const handleStartScan = useCallback(() => {
     setIsScanning(true);
     setScanResult(null);
@@ -36,8 +40,16 @@ export const ScannerSheet = forwardRef<BottomSheetMethods>((_, ref) => {
 
   return (
     <Sheet ref={ref} enableDynamicSizing>
-      <Badge label="Persistent Sheet" color={colors.cyan} />
-      <Text style={sharedStyles.h1}>QR Scanner</Text>
+      <View style={styles.badgeRow}>
+        <Badge label="Persistent" color={colors.cyan} />
+        <Badge
+          label={sourceLabel}
+          color={
+            params?.source === 'navigation' ? colors.purple : colors.primary
+          }
+        />
+      </View>
+      <Text style={sharedStyles.h1}>{title}</Text>
       <Text style={sharedStyles.text}>
         This sheet is always mounted (keepMounted). It opens instantly without
         mount delay and preserves state between open/close cycles.
@@ -113,6 +125,10 @@ export const ScannerSheet = forwardRef<BottomSheetMethods>((_, ref) => {
 ScannerSheet.displayName = 'ScannerSheet';
 
 const styles = StyleSheet.create({
+  badgeRow: {
+    flexDirection: 'row',
+    gap: 8,
+  },
   scannerViewport: {
     height: 180,
     backgroundColor: colors.background,
diff --git a/src/BottomSheet.context.ts b/src/BottomSheet.context.ts
index 1e58915..f803e7c 100644
--- a/src/BottomSheet.context.ts
+++ b/src/BottomSheet.context.ts
@@ -9,7 +9,5 @@ export const BottomSheetContext = createContext<
 >(undefined);
 
 export function useMaybeBottomSheetContext() {
-  const context = useContext(BottomSheetContext);
-
-  return context;
+  return useContext(BottomSheetContext);
 }
diff --git a/src/BottomSheetHost.tsx b/src/BottomSheetHost.tsx
index 5118f38..4e9ce8d 100644
--- a/src/BottomSheetHost.tsx
+++ b/src/BottomSheetHost.tsx
@@ -1,35 +1,14 @@
 import { useEffect } from 'react';
-import { StyleSheet, View } from 'react-native';
-import Animated from 'react-native-reanimated';
-import { useSafeAreaFrame } from 'react-native-safe-area-context';
-import { PortalHost } from 'react-native-teleport';
 
-import { shallow } from 'zustand/shallow';
-import { cleanupAnimatedIndex } from './animatedRegistry';
-import { BottomSheetContext } from './BottomSheet.context';
 import { useBottomSheetStore } from './bottomSheet.store';
-import { BottomSheetBackdrop } from './BottomSheetBackdrop';
 import { initBottomSheetCoordinator } from './bottomSheetCoordinator';
 import { useBottomSheetManagerContext } from './BottomSheetManager.provider';
-import { cleanupSheetRef } from './refsMap';
-import { useScaleAnimatedStyle } from './useScaleAnimation';
+import { QueueItem } from './QueueItem';
+import { useSheetRenderData } from './useSheetRenderData';
 
-function PortalHostWrapper({
-  id,
-  width,
-  height,
-}: {
-  id: string;
-  width: number;
-  height: number;
-}) {
-  return <PortalHost name={`bottomsheet-${id}`} style={{ width, height }} />;
-}
-
-function BottomSheetHostComp() {
-  const { activeIds, hiddenKeepMountedIds } = useAllSheetIds();
+export function BottomSheetHost() {
+  const sheetRenderData = useSheetRenderData();
   const clearGroup = useBottomSheetStore((store) => store.clearGroup);
-
   const { groupId } = useBottomSheetManagerContext();
 
   useEffect(() => {
@@ -47,112 +26,14 @@ function BottomSheetHostComp() {
 
   return (
     <>
-      {hiddenKeepMountedIds.map((id) => (
-        <QueueItem key={id} id={id} stackIndex={-1} isActive={false} />
-      ))}
-      {activeIds.map((id, index) => (
-        <QueueItem key={id} id={id} stackIndex={index} isActive={true} />
+      {sheetRenderData.map(({ id, stackIndex, isActive }) => (
+        <QueueItem
+          key={id}
+          id={id}
+          stackIndex={stackIndex}
+          isActive={isActive}
+        />
       ))}
     </>
   );
 }
-
-function QueueItem({
-  id,
-  stackIndex,
-  isActive,
-}: {
-  id: string;
-  stackIndex: number;
-  isActive: boolean;
-}) {
-  const { content, usePortal, startClosing, keepMounted } = useBottomSheetStore(
-    (state) => ({
-      content: state.sheetsById[id]?.content,
-      usePortal: state.sheetsById[id]?.usePortal,
-      keepMounted: state.sheetsById[id]?.keepMounted,
-      startClosing: state.startClosing,
-    }),
-    shallow
-  );
-
-  const { width, height } = useSafeAreaFrame();
-  const value = { id };
-  const scaleStyle = useScaleAnimatedStyle({ id });
-
-  useEffect(() => {
-    return () => {
-      if (!keepMounted) {
-        cleanupSheetRef(id);
-        cleanupAnimatedIndex(id);
-      }
-    };
-  }, [id, keepMounted]);
-
-  const backdropZIndex = stackIndex * 2;
-  const contentZIndex = stackIndex * 2 + 1;
-
-  return (
-    <BottomSheetContext.Provider value={value}>
-      {isActive && (
-        <View
-          style={[StyleSheet.absoluteFillObject, { zIndex: backdropZIndex }]}
-          pointerEvents="box-none"
-        >
-          <BottomSheetBackdrop sheetId={id} onPress={() => startClosing(id)} />
-        </View>
-      )}
-
-      {/* Sheet content - rendered with scaling */}
-      <Animated.View
-        pointerEvents="box-none"
-        style={[
-          StyleSheet.absoluteFillObject,
-          styles.container,
-          { width, height, zIndex: contentZIndex },
-          scaleStyle,
-        ]}
-      >
-        {usePortal ? (
-          <PortalHostWrapper id={id} width={width} height={height} />
-        ) : (
-          content
-        )}
-      </Animated.View>
-    </BottomSheetContext.Provider>
-  );
-}
-
-const useAllSheetIds = () => {
-  const { groupId } = useBottomSheetManagerContext();
-
-  return useBottomSheetStore((state) => {
-    // Active sheets from stackOrder
-    const activeIds = state.stackOrder.filter(
-      (sheetId) => state.sheetsById[sheetId]?.groupId === groupId
-    );
-
-    // Hidden keepMounted sheets (in sheetsById but not in stackOrder)
-    const stackOrderSet = new Set(state.stackOrder);
-    const hiddenKeepMountedIds = Object.keys(state.sheetsById).filter(
-      (sheetId) => {
-        const sheet = state.sheetsById[sheetId];
-        return (
-          sheet &&
-          sheet.groupId === groupId &&
-          sheet.keepMounted &&
-          sheet.status === 'hidden' &&
-          !stackOrderSet.has(sheetId)
-        );
-      }
-    );
-
-    return { activeIds, hiddenKeepMountedIds };
-  }, shallow);
-};
-
-export const BottomSheetHost = BottomSheetHostComp;
-
-const styles = StyleSheet.create({
-  container: {},
-});
diff --git a/src/BottomSheetManaged.tsx b/src/BottomSheetManaged.tsx
index ac7342e..5f1d119 100644
--- a/src/BottomSheetManaged.tsx
+++ b/src/BottomSheetManaged.tsx
@@ -8,6 +8,7 @@ import React from 'react';
 import { getAnimatedIndex } from './animatedRegistry';
 import { useBottomSheetStore } from './bottomSheet.store';
 import { createSheetEventHandlers } from './bottomSheetCoordinator';
+import { useBottomSheetRefContext } from './BottomSheetRef.context';
 import { useBottomSheetContext } from './useBottomSheetContext';
 
 export interface BottomSheetRef extends BottomSheetMethods {}
@@ -32,9 +33,11 @@ export const BottomSheetManaged = React.forwardRef<
       index: externalIndex,
       ...props
     },
-    ref
+    forwardedRef
   ) => {
     const { id } = useBottomSheetContext();
+    const contextRef = useBottomSheetRefContext();
+    const ref = contextRef ?? forwardedRef;
 
     const status = useBottomSheetStore((s) => s.sheetsById[id]?.status);
     const shouldBeClosed = status === 'hidden' || status === 'closing';
diff --git a/src/BottomSheetPersistent.tsx b/src/BottomSheetPersistent.tsx
index 0515a8b..66b3fb5 100644
--- a/src/BottomSheetPersistent.tsx
+++ b/src/BottomSheetPersistent.tsx
@@ -1,12 +1,15 @@
-import React, { cloneElement, useEffect, useRef, useState } from 'react';
+import React, { useEffect, useLayoutEffect, useRef } from 'react';
 import { Portal } from 'react-native-teleport';
 import type { BottomSheetMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
 
 import { BottomSheetContext } from './BottomSheet.context';
+import { BottomSheetRefContext } from './BottomSheetRef.context';
 import { useBottomSheetStore } from './bottomSheet.store';
 import { useMaybeBottomSheetManagerContext } from './BottomSheetManager.provider';
 import type { BottomSheetPortalId } from './portal.types';
 import { setSheetRef, cleanupSheetRef } from './refsMap';
+import { cleanupAnimatedIndex } from './animatedRegistry';
+import { useEvent } from './useEvent';
 
 interface BottomSheetPersistentProps {
   id: BottomSheetPortalId;
@@ -26,44 +29,39 @@ export function BottomSheetPersistent({
   );
 
   const sheetRef = useRef<BottomSheetMethods>(null);
-  const [childWithRef, setChildWithRef] = useState<React.ReactElement | null>(
-    null
-  );
-
-  // Clone element with ref in useEffect (not during render)
-  useEffect(() => {
-    setChildWithRef(
-      cloneElement(children, { ref: sheetRef } as { ref: typeof sheetRef })
-    );
-  }, [children]);
-
-  // Mount sheet and sync ref to global refsMap
-  useEffect(() => {
-    const groupId = bottomSheetManagerContext?.groupId || 'default';
+  const groupId = bottomSheetManagerContext?.groupId || 'default';
 
+  const mountSheet = useEvent(() => {
     setSheetRef(id, sheetRef);
-    mount({
-      id,
-      groupId,
-      content: null,
-      usePortal: true,
-      keepMounted: true,
-    });
+    mount({ id, groupId, content: null, usePortal: true, keepMounted: true });
+  });
 
+  useLayoutEffect(() => {
+    mountSheet();
     return () => {
       unmount(id);
       cleanupSheetRef(id);
+      cleanupAnimatedIndex(id);
     };
-  }, [id, bottomSheetManagerContext?.groupId, mount, unmount]);
+  }, [id, groupId, mount, unmount, mountSheet]);
+
+  // Re-mount if sheet was removed externally (e.g., by clearGroup during fast refresh)
+  useEffect(() => {
+    if (!sheetExists) {
+      mountSheet();
+    }
+  }, [sheetExists, id, groupId, mount, mountSheet]);
 
-  if (!sheetExists || !childWithRef) {
+  if (!sheetExists) {
     return null;
   }
 
   return (
     <Portal hostName={`bottomsheet-${id}`}>
       <BottomSheetContext.Provider value={{ id }}>
-        {childWithRef}
+        <BottomSheetRefContext.Provider value={sheetRef}>
+          {children}
+        </BottomSheetRefContext.Provider>
       </BottomSheetContext.Provider>
     </Portal>
   );
diff --git a/src/BottomSheetRef.context.ts b/src/BottomSheetRef.context.ts
new file mode 100644
index 0000000..f28d6e7
--- /dev/null
+++ b/src/BottomSheetRef.context.ts
@@ -0,0 +1,14 @@
+import { createContext, useContext, type RefObject } from 'react';
+import type { BottomSheetMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
+
+type SheetRef = RefObject<BottomSheetMethods | null>;
+
+/**
+ * Context for passing sheet ref from BottomSheetPersistent/BottomSheetPortal
+ * to BottomSheetManaged. This allows automatic ref binding without user intervention.
+ */
+export const BottomSheetRefContext = createContext<SheetRef | null>(null);
+
+export function useBottomSheetRefContext(): SheetRef | null {
+  return useContext(BottomSheetRefContext);
+}
diff --git a/src/QueueItem.tsx b/src/QueueItem.tsx
new file mode 100644
index 0000000..9f95ce4
--- /dev/null
+++ b/src/QueueItem.tsx
@@ -0,0 +1,81 @@
+import { useEffect } from 'react';
+import { StyleSheet, View } from 'react-native';
+import Animated from 'react-native-reanimated';
+import { useSafeAreaFrame } from 'react-native-safe-area-context';
+import { PortalHost } from 'react-native-teleport';
+import { shallow } from 'zustand/shallow';
+
+import { cleanupAnimatedIndex } from './animatedRegistry';
+import { BottomSheetContext } from './BottomSheet.context';
+import { useBottomSheetStore } from './bottomSheet.store';
+import { BottomSheetBackdrop } from './BottomSheetBackdrop';
+import { cleanupSheetRef } from './refsMap';
+import { useScaleAnimatedStyle } from './useScaleAnimation';
+
+interface QueueItemProps {
+  id: string;
+  stackIndex: number;
+  isActive: boolean;
+}
+
+export function QueueItem({ id, stackIndex, isActive }: QueueItemProps) {
+  const { content, usePortal, startClosing, keepMounted } = useBottomSheetStore(
+    (state) => ({
+      content: state.sheetsById[id]?.content,
+      usePortal: state.sheetsById[id]?.usePortal,
+      keepMounted: state.sheetsById[id]?.keepMounted,
+      startClosing: state.startClosing,
+    }),
+    shallow
+  );
+
+  const { width, height } = useSafeAreaFrame();
+  const scaleStyle = useScaleAnimatedStyle({ id });
+
+  useEffect(() => {
+    return () => {
+      if (!keepMounted) {
+        cleanupSheetRef(id);
+        cleanupAnimatedIndex(id);
+      }
+    };
+  }, [id, keepMounted]);
+
+  const backdropZIndex = stackIndex * 2;
+  const contentZIndex = stackIndex * 2 + 1;
+
+  return (
+    <>
+      {isActive && (
+        <View
+          style={[StyleSheet.absoluteFillObject, { zIndex: backdropZIndex }]}
+          pointerEvents="box-none"
+        >
+          <BottomSheetBackdrop sheetId={id} onPress={() => startClosing(id)} />
+        </View>
+      )}
+
+      <Animated.View
+        pointerEvents="box-none"
+        style={[
+          StyleSheet.absoluteFillObject,
+          styles.container,
+          { width, height, zIndex: contentZIndex },
+          scaleStyle,
+        ]}
+      >
+        {usePortal ? (
+          <PortalHost name={`bottomsheet-${id}`} style={{ width, height }} />
+        ) : (
+          <BottomSheetContext.Provider value={{ id }}>
+            {content}
+          </BottomSheetContext.Provider>
+        )}
+      </Animated.View>
+    </>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {},
+});
diff --git a/src/animatedRegistry.ts b/src/animatedRegistry.ts
index 57c5bce..91b3e4d 100644
--- a/src/animatedRegistry.ts
+++ b/src/animatedRegistry.ts
@@ -20,3 +20,11 @@ export function getAnimatedIndex(sheetId: string): SharedValue<number> {
 export function cleanupAnimatedIndex(sheetId: string): void {
   animatedIndexRegistry.delete(sheetId);
 }
+
+/**
+ * Reset all animated indexes. Useful for testing.
+ * @internal
+ */
+export function __resetAnimatedIndexes(): void {
+  animatedIndexRegistry.clear();
+}
diff --git a/src/bottomSheet.store.ts b/src/bottomSheet.store.ts
index 44414c2..123817b 100644
--- a/src/bottomSheet.store.ts
+++ b/src/bottomSheet.store.ts
@@ -8,7 +8,7 @@ export type OpenMode = 'push' | 'switch' | 'replace';
 export interface BottomSheetState {
   groupId: string;
   id: string;
-  content: ReactNode;
+  content?: ReactNode;
   status: BottomSheetStatus;
   scaleBackground?: boolean;
   usePortal?: boolean;
diff --git a/src/index.tsx b/src/index.tsx
index 4d9b423..d83a40e 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -34,3 +34,7 @@ export type {
   BottomSheetPortalId,
   BottomSheetPortalParams,
 } from './portal.types';
+
+// Testing utilities (internal use)
+export { __resetSheetRefs } from './refsMap';
+export { __resetAnimatedIndexes } from './animatedRegistry';
diff --git a/src/refsMap.ts b/src/refsMap.ts
index 92bfef6..49f3521 100644
--- a/src/refsMap.ts
+++ b/src/refsMap.ts
@@ -16,3 +16,11 @@ export function setSheetRef(sheetId: string, ref: SheetRef): void {
 export function cleanupSheetRef(sheetId: string): void {
   sheetRefsMap.delete(sheetId);
 }
+
+/**
+ * Reset all sheet refs. Useful for testing.
+ * @internal
+ */
+export function __resetSheetRefs(): void {
+  sheetRefsMap.clear();
+}
diff --git a/src/useEvent.ts b/src/useEvent.ts
new file mode 100644
index 0000000..379c778
--- /dev/null
+++ b/src/useEvent.ts
@@ -0,0 +1,17 @@
+import { useCallback, useLayoutEffect, useRef } from 'react';
+
+// biome-ignore lint/suspicious/noExplicitAny: No better alternative available.
+type CallbackType = (...args: any[]) => any;
+
+// RFC: https://github.com/reactjs/rfcs/blob/useevent/text/0000-useevent.md
+export const useEvent = <T extends CallbackType>(callback: T) => {
+  const callbackRef = useRef(callback);
+
+  useLayoutEffect(() => {
+    callbackRef.current = callback;
+  });
+
+  return useCallback((...args: Parameters<T>): ReturnType<T> => {
+    return callbackRef.current(...args);
+  }, []);
+};
diff --git a/src/useScaleAnimation.ts b/src/useScaleAnimation.ts
index f23eb14..6a20d0d 100644
--- a/src/useScaleAnimation.ts
+++ b/src/useScaleAnimation.ts
@@ -66,7 +66,8 @@ export function useScaleDepth(groupId: string, sheetId?: string): number {
         sheet &&
         sheet.groupId === groupId &&
         sheet.scaleBackground &&
-        sheet.status !== 'closing'
+        sheet.status !== 'closing' &&
+        sheet.status !== 'hidden'
       ) {
         depth++;
         if (!sheetId) {
diff --git a/src/useSheetRenderData.ts b/src/useSheetRenderData.ts
new file mode 100644
index 0000000..2f2e6f4
--- /dev/null
+++ b/src/useSheetRenderData.ts
@@ -0,0 +1,74 @@
+import { shallow } from 'zustand/shallow';
+import {
+  useBottomSheetStore,
+  type BottomSheetState,
+} from './bottomSheet.store';
+import { useBottomSheetManagerContext } from './BottomSheetManager.provider';
+
+export interface SheetRenderItem {
+  id: string;
+  stackIndex: number;
+  isActive: boolean;
+}
+
+/**
+ * Returns a flat list of sheets to render.
+ *
+ * Each sheet appears exactly once - this prevents React from
+ * unmounting/remounting when a sheet transitions between states.
+ *
+ * Render order:
+ * 1. Hidden persistent sheets (keepMounted=true, not in stack)
+ * 2. Active sheets (in stackOrder)
+ */
+export function useSheetRenderData(): SheetRenderItem[] {
+  const { groupId } = useBottomSheetManagerContext();
+
+  return useBottomSheetStore((state) => {
+    const hiddenPersistent = getHiddenPersistentSheets(state, groupId);
+    const active = getActiveSheets(state, groupId);
+
+    return [...hiddenPersistent, ...active];
+  }, shallow);
+}
+
+function getHiddenPersistentSheets(
+  state: { sheetsById: Record<string, BottomSheetState>; stackOrder: string[] },
+  groupId: string
+): SheetRenderItem[] {
+  const inStack = new Set(state.stackOrder);
+
+  return Object.values(state.sheetsById)
+    .filter((sheet) => isHiddenPersistent(sheet, groupId, inStack))
+    .map((sheet) => ({
+      id: sheet.id,
+      stackIndex: -1,
+      isActive: false,
+    }));
+}
+
+function isHiddenPersistent(
+  sheet: BottomSheetState,
+  groupId: string,
+  inStack: Set<string>
+): boolean {
+  const belongsToGroup = sheet.groupId === groupId;
+  const isPersistent = sheet.keepMounted === true;
+  const isHidden = sheet.status === 'hidden';
+  const isNotInStack = !inStack.has(sheet.id);
+
+  return belongsToGroup && isPersistent && isHidden && isNotInStack;
+}
+
+function getActiveSheets(
+  state: { sheetsById: Record<string, BottomSheetState>; stackOrder: string[] },
+  groupId: string
+): SheetRenderItem[] {
+  return state.stackOrder
+    .filter((id) => state.sheetsById[id]?.groupId === groupId)
+    .map((id, index) => ({
+      id,
+      stackIndex: index,
+      isActive: true,
+    }));
+}

From 84665b0883324a0cf14d01351cc2af4c269be216 Mon Sep 17 00:00:00 2001
From: Arkadiusz Kubaczkowski <arek.kubaczkowski@gmail.com>
Date: Wed, 21 Jan 2026 16:07:52 +0100
Subject: [PATCH 3/7] chore: update docs

---
 README.md                      |  16 +--
 docs/docs/api/components.md    |  49 ++++++++++
 docs/docs/persistent-sheets.md | 172 +++++++++++++++++++++++++++++++++
 docs/sidebars.ts               |   1 +
 4 files changed, 231 insertions(+), 7 deletions(-)
 create mode 100644 docs/docs/persistent-sheets.md

diff --git a/README.md b/README.md
index 6761153..e0d3a14 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 A stack manager for [@gorhom/bottom-sheet](https://github.com/gorhom/react-native-bottom-sheet) with navigation modes, iOS-style scale animations, and React context preservation.
 
-## Documentation
+## 📚 Documentation
 
 **[View Full Documentation](https://arekkubaczkowski.github.io/react-native-bottom-sheet-stack/)**
 
@@ -10,16 +10,18 @@ A stack manager for [@gorhom/bottom-sheet](https://github.com/gorhom/react-nativ
 - [Navigation Modes](https://arekkubaczkowski.github.io/react-native-bottom-sheet-stack/navigation-modes)
 - [Scale Animation](https://arekkubaczkowski.github.io/react-native-bottom-sheet-stack/scale-animation)
 - [Portal API (Context Preservation)](https://arekkubaczkowski.github.io/react-native-bottom-sheet-stack/context-preservation)
+- [Persistent Sheets](https://arekkubaczkowski.github.io/react-native-bottom-sheet-stack/persistent-sheets)
 - [Type-Safe IDs & Params](https://arekkubaczkowski.github.io/react-native-bottom-sheet-stack/type-safe-ids)
 - [API Reference](https://arekkubaczkowski.github.io/react-native-bottom-sheet-stack/api/components)
 
-## Features
+## ✨ Features
 
-- **Stack Navigation** - `push`, `switch`, and `replace` modes for managing multiple sheets
-- **Scale Animation** - iOS-style background scaling effect when sheets are stacked
-- **Context Preservation** - Portal-based API that preserves React context in bottom sheets
-- **Type-Safe** - Full TypeScript support with type-safe portal IDs and params
-- **Group Support** - Isolated stacks for different parts of your app
+- 📚 **Stack Navigation** - `push`, `switch`, and `replace` modes for managing multiple sheets
+- 🎭 **Scale Animation** - iOS-style background scaling effect when sheets are stacked
+- 🔗 **Context Preservation** - Portal-based API that preserves React context in bottom sheets
+- ⚡ **Persistent Sheets** - Pre-mounted sheets that open instantly and preserve state
+- 🔒 **Type-Safe** - Full TypeScript support with type-safe portal IDs and params
+- 📦 **Group Support** - Isolated stacks for different parts of your app
 
 ## Installation
 
diff --git a/docs/docs/api/components.md b/docs/docs/api/components.md
index 29fe526..e0df393 100644
--- a/docs/docs/api/components.md
+++ b/docs/docs/api/components.md
@@ -98,3 +98,52 @@ Declares a portal-based bottom sheet that preserves React context.
 | `children` | `ReactElement` | Yes | The bottom sheet component to render |
 
 See [Type-Safe Portal IDs](/type-safe-ids) for type-safe ID configuration.
+
+---
+
+## BottomSheetPersistent
+
+Declares a persistent bottom sheet that stays mounted even when closed. Opens instantly and preserves internal state between open/close cycles.
+
+```tsx
+<BottomSheetPersistent id="scanner">
+  <ScannerSheet />
+</BottomSheetPersistent>
+```
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `BottomSheetPortalId` | Yes | Unique identifier for this persistent sheet |
+| `children` | `ReactElement` | Yes | The bottom sheet component to render |
+
+### Placement
+
+Can be placed anywhere inside `BottomSheetManagerProvider`. Must stay mounted to be accessible.
+
+```tsx
+// At app root - always available
+<BottomSheetManagerProvider id="main">
+  <BottomSheetScaleView>
+    <App />
+  </BottomSheetScaleView>
+  <BottomSheetHost />
+  <BottomSheetPersistent id="scanner">
+    <ScannerSheet />
+  </BottomSheetPersistent>
+</BottomSheetManagerProvider>
+
+// Or on a specific screen
+function HomeScreen() {
+  return (
+    <View>
+      <BottomSheetPersistent id="quick-actions">
+        <QuickActionsSheet />
+      </BottomSheetPersistent>
+    </View>
+  );
+}
+```
+
+See [Persistent Sheets](/persistent-sheets) for detailed usage.
diff --git a/docs/docs/persistent-sheets.md b/docs/docs/persistent-sheets.md
new file mode 100644
index 0000000..3011554
--- /dev/null
+++ b/docs/docs/persistent-sheets.md
@@ -0,0 +1,172 @@
+---
+sidebar_position: 7
+---
+
+# Persistent Sheets
+
+Persistent sheets are **pre-mounted** bottom sheets that stay in memory even when closed. They open instantly without mount delay and preserve their internal state between open/close cycles.
+
+## When to Use
+
+- **Frequently accessed sheets** - Scanner, camera, quick actions
+- **State preservation** - Forms, multi-step wizards, media players
+- **Instant open** - When mount delay is noticeable
+
+## Basic Usage
+
+```tsx
+import {
+  BottomSheetPersistent,
+  useBottomSheetControl,
+} from 'react-native-bottom-sheet-stack';
+
+function App() {
+  return (
+    <BottomSheetManagerProvider id="main">
+      <BottomSheetScaleView>
+        <HomeScreen />
+      </BottomSheetScaleView>
+      <BottomSheetHost />
+
+      {/* Persistent sheet - always mounted */}
+      <BottomSheetPersistent id="scanner">
+        <ScannerSheet />
+      </BottomSheetPersistent>
+    </BottomSheetManagerProvider>
+  );
+}
+
+function HomeScreen() {
+  const scanner = useBottomSheetControl('scanner');
+
+  return (
+    <Button
+      title="Open Scanner"
+      onPress={() => scanner.open({ scaleBackground: true })}
+    />
+  );
+}
+```
+
+## State Preservation
+
+Internal component state is preserved between open/close cycles:
+
+```tsx
+const ScannerSheet = forwardRef((props, ref) => {
+  const { close } = useBottomSheetContext();
+  // State is preserved when sheet is closed and reopened
+  const [scanResult, setScanResult] = useState<string | null>(null);
+  const [isScanning, setIsScanning] = useState(false);
+
+  const handleScan = () => {
+    setIsScanning(true);
+    // ... scanning logic
+    setScanResult('QR-ABC123');
+    setIsScanning(false);
+  };
+
+  return (
+    <BottomSheetManaged ref={ref} enableDynamicSizing>
+      <View>
+        {scanResult ? (
+          <Text>Result: {scanResult}</Text>
+        ) : (
+          <Button title="Start Scan" onPress={handleScan} />
+        )}
+        <Button title="Close" onPress={close} />
+      </View>
+    </BottomSheetManaged>
+  );
+});
+```
+
+Close the sheet and reopen it - `scanResult` is still there.
+
+
+## Comparison with Portal API
+
+| Feature | `BottomSheetPortal` | `BottomSheetPersistent` |
+|---------|--------------------|-----------------------|
+| Context preservation | ✅ | ✅ |
+| State preservation | ❌ (remounts) | ✅ |
+| Instant open | ❌ | ✅ |
+| Memory usage | Lower | Higher |
+| Best for | Regular sheets | Frequently used sheets |
+
+## Passing Params
+
+You can pass params when opening:
+
+```tsx
+const scanner = useBottomSheetControl('scanner');
+
+scanner.open({
+  scaleBackground: true,
+  params: { source: 'home', title: 'Scan QR Code' },
+});
+```
+
+Access them in the sheet:
+
+```tsx
+const ScannerSheet = forwardRef((props, ref) => {
+  const { params } = useBottomSheetContext<'scanner'>();
+
+  return (
+    <BottomSheetManaged ref={ref}>
+      <Text>{params?.title ?? 'Scanner'}</Text>
+    </BottomSheetManaged>
+  );
+});
+```
+
+## Type Safety
+
+Register your persistent sheet IDs for type-safe params:
+
+```tsx
+// bottom-sheet.d.ts
+declare module 'react-native-bottom-sheet-stack' {
+  interface BottomSheetPortalRegistry {
+    scanner: { source: 'home' | 'navigation'; title?: string };
+  }
+}
+```
+
+Now `useBottomSheetControl('scanner')` has typed `open()` and `params`.
+
+## Placement
+
+`BottomSheetPersistent` can be placed **anywhere** inside `BottomSheetManagerProvider` - at the app root, on a specific screen, or nested deep in your component tree.
+
+The only requirement: **it must stay mounted** to be accessible. If you unmount it, the sheet won't be available until it mounts again.
+
+```tsx
+// Option 1: At app root - always available
+<BottomSheetManagerProvider id="main">
+  <BottomSheetScaleView>
+    <App />
+  </BottomSheetScaleView>
+  <BottomSheetHost />
+  <BottomSheetPersistent id="scanner">
+    <ScannerSheet />
+  </BottomSheetPersistent>
+</BottomSheetManagerProvider>
+
+// Option 2: On a specific screen - available only when screen is mounted
+function HomeScreen() {
+  return (
+    <View>
+      <BottomSheetPersistent id="quick-actions">
+        <QuickActionsSheet />
+      </BottomSheetPersistent>
+      {/* ... screen content */}
+    </View>
+  );
+}
+```
+
+:::tip
+For sheets that should be accessible from anywhere in your app, place them at the root level to ensure they're always mounted.
+:::
diff --git a/docs/sidebars.ts b/docs/sidebars.ts
index 10182aa..f2f2948 100644
--- a/docs/sidebars.ts
+++ b/docs/sidebars.ts
@@ -8,6 +8,7 @@ const sidebars: SidebarsConfig = {
     'navigation-modes',
     'scale-animation',
     'context-preservation',
+    'persistent-sheets',
     'type-safe-ids',
     {
       type: 'category',

From 8833b94bdf6e89a54adaac52b282847b2063a515 Mon Sep 17 00:00:00 2001
From: Arkadiusz Kubaczkowski <arek.kubaczkowski@gmail.com>
Date: Thu, 22 Jan 2026 07:53:50 +0100
Subject: [PATCH 4/7] chore: store refactor

---
 CLAUDE.md                     | 809 ++++++++++++++++++++++++++++++++++
 src/BottomSheetBackdrop.tsx   |  11 +-
 src/BottomSheetHost.tsx       |   4 +-
 src/BottomSheetManaged.tsx    |   4 +-
 src/BottomSheetPersistent.tsx |  11 +-
 src/BottomSheetPortal.tsx     |   6 +-
 src/QueueItem.tsx             |  21 +-
 src/bottomSheet.store.ts      | 252 +----------
 src/store/helpers.ts          |  61 +++
 src/store/hooks.ts            |  51 +++
 src/store/index.ts            |   4 +
 src/store/store.ts            | 159 +++++++
 src/store/types.ts            |  36 ++
 src/useBottomSheetContext.ts  |  16 +-
 src/useBottomSheetControl.ts  |  13 +-
 src/useBottomSheetManager.tsx |  19 +-
 src/useBottomSheetStatus.ts   |  10 +-
 17 files changed, 1170 insertions(+), 317 deletions(-)
 create mode 100644 CLAUDE.md
 create mode 100644 src/store/helpers.ts
 create mode 100644 src/store/hooks.ts
 create mode 100644 src/store/index.ts
 create mode 100644 src/store/store.ts
 create mode 100644 src/store/types.ts

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..b6e0e20
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,809 @@
+# CLAUDE.md - LLM Guide for react-native-bottom-sheet-stack
+
+## CRITICAL: React Compiler - NO MANUAL MEMOIZATION
+
+**This project uses React Compiler (`babel-plugin-react-compiler` v1.0.0) with React 19.**
+
+### DO NOT USE:
+- `React.memo()`
+- `useMemo()`
+- `useCallback()`
+- `memo()` HOC
+- Any manual memoization patterns
+
+### WHY:
+React Compiler automatically handles all memoization at build time. Manual memoization is:
+1. **Redundant** - Compiler does it better
+2. **Harmful** - Can conflict with compiler optimizations
+3. **Unnecessary** - Compiler tracks dependencies automatically
+
+### Babel Configuration (babel.config.js):
+```javascript
+plugins: [
+  ['babel-plugin-react-compiler', {
+    target: '19',
+    panicThreshold: 'all_errors',  // Strict mode
+  }],
+]
+```
+
+### When Compiler Cannot Optimize:
+Use the `'use no memo'` directive at the top of the file (see `BottomSheetPortal.tsx` for example). This is RARE and only needed when:
+- Dynamic ref cloning breaks compiler analysis
+- External library integration requires it
+
+---
+
+## Project Overview
+
+A sophisticated stack manager for bottom sheets built on `@gorhom/bottom-sheet`. Provides:
+- **Navigation modes**: push, switch, replace
+- **iOS-style scale animations**: Background content scales when sheets open
+- **Context preservation**: Via portals (`react-native-teleport`)
+- **Persistent sheets**: Pre-mounted sheets that maintain state across open/close cycles
+- **Type-safe APIs**: TypeScript with augmentable type registry
+
+### Tech Stack
+| Category | Package | Version |
+|----------|---------|---------|
+| React | react | 19.1.0 |
+| React Native | react-native | 0.81.5 |
+| Bottom Sheet | @gorhom/bottom-sheet | ^5.2.8 |
+| Animation | react-native-reanimated | ^4.2.1 |
+| State | zustand | ^5.0.3 |
+| Portals | react-native-teleport | ^0.5.6 |
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    BottomSheetManagerProvider                    │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │                    PortalProvider                         │   │
+│  │  ┌────────────────────────────────────────────────────┐  │   │
+│  │  │          BottomSheetManagerContext                  │  │   │
+│  │  │  (groupId, scaleConfig)                            │  │   │
+│  │  └────────────────────────────────────────────────────┘  │   │
+│  └─────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+         ┌────────────────────┴────────────────────┐
+         ▼                                         ▼
+┌─────────────────────┐                 ┌─────────────────────┐
+│  BottomSheetScaleView │                 │   BottomSheetHost   │
+│  (wraps app content)  │                 │   (renders sheets)  │
+└─────────────────────┘                 └─────────────────────┘
+                                                   │
+                    ┌──────────────────────────────┴──────────────────────────────┐
+                    ▼                              ▼                              ▼
+          ┌─────────────────┐          ┌─────────────────┐          ┌─────────────────┐
+          │    QueueItem    │          │    QueueItem    │          │    QueueItem    │
+          │  (sheet slot)   │          │  (sheet slot)   │          │  (sheet slot)   │
+          │   zIndex: 0,1   │          │   zIndex: 2,3   │          │   zIndex: 4,5   │
+          └─────────────────┘          └─────────────────┘          └─────────────────┘
+                    │
+         ┌──────────┴──────────┐
+         ▼                     ▼
+┌─────────────────┐   ┌─────────────────┐
+│ PortalHost      │   │ Inline Content  │
+│ (portal mode)   │   │ (dynamic mode)  │
+└─────────────────┘   └─────────────────┘
+```
+
+---
+
+## Source File Guide (`src/`)
+
+### Core State Management
+
+#### `bottomSheet.store.ts` - Central Zustand Store
+**Purpose**: Single source of truth for all sheet state and stack ordering.
+
+**State Structure**:
+```typescript
+interface BottomSheetStoreState {
+  sheetsById: Record<string, BottomSheetState>;  // All sheets by ID
+  stackOrder: string[];                           // Visible sheet IDs in order
+}
+
+interface BottomSheetState {
+  groupId: string;              // Manager group ID
+  id: string;                   // Unique sheet ID
+  content?: ReactNode;          // For inline mode only
+  status: BottomSheetStatus;    // 'opening' | 'open' | 'closing' | 'hidden'
+  scaleBackground?: boolean;    // Enable iOS-style scale
+  usePortal?: boolean;          // Portal mode flag
+  params?: Record<string, unknown>;  // Type-safe params
+  keepMounted?: boolean;        // Persistent sheet flag
+}
+```
+
+**Key Actions**:
+- `open(sheet, mode)` - Opens sheet with navigation mode
+- `markOpen(id)` - Transitions 'opening' → 'open'
+- `startClosing(id)` - Initiates close animation
+- `finishClosing(id)` - Completes close (hides if keepMounted, removes otherwise)
+- `mount(sheet)` - Pre-mounts persistent sheet with 'hidden' status
+- `unmount(id)` - Removes persistent sheet
+
+**Navigation Modes** (`OpenMode`):
+- `push` - Keeps previous sheet visible (stacking)
+- `switch` - Hides previous sheet (hidden status, not removed)
+- `replace` - Closes previous sheet (closing status, then removed)
+
+#### `bottomSheetCoordinator.ts` - State↔UI Synchronization
+**Purpose**: Bidirectional sync between Zustand store and gorhom bottom sheet.
+
+**Two Directions**:
+1. **Store → Gorhom** (`initBottomSheetCoordinator`):
+   - Subscribes to store changes
+   - Calls `ref.expand()` when status becomes 'opening'
+   - Calls `ref.close()` when status becomes 'hidden' or 'closing'
+
+2. **Gorhom → Store** (`createSheetEventHandlers`):
+   - `handleAnimate`: User swipes down → `startClosing()`
+   - `handleChange`: Animation completes → `markOpen()`
+   - `handleClose`: Sheet fully closed → `finishClosing()`
+
+### Global Registries (Module-Level Maps)
+
+#### `refsMap.ts` - Sheet Reference Registry
+```typescript
+const sheetRefsMap = new Map<string, RefObject<BottomSheetMethods>>();
+```
+**Why**: Refs cannot be stored in Zustand (not serializable). Global map allows coordinator to access refs by sheet ID.
+
+#### `animatedRegistry.ts` - Animated Index Registry
+```typescript
+const animatedIndexRegistry = new Map<string, SharedValue<number>>();
+```
+**Why**: Shared animated values for backdrop opacity interpolation. Created lazily via `getAnimatedIndex(id)`.
+
+### Components
+
+#### `BottomSheetManagerProvider.tsx` - Root Provider
+Wraps app with:
+- `PortalProvider` (from react-native-teleport)
+- `BottomSheetManagerContext` (groupId, scaleConfig)
+
+#### `BottomSheetHost.tsx` - Sheet Queue Renderer
+**Purpose**: Renders active sheets from store.
+**Responsibilities**:
+- Initializes coordinator subscription
+- Clears group on unmount
+- Renders QueueItems for each sheet
+
+#### `QueueItem.tsx` - Individual Sheet Slot
+**Purpose**: Single sheet rendering with proper z-index layering.
+
+**Z-Index Strategy**:
+```typescript
+const backdropZIndex = stackIndex * 2;     // Even numbers: 0, 2, 4...
+const contentZIndex = stackIndex * 2 + 1;  // Odd numbers: 1, 3, 5...
+```
+This ensures backdrop always renders below its sheet's content.
+
+**Rendering Modes**:
+- **Portal Mode** (`usePortal: true`): Renders `<PortalHost>` that receives content from `BottomSheetPortal`
+- **Inline Mode** (`usePortal: false`): Renders content directly with `BottomSheetContext.Provider`
+
+#### `BottomSheetManaged.tsx` - Gorhom Sheet Wrapper
+**Purpose**: Wraps `@gorhom/bottom-sheet` with coordinator integration.
+
+**Key Features**:
+- Auto-wires event handlers to coordinator
+- Reads status from store to control `index` prop
+- Uses `useBottomSheetSpringConfigs` for smooth animations
+- Supports both forwarded ref and context ref
+
+#### `BottomSheetPortal.tsx` - Portal Mode Sheet Definition
+**Uses `'use no memo'` directive** - Compiler cannot optimize due to dynamic ref cloning.
+
+**Purpose**: Defines portal-based sheet content. Renders into PortalHost in QueueItem.
+**When to use**: When sheet needs access to parent React context (Redux, custom contexts, etc.)
+
+#### `BottomSheetPersistent.tsx` - Pre-Mounted Persistent Sheet
+**Purpose**: Sheet that stays mounted even when closed.
+
+**Lifecycle**:
+1. On mount: `mount()` action creates sheet with `status: 'hidden'`, `keepMounted: true`
+2. On open: Store moves to stack, status → 'opening'
+3. On close: Status → 'hidden' (NOT removed from sheetsById)
+4. On unmount: `unmount()` action removes from store
+
+**Use Case**: Sheets with heavy state (forms, media players) that need to preserve state.
+
+#### `BottomSheetScaleView.tsx` - Background Scale Animation
+**Purpose**: Wraps app content to apply iOS-style scale animation.
+**Note**: Must be sibling to `BottomSheetHost`, not parent.
+
+#### `BottomSheetBackdrop.tsx` - Custom Backdrop
+**Purpose**: Animated backdrop with opacity based on sheet's animatedIndex.
+**Key**: Only interactive when status is 'open' (prevents animation conflicts).
+
+### Hooks
+
+#### `useBottomSheetManager.tsx` - Dynamic Sheet Opening
+**Purpose**: Imperative API for opening sheets with content.
+
+```typescript
+const { open, close, clear } = useBottomSheetManager();
+
+// Open with inline content (content cloned with ref)
+const id = open(<MySheet />, { mode: 'push', scaleBackground: true });
+close(id);
+```
+
+**When to use**: Opening sheets dynamically with content as parameter.
+
+#### `useBottomSheetControl.ts` - Portal Sheet Control
+**Purpose**: Type-safe control for portal-based sheets.
+
+```typescript
+const { open, close, updateParams } = useBottomSheetControl('user-sheet');
+
+open({ params: { userId: '123' } });
+updateParams({ userId: '456' });
+```
+
+**When to use**: Controlling pre-defined portal sheets with type-safe params.
+
+#### `useBottomSheetContext.ts` - Sheet Internal Context
+**Purpose**: Access current sheet's ID and params from within the sheet.
+
+```typescript
+// Inside a sheet component
+const { id, params, close } = useBottomSheetContext<'user-sheet'>();
+```
+
+#### `useBottomSheetStatus.ts` - Sheet Status Monitoring
+**Purpose**: Observe sheet status from outside the sheet.
+
+```typescript
+const { status, isOpen } = useBottomSheetStatus('user-sheet');
+```
+
+#### `useScaleAnimation.ts` - Scale Animation Logic
+**Purpose**: Calculates scale animation values based on sheet depth.
+
+**Key Concept - Power Scaling**:
+```typescript
+const currentScale = Math.pow(scale, depth);  // e.g., 0.92^1 = 0.92, 0.92^2 = 0.85
+```
+Creates cascading scale effect for nested sheets.
+
+**useScaleDepth**: Returns number of `scaleBackground: true` sheets above current position.
+
+#### `useSheetRenderData.ts` - Render Order Logic
+**Purpose**: Determines which sheets to render and in what order.
+
+**Render Order**:
+1. Hidden persistent sheets (keepMounted=true, not in stack)
+2. Active sheets (in stackOrder)
+
+This prevents React from unmounting/remounting during state transitions.
+
+#### `useEvent.ts` - Stable Callback Utility
+**Purpose**: RFC useEvent implementation - stable function identity with latest closure.
+
+**Usage**: Used in `BottomSheetPersistent` for mount callback.
+
+### Context Files
+
+#### `BottomSheet.context.ts`
+Provides current sheet ID to children. Used by `useBottomSheetContext`.
+
+#### `BottomSheetManager.context.tsx`
+Provides groupId and scaleConfig to all components within a manager.
+
+#### `BottomSheetRef.context.ts`
+Passes sheet ref from Persistent/Portal to Managed without user intervention.
+
+### Type Definitions
+
+#### `portal.types.ts` - Type-Safe Portal Registry
+**Purpose**: Enables type-safe sheet IDs and params via module augmentation.
+
+```typescript
+// In your app:
+declare module 'react-native-bottom-sheet-stack' {
+  interface BottomSheetPortalRegistry {
+    'simple-sheet': true;                    // No params
+    'user-sheet': { userId: string };        // With params
+  }
+}
+```
+
+**Key Types**:
+- `BottomSheetPortalId` - Union of registered sheet IDs (or `string` if no registry)
+- `BottomSheetPortalParams<T>` - Params type for specific sheet ID
+- `HasParams<T>` - Boolean type for param requirement checking
+
+---
+
+## Sheet Lifecycle States
+
+```
+                    mount() (persistent only)
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                        'hidden'                              │
+│  (persistent sheets only - not rendered, but in sheetsById) │
+└─────────────────────────────────────────────────────────────┘
+                           │
+                     open() action
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                       'opening'                              │
+│  (coordinator calls ref.expand(), animation starting)        │
+└─────────────────────────────────────────────────────────────┘
+                           │
+              handleChange(index >= 0)
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                         'open'                               │
+│  (fully visible, interactive)                                │
+└─────────────────────────────────────────────────────────────┘
+                           │
+         startClosing() (user swipe or API call)
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                       'closing'                              │
+│  (coordinator calls ref.close(), animation running)          │
+└─────────────────────────────────────────────────────────────┘
+                           │
+                    handleClose()
+                           │
+          ┌────────────────┴────────────────┐
+          ▼                                 ▼
+┌──────────────────┐              ┌──────────────────┐
+│ keepMounted=true │              │ keepMounted=false│
+│   → 'hidden'     │              │   → REMOVED      │
+└──────────────────┘              └──────────────────┘
+```
+
+---
+
+## Three Operating Modes
+
+This library provides three distinct ways to use bottom sheets. Each mode has different trade-offs:
+
+| Mode | Component | Context Preserved | State Preserved | Use Case |
+|------|-----------|-------------------|-----------------|----------|
+| **Inline** | `useBottomSheetManager` | No | No | Dynamic, one-off sheets |
+| **Portal** | `BottomSheetPortal` | Yes | No | Pre-defined sheets needing context |
+| **Persistent** | `BottomSheetPersistent` | Yes | Yes | Heavy state sheets (forms, media) |
+
+---
+
+### 1. Inline Mode (Dynamic Content)
+
+**Component**: `useBottomSheetManager` hook
+**Flags**: `usePortal: false`, `keepMounted: false`
+
+```tsx
+const { open, close } = useBottomSheetManager();
+
+// Open with inline content
+const id = open(
+  <BottomSheetManaged snapPoints={['50%']}>
+    <DynamicContent data={someData} />
+  </BottomSheetManaged>,
+  { scaleBackground: true, mode: 'push' }
+);
+
+// Close by ID
+close(id);
+```
+
+**Data Flow**:
+1. `useBottomSheetManager.open()` clones content with ref attached
+2. Content stored in `sheetsById[id].content`
+3. `QueueItem` renders content directly with `BottomSheetContext.Provider`
+4. On close: Sheet removed from store entirely
+
+**Characteristics**:
+- Content passed as JSX parameter at runtime
+- Sheet unmounted on close (state lost)
+- No access to parent React context (Redux, etc.)
+- Random ID generated if not provided
+
+**Use When**:
+- Sheet content determined at runtime
+- Quick confirmation dialogs, alerts
+- No need for parent context access
+- State doesn't need to persist
+
+---
+
+### 2. Portal Mode (Context Preservation)
+
+**Component**: `BottomSheetPortal`
+**Flags**: `usePortal: true`, `keepMounted: false`
+
+```tsx
+// 1. Define sheet at declaration site (near context providers)
+<BottomSheetPortal id="user-sheet">
+  <BottomSheetManaged snapPoints={['50%']}>
+    <UserSheetContent />  {/* Has access to parent contexts! */}
+  </BottomSheetManaged>
+</BottomSheetPortal>
+
+// 2. Control from anywhere
+const { open, close, updateParams } = useBottomSheetControl('user-sheet');
+
+open({ params: { userId: '123' }, scaleBackground: true });
+updateParams({ userId: '456' });
+close();
+```
+
+**Data Flow**:
+1. `BottomSheetPortal` defines content at declaration site (renders `<Portal>`)
+2. Content stays in React tree where declared (context preserved)
+3. `QueueItem` provides `<PortalHost>` when sheet is in stack
+4. `react-native-teleport` teleports content into PortalHost
+5. On close: Sheet removed from store (content unmounts)
+
+**Characteristics**:
+- Content defined once, controlled imperatively
+- Sheet unmounted on close (state lost)
+- Full access to parent React context
+- Type-safe params via registry augmentation
+- Uses `'use no memo'` directive (React Compiler exception)
+
+**Use When**:
+- Sheet needs Redux, React Query, or custom context
+- Sheet ID and structure known at compile time
+- Type-safe params desired
+- State doesn't need to persist across open/close
+
+---
+
+### 3. Persistent Mode (State Preservation)
+
+**Component**: `BottomSheetPersistent`
+**Flags**: `usePortal: true`, `keepMounted: true`
+
+```tsx
+// 1. Define persistent sheet (content stays mounted!)
+<BottomSheetPersistent id="scanner-sheet">
+  <BottomSheetManaged snapPoints={['90%']}>
+    <ScannerWithHeavyState />  {/* State preserved across close/open! */}
+  </BottomSheetManaged>
+</BottomSheetPersistent>
+
+// 2. Control from anywhere
+const { open, close } = useBottomSheetControl('scanner-sheet');
+
+open({ scaleBackground: true });
+// User interacts, builds up state...
+close();
+// State is NOT lost!
+open();  // Reopens with previous state intact
+```
+
+**Data Flow**:
+1. On component mount: `mount()` action creates sheet with `status: 'hidden'`
+2. Sheet exists in `sheetsById` but NOT in `stackOrder`
+3. On `open()`: Sheet added to `stackOrder`, status → 'opening'
+4. On close: Status → 'hidden', removed from `stackOrder` but KEPT in `sheetsById`
+5. Content stays mounted (just hidden), state preserved
+6. On component unmount: `unmount()` removes from store completely
+
+**Lifecycle Diagram**:
+```
+Component Mount → store.mount() → status: 'hidden' (in sheetsById, not in stackOrder)
+                                         │
+                                   open() called
+                                         │
+                                         ▼
+                             status: 'opening' (added to stackOrder)
+                                         │
+                                   animation done
+                                         │
+                                         ▼
+                                  status: 'open'
+                                         │
+                                  close() called
+                                         │
+                                         ▼
+                              status: 'closing' → 'hidden'
+                              (removed from stackOrder, kept in sheetsById)
+                              Content stays mounted! State preserved!
+                                         │
+                                   open() again
+                                         │
+                                         ▼
+                             status: 'opening' (same content, same state)
+```
+
+**Characteristics**:
+- Content stays mounted even when sheet is closed
+- Full state preservation (form inputs, scroll position, media playback)
+- Full access to parent React context
+- Uses own `useRef` for sheet reference (not createRef)
+- Re-mounts automatically if cleared by `clearGroup()` during fast refresh
+
+**Use When**:
+- Heavy initialization (camera, media player, complex forms)
+- User expects to return to same state
+- Performance-critical (avoid remount cost)
+- Long-lived sheets opened/closed frequently
+
+---
+
+### Mode Comparison: Store State
+
+```
+INLINE MODE (useBottomSheetManager):
+┌─────────────────────────────────────────────────────┐
+│ sheetsById: { 'abc123': { content: <JSX>, ... } }   │
+│ stackOrder: ['abc123']                              │
+└─────────────────────────────────────────────────────┘
+After close: Sheet DELETED from sheetsById
+
+PORTAL MODE (BottomSheetPortal):
+┌─────────────────────────────────────────────────────┐
+│ sheetsById: { 'user-sheet': { usePortal: true } }   │
+│ stackOrder: ['user-sheet']                          │
+└─────────────────────────────────────────────────────┘
+After close: Sheet DELETED from sheetsById
+
+PERSISTENT MODE (BottomSheetPersistent):
+┌──────────────────────────────────────────────────────────────────┐
+│ sheetsById: { 'scanner': { usePortal: true, keepMounted: true } }│
+│ stackOrder: ['scanner']                                          │
+└──────────────────────────────────────────────────────────────────┘
+After close: Sheet KEPT in sheetsById with status: 'hidden'
+             Removed from stackOrder only
+```
+
+---
+
+### Choosing the Right Mode
+
+```
+                    ┌─────────────────────────────┐
+                    │ Need parent React context?  │
+                    └─────────────┬───────────────┘
+                                  │
+                    ┌─────────────┴───────────────┐
+                    │                             │
+                   NO                            YES
+                    │                             │
+                    ▼                             ▼
+          ┌─────────────────┐      ┌─────────────────────────┐
+          │  INLINE MODE    │      │ Need state preservation │
+          │ useBottomSheet- │      │   across open/close?    │
+          │    Manager      │      └───────────┬─────────────┘
+          └─────────────────┘                  │
+                                  ┌────────────┴────────────┐
+                                  │                         │
+                                 NO                        YES
+                                  │                         │
+                                  ▼                         ▼
+                        ┌─────────────────┐      ┌─────────────────┐
+                        │  PORTAL MODE    │      │ PERSISTENT MODE │
+                        │ BottomSheet-    │      │ BottomSheet-    │
+                        │    Portal       │      │   Persistent    │
+                        └─────────────────┘      └─────────────────┘
+```
+
+---
+
+## Scale Animation System
+
+### Configuration
+
+```typescript
+interface ScaleConfig {
+  scale?: number;        // Default: 0.92 (scale factor per depth level)
+  translateY?: number;   // Default: 10 (vertical shift per depth level)
+  borderRadius?: number; // Default: 12 (corner radius when scaled)
+  animation?: ScaleAnimationConfig;  // Timing or spring
+}
+
+type ScaleAnimationConfig =
+  | { type: 'timing'; config?: WithTimingConfig }
+  | { type: 'spring'; config?: WithSpringConfig };
+```
+
+### How It Works
+
+1. **Depth Calculation** (`useScaleDepth`):
+   - Counts sheets with `scaleBackground: true` above current position
+   - For `BottomSheetScaleView`: Counts all scaleBackground sheets (binary 0 or 1)
+   - For sheets: Counts scaleBackground sheets above it in stack
+
+2. **Power Scaling**:
+   ```typescript
+   currentScale = scale^depth      // e.g., 0.92^2 = 0.8464
+   currentTranslateY = translateY * depth
+   currentBorderRadius = min(borderRadius * depth, borderRadius)
+   ```
+
+3. **Animation**:
+   - `useDerivedValue` computes animated progress
+   - `useAnimatedStyle` applies transforms
+
+---
+
+## Group Isolation
+
+Multiple `BottomSheetManagerProvider` instances can run independently:
+
+```tsx
+<BottomSheetManagerProvider id="main-group">
+  {/* Main app sheets */}
+</BottomSheetManagerProvider>
+
+<BottomSheetManagerProvider id="modal-group">
+  {/* Modal-specific sheets */}
+</BottomSheetManagerProvider>
+```
+
+Each group:
+- Has its own stackOrder
+- Sheets filtered by groupId in coordinator
+- `clearGroup(groupId)` clears only that group
+
+---
+
+## Code Conventions
+
+### TypeScript
+- Strict mode enabled
+- `noUncheckedIndexedAccess: true` - Always check map/array access
+- `verbatimModuleSyntax: true` - Explicit `type` imports
+
+### Zustand Patterns
+- Use `shallow` comparison for object selectors
+- Use `subscribeWithSelector` for coordinator subscription
+- Never store refs in store (use global maps instead)
+
+### Animation Patterns
+- Use `react-native-reanimated` worklets
+- Shared values via `makeMutable()` for global access
+- `useAnimatedStyle` for animated components
+
+### Ref Handling
+- Global refs map instead of context drilling
+- `createRef` for dynamic sheets
+- `useRef` for persistent sheets
+
+---
+
+## Testing Utilities
+
+```typescript
+import { __resetSheetRefs, __resetAnimatedIndexes } from 'react-native-bottom-sheet-stack';
+
+beforeEach(() => {
+  __resetSheetRefs();
+  __resetAnimatedIndexes();
+});
+```
+
+---
+
+## Common Patterns
+
+### Opening a Sheet with Scale
+
+```typescript
+// Portal mode
+const { open } = useBottomSheetControl('my-sheet');
+open({ scaleBackground: true });
+
+// Inline mode
+const { open } = useBottomSheetManager();
+open(<MySheet />, { scaleBackground: true });
+```
+
+### Updating Sheet Params
+
+```typescript
+const { updateParams, resetParams } = useBottomSheetControl('user-sheet');
+
+// Update
+updateParams({ userId: newId });
+
+// Reset to undefined
+resetParams();
+```
+
+### Accessing Params Inside Sheet
+
+```typescript
+function UserSheet() {
+  const { params, close } = useBottomSheetContext<'user-sheet'>();
+  // params is typed as { userId: string } | undefined
+}
+```
+
+### Navigation Modes
+
+```typescript
+// Push: Stack sheets (both visible)
+open({ mode: 'push' });
+
+// Switch: Hide previous, show new (can restore)
+open({ mode: 'switch' });
+
+// Replace: Close previous, show new (cannot restore)
+open({ mode: 'replace' });
+```
+
+---
+
+## File Structure Summary
+
+```
+src/
+├── index.tsx                    # Public exports
+├── bottomSheet.store.ts         # Zustand store (state + actions)
+├── bottomSheetCoordinator.ts    # Store ↔ Gorhom sync
+├── refsMap.ts                   # Global sheet refs registry
+├── animatedRegistry.ts          # Global animated values registry
+├── portal.types.ts              # Type-safe portal registry types
+│
+├── BottomSheetManager.provider.tsx  # Root provider component
+├── BottomSheetManager.context.tsx   # Manager context definition
+├── BottomSheet.context.ts           # Sheet context definition
+├── BottomSheetRef.context.ts        # Ref context definition
+│
+├── BottomSheetHost.tsx          # Sheet queue renderer
+├── QueueItem.tsx                # Individual sheet slot
+├── BottomSheetManaged.tsx       # Gorhom wrapper component
+├── BottomSheetPortal.tsx        # Portal mode definition ('use no memo')
+├── BottomSheetPersistent.tsx    # Persistent sheet component
+├── BottomSheetScaleView.tsx     # Background scale wrapper
+├── BottomSheetBackdrop.tsx      # Custom backdrop component
+│
+├── useBottomSheetManager.tsx    # Dynamic sheet opening hook
+├── useBottomSheetControl.ts     # Portal sheet control hook
+├── useBottomSheetContext.ts     # Sheet internal context hook
+├── useBottomSheetStatus.ts      # External status monitoring hook
+├── useScaleAnimation.ts         # Scale animation hooks
+├── useSheetRenderData.ts        # Render order computation hook
+└── useEvent.ts                  # Stable callback utility
+```
+
+---
+
+## Dependencies Graph
+
+```
+@gorhom/bottom-sheet ──────┐
+                           │
+react-native-reanimated ───┼──▶ BottomSheetManaged
+                           │         │
+react-native-gesture-handler        │
+                                    ▼
+zustand ─────────────────────▶ bottomSheet.store
+                                    │
+                                    ▼
+react-native-teleport ────────▶ BottomSheetPortal
+                               BottomSheetPersistent
+                               QueueItem (PortalHost)
+                                    │
+                                    ▼
+react-native-safe-area-context ─▶ QueueItem (useSafeAreaFrame)
+```
+
+---
+
+## Pitfalls to Avoid
+
+1. **DO NOT memoize** - React Compiler handles it
+2. **DO NOT store refs in Zustand** - Use refsMap instead
+3. **DO NOT forget `BottomSheetHost`** - Sheets won't render without it
+4. **DO NOT nest `BottomSheetScaleView` around `BottomSheetHost`** - They must be siblings
+5. **DO NOT use same sheet ID in multiple groups** - IDs must be globally unique
+6. **DO NOT call `open()` on already-open sheet** - It's a no-op by design
diff --git a/src/BottomSheetBackdrop.tsx b/src/BottomSheetBackdrop.tsx
index 10d4d45..4215bfc 100644
--- a/src/BottomSheetBackdrop.tsx
+++ b/src/BottomSheetBackdrop.tsx
@@ -5,25 +5,18 @@ import Animated, {
   useAnimatedStyle,
 } from 'react-native-reanimated';
 import { getAnimatedIndex } from './animatedRegistry';
-import { useBottomSheetStore } from './bottomSheet.store';
+import { useSheetStatus } from './bottomSheet.store';
 
 interface BottomSheetBackdropProps {
   sheetId: string;
   onPress?: () => void;
 }
 
-/**
- * Custom backdrop component rendered separately from the scaled sheet content.
- * This ensures the backdrop doesn't scale with the sheet.
- * Opacity is interpolated from the bottom sheet's animatedIndex for smooth animation.
- */
 export function BottomSheetBackdrop({
   sheetId,
   onPress,
 }: BottomSheetBackdropProps) {
-  const status = useBottomSheetStore(
-    (state) => state.sheetsById[sheetId]?.status
-  );
+  const status = useSheetStatus(sheetId);
 
   const animatedIndex = getAnimatedIndex(sheetId);
   // Only allow interaction when fully open - prevents animation conflicts
diff --git a/src/BottomSheetHost.tsx b/src/BottomSheetHost.tsx
index 4e9ce8d..51040e5 100644
--- a/src/BottomSheetHost.tsx
+++ b/src/BottomSheetHost.tsx
@@ -1,6 +1,6 @@
 import { useEffect } from 'react';
 
-import { useBottomSheetStore } from './bottomSheet.store';
+import { useClearGroup } from './bottomSheet.store';
 import { initBottomSheetCoordinator } from './bottomSheetCoordinator';
 import { useBottomSheetManagerContext } from './BottomSheetManager.provider';
 import { QueueItem } from './QueueItem';
@@ -8,7 +8,7 @@ import { useSheetRenderData } from './useSheetRenderData';
 
 export function BottomSheetHost() {
   const sheetRenderData = useSheetRenderData();
-  const clearGroup = useBottomSheetStore((store) => store.clearGroup);
+  const clearGroup = useClearGroup();
   const { groupId } = useBottomSheetManagerContext();
 
   useEffect(() => {
diff --git a/src/BottomSheetManaged.tsx b/src/BottomSheetManaged.tsx
index 5f1d119..52f4c5a 100644
--- a/src/BottomSheetManaged.tsx
+++ b/src/BottomSheetManaged.tsx
@@ -6,7 +6,7 @@ import { type BottomSheetMethods } from '@gorhom/bottom-sheet/lib/typescript/typ
 import React from 'react';
 
 import { getAnimatedIndex } from './animatedRegistry';
-import { useBottomSheetStore } from './bottomSheet.store';
+import { useSheetStatus } from './bottomSheet.store';
 import { createSheetEventHandlers } from './bottomSheetCoordinator';
 import { useBottomSheetRefContext } from './BottomSheetRef.context';
 import { useBottomSheetContext } from './useBottomSheetContext';
@@ -39,7 +39,7 @@ export const BottomSheetManaged = React.forwardRef<
     const contextRef = useBottomSheetRefContext();
     const ref = contextRef ?? forwardedRef;
 
-    const status = useBottomSheetStore((s) => s.sheetsById[id]?.status);
+    const status = useSheetStatus(id);
     const shouldBeClosed = status === 'hidden' || status === 'closing';
     const index = externalIndex ?? (shouldBeClosed ? -1 : 0);
 
diff --git a/src/BottomSheetPersistent.tsx b/src/BottomSheetPersistent.tsx
index 66b3fb5..f8fbbf9 100644
--- a/src/BottomSheetPersistent.tsx
+++ b/src/BottomSheetPersistent.tsx
@@ -4,7 +4,7 @@ import type { BottomSheetMethods } from '@gorhom/bottom-sheet/lib/typescript/typ
 
 import { BottomSheetContext } from './BottomSheet.context';
 import { BottomSheetRefContext } from './BottomSheetRef.context';
-import { useBottomSheetStore } from './bottomSheet.store';
+import { useMount, useUnmount, useSheetExists } from './bottomSheet.store';
 import { useMaybeBottomSheetManagerContext } from './BottomSheetManager.provider';
 import type { BottomSheetPortalId } from './portal.types';
 import { setSheetRef, cleanupSheetRef } from './refsMap';
@@ -21,12 +21,9 @@ export function BottomSheetPersistent({
   children,
 }: BottomSheetPersistentProps) {
   const bottomSheetManagerContext = useMaybeBottomSheetManagerContext();
-  const mount = useBottomSheetStore((state) => state.mount);
-  const unmount = useBottomSheetStore((state) => state.unmount);
-
-  const sheetExists = useBottomSheetStore(
-    (state) => !!state.sheetsById[id]?.id
-  );
+  const mount = useMount();
+  const unmount = useUnmount();
+  const sheetExists = useSheetExists(id);
 
   const sheetRef = useRef<BottomSheetMethods>(null);
   const groupId = bottomSheetManagerContext?.groupId || 'default';
diff --git a/src/BottomSheetPortal.tsx b/src/BottomSheetPortal.tsx
index cf3acbb..d9f2645 100644
--- a/src/BottomSheetPortal.tsx
+++ b/src/BottomSheetPortal.tsx
@@ -4,7 +4,7 @@ import React from 'react';
 import { Portal } from 'react-native-teleport';
 
 import { BottomSheetContext } from './BottomSheet.context';
-import { useBottomSheetStore } from './bottomSheet.store';
+import { useSheetUsePortal } from './bottomSheet.store';
 import type { BottomSheetPortalId } from './portal.types';
 import { getSheetRef } from './refsMap';
 
@@ -14,9 +14,7 @@ interface BottomSheetPortalProps {
 }
 
 export function BottomSheetPortal({ id, children }: BottomSheetPortalProps) {
-  const usePortal = useBottomSheetStore(
-    (state) => state.sheetsById[id]?.usePortal
-  );
+  const usePortal = useSheetUsePortal(id);
 
   if (!usePortal) {
     return null;
diff --git a/src/QueueItem.tsx b/src/QueueItem.tsx
index 9f95ce4..27d64be 100644
--- a/src/QueueItem.tsx
+++ b/src/QueueItem.tsx
@@ -3,11 +3,15 @@ import { StyleSheet, View } from 'react-native';
 import Animated from 'react-native-reanimated';
 import { useSafeAreaFrame } from 'react-native-safe-area-context';
 import { PortalHost } from 'react-native-teleport';
-import { shallow } from 'zustand/shallow';
 
 import { cleanupAnimatedIndex } from './animatedRegistry';
 import { BottomSheetContext } from './BottomSheet.context';
-import { useBottomSheetStore } from './bottomSheet.store';
+import {
+  useSheetContent,
+  useSheetUsePortal,
+  useSheetKeepMounted,
+  useStartClosing,
+} from './bottomSheet.store';
 import { BottomSheetBackdrop } from './BottomSheetBackdrop';
 import { cleanupSheetRef } from './refsMap';
 import { useScaleAnimatedStyle } from './useScaleAnimation';
@@ -19,15 +23,10 @@ interface QueueItemProps {
 }
 
 export function QueueItem({ id, stackIndex, isActive }: QueueItemProps) {
-  const { content, usePortal, startClosing, keepMounted } = useBottomSheetStore(
-    (state) => ({
-      content: state.sheetsById[id]?.content,
-      usePortal: state.sheetsById[id]?.usePortal,
-      keepMounted: state.sheetsById[id]?.keepMounted,
-      startClosing: state.startClosing,
-    }),
-    shallow
-  );
+  const content = useSheetContent(id);
+  const usePortal = useSheetUsePortal(id);
+  const keepMounted = useSheetKeepMounted(id);
+  const startClosing = useStartClosing();
 
   const { width, height } = useSafeAreaFrame();
   const scaleStyle = useScaleAnimatedStyle({ id });
diff --git a/src/bottomSheet.store.ts b/src/bottomSheet.store.ts
index 123817b..d406816 100644
--- a/src/bottomSheet.store.ts
+++ b/src/bottomSheet.store.ts
@@ -1,251 +1 @@
-import { type ReactNode } from 'react';
-import { subscribeWithSelector } from 'zustand/middleware';
-import { createWithEqualityFn as create } from 'zustand/traditional';
-
-export type BottomSheetStatus = 'opening' | 'open' | 'closing' | 'hidden';
-export type OpenMode = 'push' | 'switch' | 'replace';
-
-export interface BottomSheetState {
-  groupId: string;
-  id: string;
-  content?: ReactNode;
-  status: BottomSheetStatus;
-  scaleBackground?: boolean;
-  usePortal?: boolean;
-  params?: Record<string, unknown>;
-  keepMounted?: boolean;
-}
-
-type TriggerState = Omit<BottomSheetState, 'status'>;
-
-interface BottomSheetStoreState {
-  sheetsById: Record<string, BottomSheetState>;
-  stackOrder: string[];
-}
-
-interface BottomSheetStoreActions {
-  open(sheet: TriggerState, mode?: OpenMode): void;
-  markOpen(id: string): void;
-  startClosing(id: string): void;
-  finishClosing(id: string): void;
-  updateParams(id: string, params: Record<string, unknown> | undefined): void;
-  clearGroup(groupId: string): void;
-  clearAll(): void;
-  mount(sheet: Omit<BottomSheetState, 'status'>): void;
-  unmount(id: string): void;
-}
-
-export type BottomSheetStore = BottomSheetStoreState & BottomSheetStoreActions;
-
-// --- Pure helper functions (outside store for testability) ---
-
-const MODE_STATUS_MAP: Record<OpenMode, BottomSheetStatus | null> = {
-  push: null,
-  switch: 'hidden',
-  replace: 'closing',
-};
-
-function applyModeToTopSheet(
-  sheetsById: Record<string, BottomSheetState>,
-  stackOrder: string[],
-  mode: OpenMode
-): void {
-  const targetStatus = MODE_STATUS_MAP[mode];
-  if (!targetStatus) return;
-
-  const topId = stackOrder[stackOrder.length - 1];
-  if (!topId) return;
-
-  const topSheet = sheetsById[topId];
-  if (topSheet) {
-    sheetsById[topId] = { ...topSheet, status: targetStatus };
-  }
-}
-
-function isActivatableKeepMounted(
-  sheet: BottomSheetState | undefined
-): sheet is BottomSheetState {
-  return Boolean(sheet?.keepMounted && sheet.status === 'hidden');
-}
-
-// --- Store ---
-
-export const useBottomSheetStore = create(
-  subscribeWithSelector<BottomSheetStore>((set) => ({
-    sheetsById: {},
-    stackOrder: [],
-
-    open: (sheet, mode = 'push') =>
-      set((state) => {
-        const existingSheet = state.sheetsById[sheet.id];
-
-        // Sheet already active - no-op
-        if (existingSheet && !isActivatableKeepMounted(existingSheet)) {
-          return state;
-        }
-
-        const newSheetsById = { ...state.sheetsById };
-        applyModeToTopSheet(newSheetsById, state.stackOrder, mode);
-
-        const newSheet: BottomSheetState = existingSheet
-          ? {
-              ...existingSheet,
-              status: 'opening',
-              scaleBackground:
-                sheet.scaleBackground ?? existingSheet.scaleBackground,
-              params: sheet.params ?? existingSheet.params,
-            }
-          : { ...sheet, status: 'opening' };
-
-        newSheetsById[sheet.id] = newSheet;
-
-        return {
-          sheetsById: newSheetsById,
-          stackOrder: [...state.stackOrder, sheet.id],
-        };
-      }),
-
-    markOpen: (id) =>
-      set((state) => {
-        const sheet = state.sheetsById[id];
-        if (!sheet) {
-          return state;
-        }
-        return {
-          sheetsById: {
-            ...state.sheetsById,
-            [id]: { ...sheet, status: 'open' },
-          },
-        };
-      }),
-
-    startClosing: (id) =>
-      set((state) => {
-        const sheet = state.sheetsById[id];
-        if (!sheet || sheet.status === 'hidden') {
-          return state;
-        }
-
-        const newSheetsById = { ...state.sheetsById };
-        newSheetsById[id] = { ...sheet, status: 'closing' };
-
-        const index = state.stackOrder.indexOf(id);
-        const belowId = state.stackOrder[index - 1];
-        const belowSheet = belowId ? newSheetsById[belowId] : undefined;
-
-        if (belowId && belowSheet && belowSheet.status === 'hidden') {
-          newSheetsById[belowId] = { ...belowSheet, status: 'opening' };
-        }
-
-        return { sheetsById: newSheetsById };
-      }),
-
-    finishClosing: (id) =>
-      set((state) => {
-        const sheet = state.sheetsById[id];
-        if (!sheet) {
-          return state;
-        }
-
-        const newSheetsById = { ...state.sheetsById };
-
-        // For keepMounted sheets, set status to 'hidden' instead of deleting
-        if (sheet.keepMounted) {
-          newSheetsById[id] = { ...sheet, status: 'hidden' };
-        } else {
-          delete newSheetsById[id];
-        }
-
-        const newStackOrder = state.stackOrder.filter(
-          (sheetId) => sheetId !== id
-        );
-
-        const topId = newStackOrder[newStackOrder.length - 1];
-        const topSheet = topId ? newSheetsById[topId] : undefined;
-
-        if (topId && topSheet && topSheet.status === 'hidden') {
-          newSheetsById[topId] = { ...topSheet, status: 'opening' };
-        }
-
-        return {
-          sheetsById: newSheetsById,
-          stackOrder: newStackOrder,
-        };
-      }),
-
-    updateParams: (id, params) =>
-      set((state) => {
-        const sheet = state.sheetsById[id];
-        if (!sheet) {
-          return state;
-        }
-        return {
-          sheetsById: {
-            ...state.sheetsById,
-            [id]: { ...sheet, params },
-          },
-        };
-      }),
-
-    clearGroup: (groupId) =>
-      set((state) => {
-        // Find all sheets in this group (both in stackOrder and keepMounted hidden)
-        const idsInGroup = Object.keys(state.sheetsById).filter(
-          (id) => state.sheetsById[id]?.groupId === groupId
-        );
-
-        if (idsInGroup.length === 0) {
-          return state;
-        }
-
-        const idsToRemove = new Set(idsInGroup);
-        const newSheetsById = { ...state.sheetsById };
-        idsToRemove.forEach((id) => {
-          delete newSheetsById[id];
-        });
-
-        return {
-          sheetsById: newSheetsById,
-          stackOrder: state.stackOrder.filter((id) => !idsToRemove.has(id)),
-        };
-      }),
-
-    clearAll: () => set(() => ({ sheetsById: {}, stackOrder: [] })),
-
-    mount: (sheet) =>
-      set((state) => {
-        // Don't mount if already exists
-        if (state.sheetsById[sheet.id]) {
-          return state;
-        }
-
-        return {
-          sheetsById: {
-            ...state.sheetsById,
-            [sheet.id]: { ...sheet, status: 'hidden' },
-          },
-        };
-      }),
-
-    unmount: (id) =>
-      set((state) => {
-        const sheet = state.sheetsById[id];
-        if (!sheet) {
-          return state;
-        }
-
-        const newSheetsById = { ...state.sheetsById };
-        delete newSheetsById[id];
-
-        // Also remove from stackOrder if present
-        const newStackOrder = state.stackOrder.filter(
-          (sheetId) => sheetId !== id
-        );
-
-        return {
-          sheetsById: newSheetsById,
-          stackOrder: newStackOrder,
-        };
-      }),
-  }))
-);
+export * from './store';
diff --git a/src/store/helpers.ts b/src/store/helpers.ts
new file mode 100644
index 0000000..215707e
--- /dev/null
+++ b/src/store/helpers.ts
@@ -0,0 +1,61 @@
+import type { BottomSheetState, BottomSheetStatus, OpenMode } from './types';
+
+export const MODE_STATUS_MAP: Record<OpenMode, BottomSheetStatus | null> = {
+  push: null,
+  switch: 'hidden',
+  replace: 'closing',
+};
+
+export function isActivatableKeepMounted(
+  sheet: BottomSheetState | undefined
+): sheet is BottomSheetState {
+  return Boolean(sheet?.keepMounted && sheet.status === 'hidden');
+}
+
+export function isHidden(sheet: BottomSheetState | undefined): boolean {
+  return sheet?.status === 'hidden';
+}
+
+export function updateSheet(
+  sheetsById: Record<string, BottomSheetState>,
+  id: string,
+  update: Partial<BottomSheetState>
+): Record<string, BottomSheetState> {
+  const sheet = sheetsById[id];
+  if (!sheet) return sheetsById;
+
+  return {
+    ...sheetsById,
+    [id]: { ...sheet, ...update },
+  };
+}
+
+export function applyModeToTopSheet(
+  sheetsById: Record<string, BottomSheetState>,
+  stackOrder: string[],
+  mode: OpenMode
+): Record<string, BottomSheetState> {
+  const targetStatus = MODE_STATUS_MAP[mode];
+  if (!targetStatus) return sheetsById;
+
+  const topId = stackOrder[stackOrder.length - 1];
+  if (!topId || !sheetsById[topId]) return sheetsById;
+
+  return updateSheet(sheetsById, topId, { status: targetStatus });
+}
+
+export function removeFromStack(stackOrder: string[], id: string): string[] {
+  return stackOrder.filter((sheetId) => sheetId !== id);
+}
+
+export function getTopSheetId(stackOrder: string[]): string | undefined {
+  return stackOrder[stackOrder.length - 1];
+}
+
+export function getSheetBelowId(
+  stackOrder: string[],
+  id: string
+): string | undefined {
+  const index = stackOrder.indexOf(id);
+  return index > 0 ? stackOrder[index - 1] : undefined;
+}
diff --git a/src/store/hooks.ts b/src/store/hooks.ts
new file mode 100644
index 0000000..2cc7423
--- /dev/null
+++ b/src/store/hooks.ts
@@ -0,0 +1,51 @@
+import { getTopSheetId } from './helpers';
+import { useBottomSheetStore } from './store';
+
+// State hooks
+
+export const useSheet = (id: string) =>
+  useBottomSheetStore((state) => state.sheetsById[id]);
+
+export const useSheetStatus = (id: string) =>
+  useBottomSheetStore((state) => state.sheetsById[id]?.status);
+
+export const useSheetParams = (id: string) =>
+  useBottomSheetStore((state) => state.sheetsById[id]?.params);
+
+export const useSheetContent = (id: string) =>
+  useBottomSheetStore((state) => state.sheetsById[id]?.content);
+
+export const useSheetUsePortal = (id: string) =>
+  useBottomSheetStore((state) => state.sheetsById[id]?.usePortal);
+
+export const useSheetKeepMounted = (id: string) =>
+  useBottomSheetStore((state) => state.sheetsById[id]?.keepMounted);
+
+export const useSheetExists = (id: string) =>
+  useBottomSheetStore((state) => !!state.sheetsById[id]);
+
+export const useIsSheetOpen = (id: string) =>
+  useBottomSheetStore((state) => {
+    const status = state.sheetsById[id]?.status;
+    return status === 'open' || status === 'opening';
+  });
+
+export const useTopSheetId = () =>
+  useBottomSheetStore((state) => getTopSheetId(state.stackOrder));
+
+// Action hooks
+
+export const useOpen = () => useBottomSheetStore((state) => state.open);
+
+export const useStartClosing = () =>
+  useBottomSheetStore((state) => state.startClosing);
+
+export const useUpdateParams = () =>
+  useBottomSheetStore((state) => state.updateParams);
+
+export const useClearGroup = () =>
+  useBottomSheetStore((state) => state.clearGroup);
+
+export const useMount = () => useBottomSheetStore((state) => state.mount);
+
+export const useUnmount = () => useBottomSheetStore((state) => state.unmount);
diff --git a/src/store/index.ts b/src/store/index.ts
new file mode 100644
index 0000000..e088c09
--- /dev/null
+++ b/src/store/index.ts
@@ -0,0 +1,4 @@
+export * from './types';
+export * from './store';
+export * from './hooks';
+export { getTopSheetId } from './helpers';
diff --git a/src/store/store.ts b/src/store/store.ts
new file mode 100644
index 0000000..f5f8fb9
--- /dev/null
+++ b/src/store/store.ts
@@ -0,0 +1,159 @@
+import { subscribeWithSelector } from 'zustand/middleware';
+import { createWithEqualityFn as create } from 'zustand/traditional';
+
+import {
+  applyModeToTopSheet,
+  getSheetBelowId,
+  getTopSheetId,
+  isActivatableKeepMounted,
+  isHidden,
+  removeFromStack,
+  updateSheet,
+} from './helpers';
+import type { BottomSheetState, BottomSheetStore } from './types';
+
+export const useBottomSheetStore = create(
+  subscribeWithSelector<BottomSheetStore>((set) => ({
+    sheetsById: {},
+    stackOrder: [],
+
+    open: (sheet, mode = 'push') =>
+      set((state) => {
+        const existingSheet = state.sheetsById[sheet.id];
+
+        if (existingSheet && !isActivatableKeepMounted(existingSheet)) {
+          return state;
+        }
+
+        const updatedSheetsById = applyModeToTopSheet(
+          state.sheetsById,
+          state.stackOrder,
+          mode
+        );
+
+        const newSheet: BottomSheetState = existingSheet
+          ? {
+              ...existingSheet,
+              status: 'opening',
+              scaleBackground:
+                sheet.scaleBackground ?? existingSheet.scaleBackground,
+              params: sheet.params ?? existingSheet.params,
+            }
+          : { ...sheet, status: 'opening' };
+
+        return {
+          sheetsById: { ...updatedSheetsById, [sheet.id]: newSheet },
+          stackOrder: [...state.stackOrder, sheet.id],
+        };
+      }),
+
+    markOpen: (id) =>
+      set((state) => {
+        if (!state.sheetsById[id]) return state;
+        return {
+          sheetsById: updateSheet(state.sheetsById, id, { status: 'open' }),
+        };
+      }),
+
+    startClosing: (id) =>
+      set((state) => {
+        const sheet = state.sheetsById[id];
+        if (!sheet || isHidden(sheet)) return state;
+
+        let updatedSheetsById = updateSheet(state.sheetsById, id, {
+          status: 'closing',
+        });
+
+        const belowId = getSheetBelowId(state.stackOrder, id);
+        if (belowId && isHidden(updatedSheetsById[belowId])) {
+          updatedSheetsById = updateSheet(updatedSheetsById, belowId, {
+            status: 'opening',
+          });
+        }
+
+        return { sheetsById: updatedSheetsById };
+      }),
+
+    finishClosing: (id) =>
+      set((state) => {
+        const sheet = state.sheetsById[id];
+        if (!sheet) return state;
+
+        let updatedSheetsById = { ...state.sheetsById };
+
+        if (sheet.keepMounted) {
+          updatedSheetsById = updateSheet(updatedSheetsById, id, {
+            status: 'hidden',
+          });
+        } else {
+          delete updatedSheetsById[id];
+        }
+
+        const newStackOrder = removeFromStack(state.stackOrder, id);
+        const topId = getTopSheetId(newStackOrder);
+
+        if (topId && isHidden(updatedSheetsById[topId])) {
+          updatedSheetsById = updateSheet(updatedSheetsById, topId, {
+            status: 'opening',
+          });
+        }
+
+        return {
+          sheetsById: updatedSheetsById,
+          stackOrder: newStackOrder,
+        };
+      }),
+
+    updateParams: (id, params) =>
+      set((state) => {
+        if (!state.sheetsById[id]) return state;
+        return { sheetsById: updateSheet(state.sheetsById, id, { params }) };
+      }),
+
+    clearGroup: (groupId) =>
+      set((state) => {
+        const idsToRemove = new Set(
+          Object.keys(state.sheetsById).filter(
+            (id) => state.sheetsById[id]?.groupId === groupId
+          )
+        );
+
+        if (idsToRemove.size === 0) return state;
+
+        const updatedSheetsById = { ...state.sheetsById };
+        idsToRemove.forEach((id) => delete updatedSheetsById[id]);
+
+        return {
+          sheetsById: updatedSheetsById,
+          stackOrder: state.stackOrder.filter((id) => !idsToRemove.has(id)),
+        };
+      }),
+
+    clearAll: () => set({ sheetsById: {}, stackOrder: [] }),
+
+    mount: (sheet) =>
+      set((state) => {
+        if (state.sheetsById[sheet.id]) return state;
+
+        return {
+          sheetsById: {
+            ...state.sheetsById,
+            [sheet.id]: { ...sheet, status: 'hidden' },
+          },
+        };
+      }),
+
+    unmount: (id) =>
+      set((state) => {
+        if (!state.sheetsById[id]) return state;
+
+        const updatedSheetsById = { ...state.sheetsById };
+        delete updatedSheetsById[id];
+
+        return {
+          sheetsById: updatedSheetsById,
+          stackOrder: removeFromStack(state.stackOrder, id),
+        };
+      }),
+  }))
+);
diff --git a/src/store/types.ts b/src/store/types.ts
new file mode 100644
index 0000000..b9cf02a
--- /dev/null
+++ b/src/store/types.ts
@@ -0,0 +1,36 @@
+import { type ReactNode } from 'react';
+
+export type BottomSheetStatus = 'opening' | 'open' | 'closing' | 'hidden';
+export type OpenMode = 'push' | 'switch' | 'replace';
+
+export interface BottomSheetState {
+  groupId: string;
+  id: string;
+  content?: ReactNode;
+  status: BottomSheetStatus;
+  scaleBackground?: boolean;
+  usePortal?: boolean;
+  params?: Record<string, unknown>;
+  keepMounted?: boolean;
+}
+
+export type TriggerState = Omit<BottomSheetState, 'status'>;
+
+export interface BottomSheetStoreState {
+  sheetsById: Record<string, BottomSheetState>;
+  stackOrder: string[];
+}
+
+export interface BottomSheetStoreActions {
+  open(sheet: TriggerState, mode?: OpenMode): void;
+  markOpen(id: string): void;
+  startClosing(id: string): void;
+  finishClosing(id: string): void;
+  updateParams(id: string, params: Record<string, unknown> | undefined): void;
+  clearGroup(groupId: string): void;
+  clearAll(): void;
+  mount(sheet: Omit<BottomSheetState, 'status'>): void;
+  unmount(id: string): void;
+}
+
+export type BottomSheetStore = BottomSheetStoreState & BottomSheetStoreActions;
diff --git a/src/useBottomSheetContext.ts b/src/useBottomSheetContext.ts
index f30ccfd..19433b8 100644
--- a/src/useBottomSheetContext.ts
+++ b/src/useBottomSheetContext.ts
@@ -1,6 +1,5 @@
-import { shallow } from 'zustand/shallow';
 import { useMaybeBottomSheetContext } from './BottomSheet.context';
-import { useBottomSheetStore } from './bottomSheet.store';
+import { useSheet, useStartClosing } from './bottomSheet.store';
 import type {
   BottomSheetPortalId,
   BottomSheetPortalParams,
@@ -24,16 +23,11 @@ export function useBottomSheetContext<
   T extends BottomSheetPortalId,
 >(): UseBottomSheetContextReturn<BottomSheetPortalParams<T> | unknown> {
   const context = useMaybeBottomSheetContext();
+  const sheet = useSheet(context?.id ?? '');
+  const startClosing = useStartClosing();
 
-  const { id, params } = useBottomSheetStore(
-    (state) => ({
-      id: state.sheetsById[context?.id!]?.id,
-      params: state.sheetsById[context?.id!]?.params,
-    }),
-    shallow
-  );
-
-  const startClosing = useBottomSheetStore((state) => state.startClosing);
+  const id = sheet?.id;
+  const params = sheet?.params;
 
   if (!id) {
     throw new Error(
diff --git a/src/useBottomSheetControl.ts b/src/useBottomSheetControl.ts
index 306a40b..a3c4037 100644
--- a/src/useBottomSheetControl.ts
+++ b/src/useBottomSheetControl.ts
@@ -1,7 +1,12 @@
 import React from 'react';
 import type { BottomSheetMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
 
-import { useBottomSheetStore, type OpenMode } from './bottomSheet.store';
+import {
+  useOpen,
+  useStartClosing,
+  useUpdateParams,
+  type OpenMode,
+} from './bottomSheet.store';
 import { useMaybeBottomSheetManagerContext } from './BottomSheetManager.provider';
 import type {
   BottomSheetPortalId,
@@ -41,9 +46,9 @@ export function useBottomSheetControl<T extends BottomSheetPortalId>(
 ): UseBottomSheetControlReturn<T> {
   const bottomSheetManagerContext = useMaybeBottomSheetManagerContext();
 
-  const storeOpen = useBottomSheetStore((state) => state.open);
-  const startClosing = useBottomSheetStore((state) => state.startClosing);
-  const storeUpdateParams = useBottomSheetStore((state) => state.updateParams);
+  const storeOpen = useOpen();
+  const startClosing = useStartClosing();
+  const storeUpdateParams = useUpdateParams();
 
   const open = (options?: OpenOptions<T>) => {
     const groupId = bottomSheetManagerContext?.groupId || 'default';
diff --git a/src/useBottomSheetManager.tsx b/src/useBottomSheetManager.tsx
index fe17d7d..f463232 100644
--- a/src/useBottomSheetManager.tsx
+++ b/src/useBottomSheetManager.tsx
@@ -1,22 +1,21 @@
 import React from 'react';
 
-import { useBottomSheetStore, type OpenMode } from './bottomSheet.store';
+import {
+  useOpen,
+  useStartClosing,
+  useClearGroup,
+  type OpenMode,
+} from './bottomSheet.store';
 import { useMaybeBottomSheetManagerContext } from './BottomSheetManager.provider';
 import { setSheetRef } from './refsMap';
 import type { BottomSheetMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
-import { shallow } from 'zustand/shallow';
 
 export const useBottomSheetManager = () => {
   const bottomSheetManagerContext = useMaybeBottomSheetManagerContext();
 
-  const { storeOpen, startClosing, storeClearGroup } = useBottomSheetStore(
-    (store) => ({
-      storeOpen: store.open,
-      storeClearGroup: store.clearGroup,
-      startClosing: store.startClosing,
-    }),
-    shallow
-  );
+  const storeOpen = useOpen();
+  const startClosing = useStartClosing();
+  const storeClearGroup = useClearGroup();
 
   const openBottomSheet = (
     content: React.ReactElement,
diff --git a/src/useBottomSheetStatus.ts b/src/useBottomSheetStatus.ts
index b94fa3f..9d4b6c6 100644
--- a/src/useBottomSheetStatus.ts
+++ b/src/useBottomSheetStatus.ts
@@ -1,5 +1,6 @@
 import {
-  useBottomSheetStore,
+  useSheetStatus,
+  useIsSheetOpen,
   type BottomSheetStatus,
 } from './bottomSheet.store';
 import type { BottomSheetPortalId } from './portal.types';
@@ -12,11 +13,8 @@ export interface UseBottomSheetStatusReturn {
 export function useBottomSheetStatus(
   id: BottomSheetPortalId
 ): UseBottomSheetStatusReturn {
-  const status = useBottomSheetStore(
-    (state) => state.sheetsById[id]?.status ?? null
-  );
-
-  const isOpen = status === 'open' || status === 'opening';
+  const status = useSheetStatus(id) ?? null;
+  const isOpen = useIsSheetOpen(id);
 
   return {
     status,

From fa804b71d13c950d5458d56cd62d2e51231e8bf0 Mon Sep 17 00:00:00 2001
From: Arkadiusz Kubaczkowski <arek.kubaczkowski@gmail.com>
Date: Thu, 22 Jan 2026 09:20:30 +0100
Subject: [PATCH 5/7] chore: refactor

---
 CLAUDE.md                     |  9 +++++
 docs/docs/api/hooks.md        | 13 ++++--
 src/BottomSheetBackdrop.tsx   |  2 -
 src/BottomSheetPersistent.tsx | 44 +++++++++------------
 src/BottomSheetPortal.tsx     |  8 ++--
 src/QueueItem.tsx             |  7 +++-
 src/index.tsx                 |  1 +
 src/portalSessionRegistry.ts  | 25 ++++++++++++
 src/store/hooks.ts            | 23 ++++++-----
 src/store/store.ts            | 10 ++++-
 src/store/types.ts            |  6 +++
 src/useBottomSheetContext.ts  | 13 +++---
 src/useBottomSheetStatus.ts   | 14 ++-----
 src/useScaleAnimation.ts      | 74 +++++++++++++++++++++--------------
 14 files changed, 152 insertions(+), 97 deletions(-)
 create mode 100644 src/portalSessionRegistry.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index b6e0e20..7df83b2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -261,8 +261,17 @@ const { id, params, close } = useBottomSheetContext<'user-sheet'>();
 #### `useBottomSheetStatus.ts` - Sheet Status Monitoring
 **Purpose**: Observe sheet status from outside the sheet.
 
+**Works with all sheet types**: Portal, persistent, and inline sheets.
+
 ```typescript
+// Portal/persistent sheet (registered ID)
 const { status, isOpen } = useBottomSheetStatus('user-sheet');
+
+// Inline sheet (dynamic ID from useBottomSheetManager)
+const { open } = useBottomSheetManager();
+const sheetId = open(<MySheet />);
+// Later...
+const { status, isOpen } = useBottomSheetStatus(sheetId);
 ```
 
 #### `useScaleAnimation.ts` - Scale Animation Logic
diff --git a/docs/docs/api/hooks.md b/docs/docs/api/hooks.md
index 687aa40..c2b7d8c 100644
--- a/docs/docs/api/hooks.md
+++ b/docs/docs/api/hooks.md
@@ -155,19 +155,26 @@ open({
 
 Subscribe to any sheet's status from anywhere in your app. Pass the sheet ID to identify which sheet to observe.
 
-:::tip When to Use
-Use this when you need to show UI based on whether a sheet is open, or react to status changes. Separate from `useBottomSheetControl` to avoid unnecessary re-renders in components that only need to trigger sheets.
+:::tip Works with All Sheet Types
+This hook accepts any string ID, so it works with portal sheets, persistent sheets, and inline sheets (using the ID returned from `useBottomSheetManager().open()`).
 :::
 
 ```tsx
+// Portal/persistent sheet
 const { status, isOpen } = useBottomSheetStatus('my-sheet');
+
+// Inline sheet (using ID from open())
+const { open } = useBottomSheetManager();
+const sheetId = open(<MySheet />);
+// ...
+const { status, isOpen } = useBottomSheetStatus(sheetId);
 ```
 
 ### Parameters
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `id` | `BottomSheetPortalId` | The sheet ID to observe |
+| `id` | `string` | The sheet ID to observe (portal ID or inline sheet ID) |
 
 ### Returns
 
diff --git a/src/BottomSheetBackdrop.tsx b/src/BottomSheetBackdrop.tsx
index 4215bfc..a0a1bfc 100644
--- a/src/BottomSheetBackdrop.tsx
+++ b/src/BottomSheetBackdrop.tsx
@@ -17,9 +17,7 @@ export function BottomSheetBackdrop({
   onPress,
 }: BottomSheetBackdropProps) {
   const status = useSheetStatus(sheetId);
-
   const animatedIndex = getAnimatedIndex(sheetId);
-  // Only allow interaction when fully open - prevents animation conflicts
   const isInteractive = status === 'open';
 
   const animatedStyle = useAnimatedStyle(() => {
diff --git a/src/BottomSheetPersistent.tsx b/src/BottomSheetPersistent.tsx
index f8fbbf9..2b738fc 100644
--- a/src/BottomSheetPersistent.tsx
+++ b/src/BottomSheetPersistent.tsx
@@ -1,15 +1,13 @@
-import React, { useEffect, useLayoutEffect, useRef } from 'react';
-import { Portal } from 'react-native-teleport';
 import type { BottomSheetMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
+import React, { useEffect, useRef } from 'react';
 
-import { BottomSheetContext } from './BottomSheet.context';
-import { BottomSheetRefContext } from './BottomSheetRef.context';
-import { useMount, useUnmount, useSheetExists } from './bottomSheet.store';
+import { useMount, useSheetExists, useUnmount } from './bottomSheet.store';
 import { useMaybeBottomSheetManagerContext } from './BottomSheetManager.provider';
+import { BottomSheetPortal } from './BottomSheetPortal';
+import { BottomSheetRefContext } from './BottomSheetRef.context';
 import type { BottomSheetPortalId } from './portal.types';
-import { setSheetRef, cleanupSheetRef } from './refsMap';
-import { cleanupAnimatedIndex } from './animatedRegistry';
 import { useEvent } from './useEvent';
+import { setSheetRef } from './refsMap';
 
 interface BottomSheetPersistentProps {
   id: BottomSheetPortalId;
@@ -29,37 +27,31 @@ export function BottomSheetPersistent({
   const groupId = bottomSheetManagerContext?.groupId || 'default';
 
   const mountSheet = useEvent(() => {
-    setSheetRef(id, sheetRef);
     mount({ id, groupId, content: null, usePortal: true, keepMounted: true });
   });
 
-  useLayoutEffect(() => {
-    mountSheet();
-    return () => {
-      unmount(id);
-      cleanupSheetRef(id);
-      cleanupAnimatedIndex(id);
-    };
-  }, [id, groupId, mount, unmount, mountSheet]);
-
-  // Re-mount if sheet was removed externally (e.g., by clearGroup during fast refresh)
   useEffect(() => {
     if (!sheetExists) {
+      setSheetRef(id, sheetRef);
       mountSheet();
     }
-  }, [sheetExists, id, groupId, mount, mountSheet]);
+  }, [id, sheetExists, mountSheet]);
+
+  useEffect(() => {
+    return () => {
+      unmount(id);
+    };
+  }, [id, unmount]);
 
   if (!sheetExists) {
     return null;
   }
 
   return (
-    <Portal hostName={`bottomsheet-${id}`}>
-      <BottomSheetContext.Provider value={{ id }}>
-        <BottomSheetRefContext.Provider value={sheetRef}>
-          {children}
-        </BottomSheetRefContext.Provider>
-      </BottomSheetContext.Provider>
-    </Portal>
+    <BottomSheetPortal id={id}>
+      <BottomSheetRefContext.Provider value={sheetRef}>
+        {children}
+      </BottomSheetRefContext.Provider>
+    </BottomSheetPortal>
   );
 }
diff --git a/src/BottomSheetPortal.tsx b/src/BottomSheetPortal.tsx
index d9f2645..f768397 100644
--- a/src/BottomSheetPortal.tsx
+++ b/src/BottomSheetPortal.tsx
@@ -4,7 +4,7 @@ import React from 'react';
 import { Portal } from 'react-native-teleport';
 
 import { BottomSheetContext } from './BottomSheet.context';
-import { useSheetUsePortal } from './bottomSheet.store';
+import { useSheetUsePortal, useSheetPortalSession } from './bottomSheet.store';
 import type { BottomSheetPortalId } from './portal.types';
 import { getSheetRef } from './refsMap';
 
@@ -15,19 +15,19 @@ interface BottomSheetPortalProps {
 
 export function BottomSheetPortal({ id, children }: BottomSheetPortalProps) {
   const usePortal = useSheetUsePortal(id);
+  const portalSession = useSheetPortalSession(id);
 
-  if (!usePortal) {
+  if (!usePortal || portalSession === undefined) {
     return null;
   }
 
   const ref = getSheetRef(id);
-
   const childWithRef = React.cloneElement(children, {
     ref,
   } as { ref: typeof ref });
 
   return (
-    <Portal hostName={`bottomsheet-${id}`}>
+    <Portal hostName={`bottomsheet-${id}-${portalSession}`}>
       <BottomSheetContext.Provider value={{ id }}>
         {childWithRef}
       </BottomSheetContext.Provider>
diff --git a/src/QueueItem.tsx b/src/QueueItem.tsx
index 27d64be..528e74f 100644
--- a/src/QueueItem.tsx
+++ b/src/QueueItem.tsx
@@ -10,6 +10,7 @@ import {
   useSheetContent,
   useSheetUsePortal,
   useSheetKeepMounted,
+  useSheetPortalSession,
   useStartClosing,
 } from './bottomSheet.store';
 import { BottomSheetBackdrop } from './BottomSheetBackdrop';
@@ -26,6 +27,7 @@ export function QueueItem({ id, stackIndex, isActive }: QueueItemProps) {
   const content = useSheetContent(id);
   const usePortal = useSheetUsePortal(id);
   const keepMounted = useSheetKeepMounted(id);
+  const portalSession = useSheetPortalSession(id);
   const startClosing = useStartClosing();
 
   const { width, height } = useSafeAreaFrame();
@@ -64,7 +66,10 @@ export function QueueItem({ id, stackIndex, isActive }: QueueItemProps) {
         ]}
       >
         {usePortal ? (
-          <PortalHost name={`bottomsheet-${id}`} style={{ width, height }} />
+          <PortalHost
+            name={`bottomsheet-${id}-${portalSession}`}
+            style={{ width, height }}
+          />
         ) : (
           <BottomSheetContext.Provider value={{ id }}>
             {content}
diff --git a/src/index.tsx b/src/index.tsx
index d83a40e..5fae241 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -38,3 +38,4 @@ export type {
 // Testing utilities (internal use)
 export { __resetSheetRefs } from './refsMap';
 export { __resetAnimatedIndexes } from './animatedRegistry';
+export { __resetPortalSessions } from './portalSessionRegistry';
diff --git a/src/portalSessionRegistry.ts b/src/portalSessionRegistry.ts
new file mode 100644
index 0000000..389a591
--- /dev/null
+++ b/src/portalSessionRegistry.ts
@@ -0,0 +1,25 @@
+/**
+ * Registry for portal session counters per sheet.
+ * This persists across sheet deletions to ensure unique Portal/PortalHost names
+ * and work around react-native-teleport connection issues after replace flows.
+ */
+const portalSessionRegistry = new Map<string, number>();
+
+export function getNextPortalSession(sheetId: string): number {
+  const current = portalSessionRegistry.get(sheetId) ?? 0;
+  const next = current + 1;
+  portalSessionRegistry.set(sheetId, next);
+  return next;
+}
+
+export function getCurrentPortalSession(sheetId: string): number | undefined {
+  return portalSessionRegistry.get(sheetId);
+}
+
+/**
+ * Reset all portal sessions. Useful for testing.
+ * @internal
+ */
+export function __resetPortalSessions(): void {
+  portalSessionRegistry.clear();
+}
diff --git a/src/store/hooks.ts b/src/store/hooks.ts
index 2cc7423..2a620c2 100644
--- a/src/store/hooks.ts
+++ b/src/store/hooks.ts
@@ -1,37 +1,36 @@
-import { getTopSheetId } from './helpers';
+import { shallow } from 'zustand/shallow';
 import { useBottomSheetStore } from './store';
 
 // State hooks
 
 export const useSheet = (id: string) =>
-  useBottomSheetStore((state) => state.sheetsById[id]);
+  useBottomSheetStore((state) => state.sheetsById[id], shallow);
 
 export const useSheetStatus = (id: string) =>
-  useBottomSheetStore((state) => state.sheetsById[id]?.status);
+  useBottomSheetStore((state) => state.sheetsById[id]?.status, shallow);
 
 export const useSheetParams = (id: string) =>
-  useBottomSheetStore((state) => state.sheetsById[id]?.params);
+  useBottomSheetStore((state) => state.sheetsById[id]?.params, shallow);
 
 export const useSheetContent = (id: string) =>
-  useBottomSheetStore((state) => state.sheetsById[id]?.content);
+  useBottomSheetStore((state) => state.sheetsById[id]?.content, shallow);
 
 export const useSheetUsePortal = (id: string) =>
-  useBottomSheetStore((state) => state.sheetsById[id]?.usePortal);
+  useBottomSheetStore((state) => state.sheetsById[id]?.usePortal, shallow);
 
 export const useSheetKeepMounted = (id: string) =>
-  useBottomSheetStore((state) => state.sheetsById[id]?.keepMounted);
+  useBottomSheetStore((state) => state.sheetsById[id]?.keepMounted, shallow);
+export const useSheetPortalSession = (id: string) =>
+  useBottomSheetStore((state) => state.sheetsById[id]?.portalSession, shallow);
 
 export const useSheetExists = (id: string) =>
-  useBottomSheetStore((state) => !!state.sheetsById[id]);
+  useBottomSheetStore((state) => !!state.sheetsById[id], shallow);
 
 export const useIsSheetOpen = (id: string) =>
   useBottomSheetStore((state) => {
     const status = state.sheetsById[id]?.status;
     return status === 'open' || status === 'opening';
-  });
-
-export const useTopSheetId = () =>
-  useBottomSheetStore((state) => getTopSheetId(state.stackOrder));
+  }, shallow);
 
 // Action hooks
 
diff --git a/src/store/store.ts b/src/store/store.ts
index f5f8fb9..fbce896 100644
--- a/src/store/store.ts
+++ b/src/store/store.ts
@@ -10,6 +10,7 @@ import {
   removeFromStack,
   updateSheet,
 } from './helpers';
+import { getNextPortalSession } from '../portalSessionRegistry';
 import type { BottomSheetState, BottomSheetStore } from './types';
 
 export const useBottomSheetStore = create(
@@ -31,6 +32,12 @@ export const useBottomSheetStore = create(
           mode
         );
 
+        // Get next portalSession from registry for portal-based sheets
+        // Registry persists across sheet deletions to ensure unique Portal/PortalHost names
+        const nextPortalSession = sheet.usePortal
+          ? getNextPortalSession(sheet.id)
+          : undefined;
+
         const newSheet: BottomSheetState = existingSheet
           ? {
               ...existingSheet,
@@ -38,8 +45,9 @@ export const useBottomSheetStore = create(
               scaleBackground:
                 sheet.scaleBackground ?? existingSheet.scaleBackground,
               params: sheet.params ?? existingSheet.params,
+              portalSession: nextPortalSession ?? existingSheet.portalSession,
             }
-          : { ...sheet, status: 'opening' };
+          : { ...sheet, status: 'opening', portalSession: nextPortalSession };
 
         return {
           sheetsById: { ...updatedSheetsById, [sheet.id]: newSheet },
diff --git a/src/store/types.ts b/src/store/types.ts
index b9cf02a..6ce4c27 100644
--- a/src/store/types.ts
+++ b/src/store/types.ts
@@ -12,6 +12,12 @@ export interface BottomSheetState {
   usePortal?: boolean;
   params?: Record<string, unknown>;
   keepMounted?: boolean;
+  /**
+   * Incremented each time a portal-based sheet is opened.
+   * Used to create unique Portal/PortalHost names to work around
+   * react-native-teleport connection issues after replace flows.
+   */
+  portalSession?: number;
 }
 
 export type TriggerState = Omit<BottomSheetState, 'status'>;
diff --git a/src/useBottomSheetContext.ts b/src/useBottomSheetContext.ts
index 19433b8..7965885 100644
--- a/src/useBottomSheetContext.ts
+++ b/src/useBottomSheetContext.ts
@@ -1,5 +1,5 @@
 import { useMaybeBottomSheetContext } from './BottomSheet.context';
-import { useSheet, useStartClosing } from './bottomSheet.store';
+import { useSheetParams, useStartClosing } from './bottomSheet.store';
 import type {
   BottomSheetPortalId,
   BottomSheetPortalParams,
@@ -23,22 +23,19 @@ export function useBottomSheetContext<
   T extends BottomSheetPortalId,
 >(): UseBottomSheetContextReturn<BottomSheetPortalParams<T> | unknown> {
   const context = useMaybeBottomSheetContext();
-  const sheet = useSheet(context?.id ?? '');
+  const params = useSheetParams(context?.id || '');
   const startClosing = useStartClosing();
 
-  const id = sheet?.id;
-  const params = sheet?.params;
-
-  if (!id) {
+  if (!context?.id) {
     throw new Error(
       'useBottomSheetContext must be used within a BottomSheet component'
     );
   }
 
-  const close = () => startClosing(id);
+  const close = () => startClosing(context.id);
 
   return {
-    id,
+    id: context.id,
     params: params as BottomSheetPortalParams<T>,
     close,
     closeBottomSheet: close,
diff --git a/src/useBottomSheetStatus.ts b/src/useBottomSheetStatus.ts
index 9d4b6c6..5a7af8d 100644
--- a/src/useBottomSheetStatus.ts
+++ b/src/useBottomSheetStatus.ts
@@ -1,23 +1,15 @@
-import {
-  useSheetStatus,
-  useIsSheetOpen,
-  type BottomSheetStatus,
-} from './bottomSheet.store';
-import type { BottomSheetPortalId } from './portal.types';
+import { useSheetStatus, type BottomSheetStatus } from './bottomSheet.store';
 
 export interface UseBottomSheetStatusReturn {
   status: BottomSheetStatus | null;
   isOpen: boolean;
 }
 
-export function useBottomSheetStatus(
-  id: BottomSheetPortalId
-): UseBottomSheetStatusReturn {
+export function useBottomSheetStatus(id: string): UseBottomSheetStatusReturn {
   const status = useSheetStatus(id) ?? null;
-  const isOpen = useIsSheetOpen(id);
 
   return {
     status,
-    isOpen,
+    isOpen: status === 'open' || status === 'opening',
   };
 }
diff --git a/src/useScaleAnimation.ts b/src/useScaleAnimation.ts
index 6a20d0d..caeae1e 100644
--- a/src/useScaleAnimation.ts
+++ b/src/useScaleAnimation.ts
@@ -2,15 +2,12 @@ import { useRef } from 'react';
 import {
   useAnimatedStyle,
   useDerivedValue,
-  withTiming,
   withSpring,
-  type WithTimingConfig,
+  withTiming,
   type WithSpringConfig,
+  type WithTimingConfig,
 } from 'react-native-reanimated';
-import {
-  useBottomSheetStore,
-  type BottomSheetStore,
-} from './bottomSheet.store';
+import { useBottomSheetStore } from './bottomSheet.store';
 import { useBottomSheetManagerContext } from './BottomSheetManager.provider';
 
 export type ScaleAnimationConfig =
@@ -40,26 +37,47 @@ const DEFAULT_CONFIG = {
   animation: DEFAULT_ANIMATION,
 } satisfies Required<ScaleConfig>;
 
-/**
- * Returns the number of sheets with scaleBackground above a given element.
- * For background wrapper, pass undefined as sheetId - returns 0 or 1 (binary).
- * For sheets, returns the count of scaleBackground sheets above it.
- * Uses shallow comparison internally for optimal re-renders.
- */
-export function useScaleDepth(groupId: string, sheetId?: string): number {
+function useBackgroundScaleDepth(groupId: string): number {
+  return useBottomSheetStore((state) => {
+    const { stackOrder, sheetsById } = state;
+
+    for (let i = 0; i < stackOrder.length; i++) {
+      const id = stackOrder[i]!;
+      const sheet = sheetsById[id];
+      if (
+        sheet &&
+        sheet.groupId === groupId &&
+        sheet.scaleBackground &&
+        sheet.status !== 'closing' &&
+        sheet.status !== 'hidden'
+      ) {
+        return 1;
+      }
+    }
+    return 0;
+  });
+}
+
+function useSheetScaleDepth(
+  groupId: string,
+  sheetId: string | undefined
+): number {
   const prevDepthRef = useRef(0);
 
-  const scaleDepthSelector = (state: BottomSheetStore) => {
-    const { stackOrder, sheetsById } = state;
+  return useBottomSheetStore((state) => {
+    if (!sheetId) {
+      return 0;
+    }
 
-    const startIndex = sheetId ? stackOrder.indexOf(sheetId) + 1 : 0;
+    const { stackOrder, sheetsById } = state;
+    const sheetIndex = stackOrder.indexOf(sheetId);
 
-    if (sheetId && startIndex === 0) {
+    if (sheetIndex === -1) {
       return prevDepthRef.current;
     }
 
     let depth = 0;
-    for (let i = startIndex; i < stackOrder.length; i++) {
+    for (let i = sheetIndex + 1; i < stackOrder.length; i++) {
       const id = stackOrder[i]!;
       const sheet = sheetsById[id];
       if (
@@ -70,26 +88,16 @@ export function useScaleDepth(groupId: string, sheetId?: string): number {
         sheet.status !== 'hidden'
       ) {
         depth++;
-        if (!sheetId) {
-          break;
-        }
       }
     }
 
     prevDepthRef.current = depth;
     return depth;
-  };
-
-  return useBottomSheetStore(scaleDepthSelector);
+  });
 }
 
-/**
- * Returns animated style for scale effect based on depth.
- * Uses power scaling: scale^depth for cascading effect.
- */
 export function useScaleAnimatedStyle({ id }: { id?: string } = {}) {
   const { groupId, scaleConfig } = useBottomSheetManagerContext();
-  const scaleDepth = useScaleDepth(groupId, id);
 
   const {
     scale = DEFAULT_CONFIG.scale,
@@ -98,6 +106,14 @@ export function useScaleAnimatedStyle({ id }: { id?: string } = {}) {
     animation = DEFAULT_CONFIG.animation,
   } = scaleConfig ?? {};
 
+  const isBackground = id === undefined;
+
+  const backgroundDepth = useBackgroundScaleDepth(groupId);
+  const sheetDepth = useSheetScaleDepth(groupId, id);
+
+  const scaleDepth = isBackground ? backgroundDepth : sheetDepth;
+
+  // Animate the depth change
   const progress = useDerivedValue(() => {
     if (animation.type === 'spring') {
       return withSpring(scaleDepth, animation.config);

From c45b8244d5987cee8de47d473514431833936cb3 Mon Sep 17 00:00:00 2001
From: Arkadiusz Kubaczkowski <arek.kubaczkowski@gmail.com>
Date: Thu, 22 Jan 2026 09:23:00 +0100
Subject: [PATCH 6/7] fix: cleanup function

---
 src/QueueItem.tsx | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/src/QueueItem.tsx b/src/QueueItem.tsx
index 528e74f..6fa44cc 100644
--- a/src/QueueItem.tsx
+++ b/src/QueueItem.tsx
@@ -35,10 +35,8 @@ export function QueueItem({ id, stackIndex, isActive }: QueueItemProps) {
 
   useEffect(() => {
     return () => {
-      if (!keepMounted) {
-        cleanupSheetRef(id);
-        cleanupAnimatedIndex(id);
-      }
+      cleanupSheetRef(id);
+      cleanupAnimatedIndex(id);
     };
   }, [id, keepMounted]);
 

From bd5077cb3e5683bbca47b5016d6f25fef7cd6e9c Mon Sep 17 00:00:00 2001
From: Arkadiusz Kubaczkowski <arek.kubaczkowski@gmail.com>
Date: Thu, 22 Jan 2026 09:24:37 +0100
Subject: [PATCH 7/7] fix: remove tests from workflow

---
 .github/workflows/ci.yml | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 40b6571..97daa15 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -35,9 +35,6 @@ jobs:
       - name: Setup
         uses: ./.github/actions/setup
 
-      - name: Run unit tests
-        run: yarn test --maxWorkers=2 --coverage
-
   build-library:
     runs-on: ubuntu-latest
     steps: