From 63f173cbf3c327386a56c9132865d395fbe5786b Mon Sep 17 00:00:00 2001
From: VadymBezpalko <vadym@gigaverse.com>
Date: Tue, 8 Sep 2026 14:49:02 +0200
Subject: [PATCH 01/13] feat(host): wrap each inline sheet's content with an
 optional SheetWrapper

A throw in an inline sheet's body could only be caught above the host, which
unmounts every sheet in the group. The wrapper renders inside each sheet's
context with the ref the coordinator drives, so an app can put a boundary
around one sheet and render a fallback adapter in its place. Portal and
persistent sheets render at their declaration site and are not wrapped.
---
 src/BottomSheetHost.tsx     |  23 +++++++-
 src/QueueItem.tsx           |  28 ++++++++--
 src/__tests__/host.test.tsx | 102 ++++++++++++++++++++++++++++++++++++
 src/index.tsx               |   1 +
 4 files changed, 149 insertions(+), 5 deletions(-)
 create mode 100644 src/__tests__/host.test.tsx

diff --git a/src/BottomSheetHost.tsx b/src/BottomSheetHost.tsx
index 2fcdd53..395a66a 100644
--- a/src/BottomSheetHost.tsx
+++ b/src/BottomSheetHost.tsx
@@ -1,5 +1,6 @@
-import { useEffect } from 'react';
+import { useEffect, type ComponentType, type ReactNode } from 'react';
 
+import type { SheetRef } from './adapter.types';
 import { useBottomSheetStore, useClearGroup } from './store';
 import { initBottomSheetCoordinator } from './bottomSheetCoordinator';
 import { useBottomSheetManagerContext } from './BottomSheetManager.context';
@@ -77,7 +78,24 @@ function reconcilePendingTransitions(groupId: string): () => void {
   };
 }
 
-export function BottomSheetHost() {
+export interface SheetWrapperProps {
+  id: string;
+  /** The ref the coordinator drives; a fallback adapter binds to it so expand/close keep reaching the sheet. */
+  sheetRef: SheetRef;
+  children: ReactNode;
+}
+
+interface BottomSheetHostProps {
+  /**
+   * Wraps each inline sheet's content inside its context — the place for a
+   * per-sheet error boundary whose fallback is an adapter bound to `sheetRef`.
+   * Portal and persistent sheets render where they are declared and are not
+   * wrapped. Must be a module-scope component: `QueueItem` is memoized.
+   */
+  SheetWrapper?: ComponentType<SheetWrapperProps>;
+}
+
+export function BottomSheetHost({ SheetWrapper }: BottomSheetHostProps) {
   const sheetRenderData = useSheetRenderData();
   const clearGroup = useClearGroup();
   const { groupId } = useBottomSheetManagerContext();
@@ -105,6 +123,7 @@ export function BottomSheetHost() {
           id={id}
           stackIndex={stackIndex}
           isActive={isActive}
+          SheetWrapper={SheetWrapper}
         />
       ))}
     </>
diff --git a/src/QueueItem.tsx b/src/QueueItem.tsx
index 915c418..1872682 100644
--- a/src/QueueItem.tsx
+++ b/src/QueueItem.tsx
@@ -1,4 +1,9 @@
-import { memo, useEffect, type PropsWithChildren } from 'react';
+import {
+  memo,
+  useEffect,
+  type ComponentType,
+  type PropsWithChildren,
+} from 'react';
 import { StyleSheet, View } from 'react-native';
 import Animated from 'react-native-reanimated';
 import { useSafeAreaFrame } from 'react-native-safe-area-context';
@@ -15,20 +20,23 @@ import {
   useSheetUsePortal,
 } from './store';
 import { BottomSheetBackdrop } from './BottomSheetBackdrop';
+import type { SheetWrapperProps } from './BottomSheetHost';
 import { removeOnBeforeClose } from './onBeforeCloseRegistry';
-import { cleanupSheetRef } from './refsMap';
+import { cleanupSheetRef, getSheetRef } from './refsMap';
 import { useSheetScaleAnimatedStyle } from './useScaleAnimation';
 
 interface QueueItemProps {
   id: string;
   stackIndex: number;
   isActive: boolean;
+  SheetWrapper?: ComponentType<SheetWrapperProps>;
 }
 
 export const QueueItem = memo(function QueueItem({
   id,
   stackIndex,
   isActive,
+  SheetWrapper,
 }: QueueItemProps) {
   const content = useSheetContent(id);
   const usePortal = useSheetUsePortal(id);
@@ -43,6 +51,20 @@ export const QueueItem = memo(function QueueItem({
 
   const animatedIndex = getAnimatedIndex(id);
 
+  // Safe to read during render: `open()` registers the ref before the store
+  // write that schedules this render, and the entry outlives the item. A
+  // persistent id can be re-registered under a mounted item, hence the guard.
+  const sheetRef = usePortal ? undefined : getSheetRef(id);
+
+  const inlineContent =
+    SheetWrapper && sheetRef ? (
+      <SheetWrapper id={id} sheetRef={sheetRef}>
+        {content}
+      </SheetWrapper>
+    ) : (
+      content
+    );
+
   useEffect(() => {
     return () => {
       cleanupSheetRef(id);
@@ -82,7 +104,7 @@ export const QueueItem = memo(function QueueItem({
           />
         ) : (
           <BottomSheetContext.Provider value={{ id }}>
-            {content}
+            {inlineContent}
           </BottomSheetContext.Provider>
         )}
       </ScaleWrapper>
diff --git a/src/__tests__/host.test.tsx b/src/__tests__/host.test.tsx
new file mode 100644
index 0000000..a4862bc
--- /dev/null
+++ b/src/__tests__/host.test.tsx
@@ -0,0 +1,102 @@
+import { Component, type ReactElement } from 'react';
+import { Text } from 'react-native';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+import { act, render } from '@testing-library/react-native';
+
+import { BottomSheetHost, type SheetWrapperProps } from '../BottomSheetHost';
+import { BottomSheetManagerProvider } from '../BottomSheetManager.provider';
+import { getSheetRef, setSheetRef } from '../refsMap';
+import { useBottomSheetContext } from '../useBottomSheetContext';
+import { makeRef, portal, setupSheetTest, store } from './testUtils';
+
+// QueueItem measures the frame, which the real provider reads from native.
+const initialMetrics = {
+  frame: { x: 0, y: 0, width: 390, height: 844 },
+  insets: { top: 0, left: 0, right: 0, bottom: 0 },
+};
+
+setupSheetTest();
+
+/** What `useBottomSheetManager().open()` does: store first, ref registered after. */
+const openInline = (id: string, content: ReactElement, groupId = 'g1') => {
+  store().open({ kind: 'inline', id, groupId, content });
+  setSheetRef(id, makeRef());
+};
+
+const renderHost = (SheetWrapper?: React.ComponentType<SheetWrapperProps>) =>
+  render(
+    <SafeAreaProvider initialMetrics={initialMetrics}>
+      <BottomSheetManagerProvider id="g1">
+        <BottomSheetHost SheetWrapper={SheetWrapper} />
+      </BottomSheetManagerProvider>
+    </SafeAreaProvider>
+  );
+
+describe('BottomSheetHost SheetWrapper', () => {
+  it('renders inline content unchanged when no wrapper is given', () => {
+    const screen = renderHost();
+    act(() => openInline('a', <Text>body</Text>));
+    expect(screen.getByText('body')).toBeTruthy();
+  });
+
+  it('wraps each inline sheet with the wrapper, inside the sheet context', () => {
+    const seen: Array<{ id: string; sheetRef: unknown; contextId: string }> =
+      [];
+    const Wrapper = ({ id, sheetRef, children }: SheetWrapperProps) => {
+      const context = useBottomSheetContext();
+      seen.push({ id, sheetRef, contextId: context.id });
+      return <>{children}</>;
+    };
+    const screen = renderHost(Wrapper);
+
+    act(() => openInline('a', <Text>body</Text>));
+
+    expect(screen.getByText('body')).toBeTruthy();
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toEqual({
+      id: 'a',
+      sheetRef: getSheetRef('a'),
+      contextId: 'a',
+    });
+  });
+
+  // Portal content renders at its declaration site; the host only mounts a
+  // PortalHost, so there is nothing for a wrapper to catch there.
+  it('does not wrap portal sheets', () => {
+    const Wrapper = jest.fn(({ children }: SheetWrapperProps) => (
+      <>{children}</>
+    ));
+    renderHost(Wrapper);
+
+    act(() => store().open(portal('p')));
+
+    expect(Wrapper).not.toHaveBeenCalled();
+  });
+
+  it('lets a boundary replace one sheet while the others stay mounted', () => {
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+    class Boundary extends Component<SheetWrapperProps, { failed: boolean }> {
+      state = { failed: false };
+      static getDerivedStateFromError() {
+        return { failed: true };
+      }
+      render() {
+        return this.state.failed ? <Text>fallback</Text> : this.props.children;
+      }
+    }
+    const Throws = () => {
+      throw new Error('boom');
+    };
+    const screen = renderHost(Boundary);
+
+    act(() => {
+      openInline('a', <Text>first</Text>);
+      store().markOpen('a');
+      openInline('b', <Throws />);
+    });
+
+    expect(screen.getByText('first')).toBeTruthy();
+    expect(screen.getByText('fallback')).toBeTruthy();
+    expect(store().stackOrderByGroup.g1).toEqual(['a', 'b']);
+  });
+});
diff --git a/src/index.tsx b/src/index.tsx
index fc92ead..5746b84 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -67,6 +67,7 @@ export {
 export { useOnBeforeClose } from './useOnBeforeClose';
 
 // Types
+export type { SheetWrapperProps } from './BottomSheetHost';
 export type { BackdropConfig, BackdropComponentProps } from './backdrop.types';
 export type { ScaleConfig, ScaleAnimationConfig } from './useScaleAnimation';
 export type {

From ed1740468e96dc4d3567f7b921ce8293f0c3a50f Mon Sep 17 00:00:00 2001
From: VadymBezpalko <vadym@gigaverse.com>
Date: Tue, 8 Sep 2026 14:49:52 +0200
Subject: [PATCH 02/13] fix(adapter): expand an adapter that mounts into an
 already-open sheet
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The coordinator reacts to status changes, so an adapter mounted after the sheet
reached 'open' — a fallback rendered by a host SheetWrapper — was never driven
and sat closed under an open status. useAdapterRef now catches up once on mount.
---
 src/__tests__/adapterRef.test.tsx | 52 +++++++++++++++++++++++++++++++
 src/useAdapterRef.ts              | 22 +++++++++++--
 2 files changed, 72 insertions(+), 2 deletions(-)
 create mode 100644 src/__tests__/adapterRef.test.tsx

diff --git a/src/__tests__/adapterRef.test.tsx b/src/__tests__/adapterRef.test.tsx
new file mode 100644
index 0000000..fb1973e
--- /dev/null
+++ b/src/__tests__/adapterRef.test.tsx
@@ -0,0 +1,52 @@
+import { renderHook } from '@testing-library/react-native';
+
+import { BottomSheetRefContext } from '../BottomSheetRef.context';
+import { useAdapterRef } from '../useAdapterRef';
+import { inSheet, makeRef, portal, setupSheetTest, store } from './testUtils';
+
+setupSheetTest();
+
+describe('useAdapterRef', () => {
+  it('prefers the ref from context over the forwarded one', () => {
+    const contextRef = makeRef();
+    const forwarded = makeRef();
+    const { result } = renderHook(() => useAdapterRef(forwarded), {
+      wrapper: ({ children }) => (
+        <BottomSheetRefContext.Provider value={contextRef}>
+          {children}
+        </BottomSheetRefContext.Provider>
+      ),
+    });
+    expect(result.current).toBe(contextRef);
+  });
+
+  it('expands on mount when the sheet is already open', () => {
+    store().open(portal('a'));
+    store().markOpen('a');
+    const ref = makeRef();
+
+    renderHook(() => useAdapterRef(ref), { wrapper: inSheet('a') });
+
+    expect(ref.current.expand).toHaveBeenCalledTimes(1);
+  });
+
+  it('leaves an opening sheet to the coordinator', () => {
+    store().open(portal('a'));
+    const ref = makeRef();
+
+    renderHook(() => useAdapterRef(ref), { wrapper: inSheet('a') });
+
+    expect(ref.current.expand).not.toHaveBeenCalled();
+  });
+
+  it('does nothing for a hidden persistent sheet or outside a sheet context', () => {
+    store().mount({ id: 'p', groupId: 'g1' });
+    const hiddenRef = makeRef();
+    renderHook(() => useAdapterRef(hiddenRef), { wrapper: inSheet('p') });
+    expect(hiddenRef.current.expand).not.toHaveBeenCalled();
+
+    const bareRef = makeRef();
+    renderHook(() => useAdapterRef(bareRef));
+    expect(bareRef.current.expand).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/useAdapterRef.ts b/src/useAdapterRef.ts
index eac2368..62dde2d 100644
--- a/src/useAdapterRef.ts
+++ b/src/useAdapterRef.ts
@@ -1,7 +1,9 @@
-import type { ForwardedRef } from 'react';
+import { useEffect, type ForwardedRef } from 'react';
 
 import type { SheetAdapterRef, SheetRef } from './adapter.types';
+import { useMaybeBottomSheetContext } from './BottomSheet.context';
 import { useMaybeBottomSheetRef } from './BottomSheetRef.context';
+import { useBottomSheetStore } from './store';
 
 /**
  * Returns the correct ref for a custom adapter.
@@ -24,5 +26,21 @@ export function useAdapterRef(
   forwardedRef: ForwardedRef<SheetAdapterRef>
 ): SheetRef | ForwardedRef<SheetAdapterRef> {
   const contextRef = useMaybeBottomSheetRef();
-  return contextRef ?? forwardedRef;
+  const ref = contextRef ?? forwardedRef;
+  const id = useMaybeBottomSheetContext()?.id;
+
+  // The coordinator drives status *changes* only, so an adapter mounted under
+  // an already-open sheet (a wrapper's fallback) has nobody else to open it.
+  // Passive effect: the imperative handle is attached by then.
+  useEffect(() => {
+    if (!id || typeof ref !== 'object') {
+      return;
+    }
+    if (useBottomSheetStore.getState().sheetsById[id]?.status !== 'open') {
+      return;
+    }
+    ref?.current?.expand();
+  }, [id, ref]);
+
+  return ref;
 }

From 4a0ffee3862ae4e4a9d37c5b9c30a3d00cda2baa Mon Sep 17 00:00:00 2001
From: VadymBezpalko <vadym@gigaverse.com>
Date: Tue, 8 Sep 2026 14:52:22 +0200
Subject: [PATCH 03/13] test(host): a fallback adapter replaces a sheet that
 throws after opening

---
 src/__tests__/host.test.tsx | 80 ++++++++++++++++++++++++++++++++++---
 1 file changed, 75 insertions(+), 5 deletions(-)

diff --git a/src/__tests__/host.test.tsx b/src/__tests__/host.test.tsx
index a4862bc..1c8744b 100644
--- a/src/__tests__/host.test.tsx
+++ b/src/__tests__/host.test.tsx
@@ -1,15 +1,22 @@
-import { Component, type ReactElement } from 'react';
+import {
+  Component,
+  createRef,
+  useImperativeHandle,
+  type ReactElement,
+} from 'react';
 import { Text } from 'react-native';
 import { SafeAreaProvider } from 'react-native-safe-area-context';
 import { act, render } from '@testing-library/react-native';
 
 import { BottomSheetHost, type SheetWrapperProps } from '../BottomSheetHost';
 import { BottomSheetManagerProvider } from '../BottomSheetManager.provider';
+import type { SheetAdapterRef } from '../adapter.types';
 import { getSheetRef, setSheetRef } from '../refsMap';
+import { useAdapterRef } from '../useAdapterRef';
 import { useBottomSheetContext } from '../useBottomSheetContext';
 import { makeRef, portal, setupSheetTest, store } from './testUtils';
 
-// QueueItem measures the frame, which the real provider reads from native.
+// QueueItem reads the frame, which the real provider gets from native.
 const initialMetrics = {
   frame: { x: 0, y: 0, width: 390, height: 844 },
   insets: { top: 0, left: 0, right: 0, bottom: 0 },
@@ -17,7 +24,6 @@ const initialMetrics = {
 
 setupSheetTest();
 
-/** What `useBottomSheetManager().open()` does: store first, ref registered after. */
 const openInline = (id: string, content: ReactElement, groupId = 'g1') => {
   store().open({ kind: 'inline', id, groupId, content });
   setSheetRef(id, makeRef());
@@ -32,6 +38,40 @@ const renderHost = (SheetWrapper?: React.ComponentType<SheetWrapperProps>) =>
     </SafeAreaProvider>
   );
 
+const fallbackExpand = jest.fn();
+
+// Module scope: the compiler outlines the `useImperativeHandle` factory there,
+// so a spy declared inside a test would be out of its reach.
+const FallbackAdapter = ({
+  sheetRef,
+}: {
+  sheetRef: SheetWrapperProps['sheetRef'];
+}) => {
+  const ref = useAdapterRef(sheetRef);
+  useImperativeHandle(ref, () => ({
+    expand: fallbackExpand,
+    close: jest.fn(),
+  }));
+  return <Text>fallback</Text>;
+};
+
+class FallbackBoundary extends Component<
+  SheetWrapperProps,
+  { failed: boolean }
+> {
+  state = { failed: false };
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+  render() {
+    return this.state.failed ? (
+      <FallbackAdapter sheetRef={this.props.sheetRef} />
+    ) : (
+      this.props.children
+    );
+  }
+}
+
 describe('BottomSheetHost SheetWrapper', () => {
   it('renders inline content unchanged when no wrapper is given', () => {
     const screen = renderHost();
@@ -60,8 +100,6 @@ describe('BottomSheetHost SheetWrapper', () => {
     });
   });
 
-  // Portal content renders at its declaration site; the host only mounts a
-  // PortalHost, so there is nothing for a wrapper to catch there.
   it('does not wrap portal sheets', () => {
     const Wrapper = jest.fn(({ children }: SheetWrapperProps) => (
       <>{children}</>
@@ -99,4 +137,36 @@ describe('BottomSheetHost SheetWrapper', () => {
     expect(screen.getByText('fallback')).toBeTruthy();
     expect(store().stackOrderByGroup.g1).toEqual(['a', 'b']);
   });
+
+  it('drives a fallback adapter that replaces a sheet which throws after opening', () => {
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+    fallbackExpand.mockClear();
+
+    const Crashable = () => {
+      const { params } = useBottomSheetContext();
+      if ((params as { crash?: boolean } | undefined)?.crash) {
+        throw new Error('boom');
+      }
+      return <Text>alive</Text>;
+    };
+
+    const screen = renderHost(FallbackBoundary);
+    act(() => {
+      store().open({
+        kind: 'inline',
+        id: 'a',
+        groupId: 'g1',
+        content: <Crashable />,
+      });
+      setSheetRef('a', createRef<SheetAdapterRef>());
+      store().markOpen('a');
+    });
+    expect(screen.getByText('alive')).toBeTruthy();
+
+    act(() => store().updateParams('a', { crash: true }));
+
+    expect(screen.getByText('fallback')).toBeTruthy();
+    expect(getSheetRef('a')?.current?.expand).toBe(fallbackExpand);
+    expect(fallbackExpand).toHaveBeenCalledTimes(1);
+  });
 });

From d82993b90a8419563002cf6f78fcfefa227cd194 Mon Sep 17 00:00:00 2001
From: VadymBezpalko <vadym@gigaverse.com>
Date: Tue, 8 Sep 2026 14:53:53 +0200
Subject: [PATCH 04/13] docs: document SheetWrapper and the adapter catch-up on
 mount

---
 CLAUDE.md                    | 23 +++++++++++++++++++++++
 docs/docs/api/components.md  | 35 +++++++++++++++++++++++++++++++++++
 docs/docs/api/types.md       | 14 ++++++++++++++
 docs/docs/custom-adapters.md |  2 ++
 4 files changed, 74 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index cd7c4ad..6422fba 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -126,6 +126,14 @@ adapter mounts (a portal sheet must teleport first); a single attempt silently
 no-ops and wedges the sheet — and for `'closing'`, wedges every later open in the
 group on the `group-busy` guard.
 
+`useAdapterRef` catches up once on mount when the sheet is already `open`
+(`ref.current.expand()`): the coordinator drives status *changes*, so an adapter
+that replaces another under an open status has nobody else to open it.
+`opening` is left to `driveSheetRef`; `closing`/`hidden` are not caught up — an
+adapter that never opened cannot animate a close; the honest action would be
+`finishClosing(id)` as in `driveSheetRef`'s give-up path, deliberately not done
+yet.
+
 Also exported publicly for adapter authors: `requestClose(id)` and
 `closeAllAnimated(groupId, opts)`.
 
@@ -198,6 +206,21 @@ backdrop below its own sheet but above the one beneath. The offset lifts the
 whole stack above arbitrary app chrome — without it any host view with a modest
 `zIndex` paints over the sheets.
 
+`BottomSheetHost` takes `SheetWrapper?: ComponentType<SheetWrapperProps>`;
+`QueueItem` renders it around an inline sheet's `content`, inside
+`BottomSheetContext`, with `getSheetRef(id)` as `sheetRef`. The render-time
+registry read is sound because `open()` writes the store and registers the ref
+in the same synchronous call, and the store write only *schedules* the render
+that mounts the item — the item's first render already sees the final entry,
+which it must, because the compiler caches the read on `id` and never re-runs
+it. An inline id is minted per open and the item's unmount cleanup removes it,
+so the value cannot change while the item is mounted; the read is guarded on
+`usePortal` because a persistent id *can* be re-registered under a
+still-mounted item. A caller-supplied inline id re-opened in the same tick as
+its removal hands the wrapper the previous ref; the coordinator reads the
+registry fresh, so the sheet still closes via the give-up path. The prop must be
+a module-scope component — `QueueItem` is `memo`.
+
 `BottomSheetBackdrop` is mounted from the sheet's first frame and faded purely by
 `animatedIndex`. Do not add a timer or delay gate: deferring the mount drops the
 opening frames the adapter already drove, and the backdrop pops in mid-fade.
diff --git a/docs/docs/api/components.md b/docs/docs/api/components.md
index c98a8ae..eabe8af 100644
--- a/docs/docs/api/components.md
+++ b/docs/docs/api/components.md
@@ -45,6 +45,41 @@ Renders the bottom sheet stack. Must be placed inside `BottomSheetManagerProvide
 Place `BottomSheetHost` **outside** of `BottomSheetScaleView` to prevent sheets from scaling.
 :::
 
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `SheetWrapper` | `React.ComponentType<SheetWrapperProps>` | Rendered around every **inline** sheet's content, inside that sheet's context. Receives `{ id, sheetRef, children }`. Portal and persistent sheets render where they are declared and are not wrapped. Define it at module scope. |
+
+Use it to put an error boundary around each sheet, so one sheet failing never takes the host down. The fallback renders an adapter bound to `sheetRef`, and the manager keeps driving the sheet — `useBottomSheetContext().close()` still closes it:
+
+```tsx
+class SheetErrorBoundary extends React.Component<
+  SheetWrapperProps,
+  { failed: boolean }
+> {
+  state = { failed: false };
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+  render() {
+    if (!this.state.failed) {
+      return this.props.children;
+    }
+    return (
+      <CustomModalAdapter ref={this.props.sheetRef}>
+        <Text>This sheet could not be shown.</Text>
+        <CloseButton />
+      </CustomModalAdapter>
+    );
+  }
+}
+
+<BottomSheetHost SheetWrapper={SheetErrorBoundary} />;
+```
+
+An adapter that mounts while its sheet is already `open` is expanded on mount, so the fallback appears in place without extra wiring.
+
 ---
 
 ## BottomSheetScaleView
diff --git a/docs/docs/api/types.md b/docs/docs/api/types.md
index 8d35c8b..05e104c 100644
--- a/docs/docs/api/types.md
+++ b/docs/docs/api/types.md
@@ -195,6 +195,20 @@ type SheetRef = RefObject<SheetAdapterRef | null>;
 
 ---
 
+### SheetWrapperProps
+
+```ts
+interface SheetWrapperProps {
+  id: string; // same as useBottomSheetContext().id
+  sheetRef: SheetRef; // the ref the coordinator drives; bind a fallback adapter to it
+  children: ReactNode;
+}
+```
+
+Props of the component passed to `BottomSheetHost`'s `SheetWrapper`.
+
+---
+
 ## Configuration Types
 
 ### ScaleConfig
diff --git a/docs/docs/custom-adapters.md b/docs/docs/custom-adapters.md
index ada0809..963e0b7 100644
--- a/docs/docs/custom-adapters.md
+++ b/docs/docs/custom-adapters.md
@@ -292,6 +292,8 @@ const ref = useAdapterRef(forwardedRef);
 useImperativeHandle(ref, () => ({ expand: ..., close: ... }));
 ```
 
+An adapter that mounts while its sheet is already `open` is expanded once on mount. The coordinator only reacts to status changes, so this is what lets an adapter rendered *in place of* another — an error-boundary fallback under `BottomSheetHost`'s `SheetWrapper` — come up open. Your adapter needs nothing extra for it beyond `useAdapterRef` + `useImperativeHandle`.
+
 ### Prop-Controlled vs Ref-Controlled Libraries
 
 **Ref-controlled** (e.g., TrueSheet with `present()`/`dismiss()`):

From cb69e4ea422a6d0c184a98d8a9903684052c4361 Mon Sep 17 00:00:00 2001
From: VadymBezpalko <vadym@gigaverse.com>
Date: Tue, 8 Sep 2026 14:55:30 +0200
Subject: [PATCH 05/13] feat(example): error boundary around each inline sheet

---
 example/src/App.tsx                           |  8 +-
 example/src/components/SheetErrorBoundary.tsx | 84 +++++++++++++++++++
 example/src/components/index.ts               |  1 +
 example/src/screens/HomeScreen.tsx            | 10 +++
 example/src/sheets/ErrorBoundarySheets.tsx    | 42 ++++++++++
 example/src/sheets/index.ts                   |  1 +
 6 files changed, 145 insertions(+), 1 deletion(-)
 create mode 100644 example/src/components/SheetErrorBoundary.tsx
 create mode 100644 example/src/sheets/ErrorBoundarySheets.tsx

diff --git a/example/src/App.tsx b/example/src/App.tsx
index fd09c07..4b27ff6 100644
--- a/example/src/App.tsx
+++ b/example/src/App.tsx
@@ -9,6 +9,7 @@ import { KeyboardProvider } from 'react-native-keyboard-controller';
 import { SafeAreaProvider } from 'react-native-safe-area-context';
 
 import { BottomSheetDebugMonitor } from './components/BottomSheetDebugMonitor';
+import { SheetErrorBoundary } from './components/SheetErrorBoundary';
 import { UserProvider } from './context/UserContext';
 import { HomeScreen } from './screens';
 import {
@@ -37,7 +38,12 @@ export default function App() {
                 <HomeScreen />
               </UserProvider>
             </BottomSheetScaleView>
-            <BottomSheetHost />
+            {/*
+              Every inline sheet in this group renders inside
+              SheetErrorBoundary, so a sheet whose body throws is replaced by a
+              fallback sheet instead of taking the host down with it.
+            */}
+            <BottomSheetHost SheetWrapper={SheetErrorBoundary} />
             {/* Persistent sheet - always mounted, opens instantly */}
             <BottomSheetPersistent id="scanner-sheet">
               <ScannerSheet />
diff --git a/example/src/components/SheetErrorBoundary.tsx b/example/src/components/SheetErrorBoundary.tsx
new file mode 100644
index 0000000..83016d8
--- /dev/null
+++ b/example/src/components/SheetErrorBoundary.tsx
@@ -0,0 +1,84 @@
+import { Component } from 'react';
+import { StyleSheet, Text, View } from 'react-native';
+import {
+  CustomModalAdapter,
+  useBottomSheetContext,
+  type SheetWrapperProps,
+} from 'react-native-bottom-sheet-stack';
+
+import { colors, sharedStyles } from '../styles/theme';
+import { Badge } from './Badge';
+import { Button, SecondaryButton } from './Button';
+
+/** Replaces the sheet that threw; bound to its ref, so the manager keeps driving it. */
+function FallbackSheet({
+  sheetRef,
+  onRetry,
+}: {
+  sheetRef: SheetWrapperProps['sheetRef'];
+  onRetry: () => void;
+}) {
+  const { close } = useBottomSheetContext();
+
+  return (
+    <CustomModalAdapter ref={sheetRef} contentContainerStyle={styles.overlay}>
+      <View style={styles.card}>
+        <Badge label="Fallback" color={colors.error} />
+        <Text style={sharedStyles.h1}>This sheet could not be shown</Text>
+        <Text style={sharedStyles.text}>
+          Its content threw while rendering. The host and every other sheet in
+          the stack are untouched — only this one was replaced.
+        </Text>
+        <View style={styles.actions}>
+          <Button title="Retry" onPress={onRetry} />
+          <SecondaryButton title="Close" onPress={close} />
+        </View>
+      </View>
+    </CustomModalAdapter>
+  );
+}
+
+/** Module scope on purpose: `QueueItem` is memoized. */
+export class SheetErrorBoundary extends Component<
+  SheetWrapperProps,
+  { failed: boolean }
+> {
+  state = { failed: false };
+
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+
+  render() {
+    if (!this.state.failed) {
+      return this.props.children;
+    }
+
+    return (
+      <FallbackSheet
+        sheetRef={this.props.sheetRef}
+        onRetry={() => this.setState({ failed: false })}
+      />
+    );
+  }
+}
+
+const styles = StyleSheet.create({
+  overlay: {
+    backgroundColor: 'rgba(0, 0, 0, 0.6)',
+    paddingHorizontal: 24,
+  },
+  card: {
+    backgroundColor: colors.surface,
+    borderRadius: 20,
+    padding: 24,
+    width: '100%',
+    borderWidth: 1,
+    borderColor: colors.border,
+    gap: 8,
+  },
+  actions: {
+    gap: 12,
+    marginTop: 12,
+  },
+});
diff --git a/example/src/components/index.ts b/example/src/components/index.ts
index 25d63a0..dda458f 100644
--- a/example/src/components/index.ts
+++ b/example/src/components/index.ts
@@ -2,3 +2,4 @@ export { Badge } from './Badge';
 export { Button, SecondaryButton, SmallButton } from './Button';
 export { DemoCard, FeatureItem } from './DemoCard';
 export { Sheet } from './Sheet';
+export { SheetErrorBoundary } from './SheetErrorBoundary';
diff --git a/example/src/screens/HomeScreen.tsx b/example/src/screens/HomeScreen.tsx
index 5c7db40..342af30 100644
--- a/example/src/screens/HomeScreen.tsx
+++ b/example/src/screens/HomeScreen.tsx
@@ -13,6 +13,7 @@ import {
   BackdropDemo,
   ContextComparisonSheet,
   ContextSheetPortal,
+  ErrorBoundaryDemoSheet,
   ForceCloseDemo,
   GroupASheet,
   HeavySheet,
@@ -216,6 +217,15 @@ export function HomeScreen() {
             onPress={() => open(<ForceCloseDemo />, { scaleBackground: true })}
           />
 
+          <DemoCard
+            title="Sheet error boundary"
+            description="Crash one inline sheet's body — a fallback sheet replaces it, the host stays up"
+            color={colors.error}
+            onPress={() =>
+              open(<ErrorBoundaryDemoSheet />, { scaleBackground: true })
+            }
+          />
+
           <DemoCard
             title="Group Isolation"
             description="Two managers, two stacks — closeAll() in one leaves the other standing"
diff --git a/example/src/sheets/ErrorBoundarySheets.tsx b/example/src/sheets/ErrorBoundarySheets.tsx
new file mode 100644
index 0000000..6ef0a9b
--- /dev/null
+++ b/example/src/sheets/ErrorBoundarySheets.tsx
@@ -0,0 +1,42 @@
+import type { BottomSheetMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
+import { forwardRef, useState } from 'react';
+import { Text, View } from 'react-native';
+import { useBottomSheetContext } from 'react-native-bottom-sheet-stack';
+
+import { Badge, Button, SecondaryButton, Sheet } from '../components';
+import { colors, sharedStyles } from '../styles/theme';
+
+/** Throws after it has opened — the case the wrapper exists for. */
+export const ErrorBoundaryDemoSheet = forwardRef<BottomSheetMethods>(
+  (_, ref) => {
+    const { close } = useBottomSheetContext();
+    const [crashed, setCrashed] = useState(false);
+
+    if (crashed) {
+      throw new Error('ErrorBoundaryDemoSheet failed to render');
+    }
+
+    return (
+      <Sheet ref={ref}>
+        <Badge label="Inline" color={colors.error} />
+        <Text style={sharedStyles.h1}>Sheet error boundary</Text>
+        <Text style={sharedStyles.text}>
+          The default host wraps every inline sheet in `SheetErrorBoundary`.
+          Crash this one and a fallback sheet takes its place, bound to the same
+          ref — Retry remounts this content, Close animates the sheet out.
+          Nothing else in the stack notices.
+        </Text>
+
+        <View style={{ gap: 12, marginTop: 8 }}>
+          <Button
+            title="Crash this sheet's body"
+            onPress={() => setCrashed(true)}
+          />
+          <SecondaryButton title="Close" onPress={close} />
+        </View>
+      </Sheet>
+    );
+  }
+);
+
+ErrorBoundaryDemoSheet.displayName = 'ErrorBoundaryDemoSheet';
diff --git a/example/src/sheets/index.ts b/example/src/sheets/index.ts
index d093eb4..b027af9 100644
--- a/example/src/sheets/index.ts
+++ b/example/src/sheets/index.ts
@@ -38,3 +38,4 @@ export {
 } from './BackdropSheets';
 export { GroupASheet, GroupBSheet } from './GroupIsolationSheets';
 export { StatusDemoPanel, StatusDemoSheet } from './SheetStatusSheets';
+export { ErrorBoundaryDemoSheet } from './ErrorBoundarySheets';

From 6562cca7e98b06937bfbe03ee35fb02cc3c19b94 Mon Sep 17 00:00:00 2001
From: VadymBezpalko <vadym@gigaverse.com>
Date: Tue, 8 Sep 2026 21:03:04 +0200
Subject: [PATCH 06/13] fix(manager): reuse the registered ref when an id is
 re-opened
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`open()` minted a fresh ref object for every call, but the registry is keyed
by sheet id alone and `QueueItem` caches its render-time read for the life of
the mounted item. Two cases diverged as a result:

- a caller-supplied inline id removed and re-added inside one JS turn
  (`destroyAll()` + `open()`) never unmounts its item, so the wrapper keeps
  the previous ref while the coordinator drives the new one — a boundary
  fallback then binds its handle to a ref nobody reads, and the next close
  burns the coordinator's frame budget and force-closes without animating;
- a manager open aimed at a mounted persistent id is accepted by the store
  and clobbered the ref that `BottomSheetPersistent` registered on mount,
  leaving a registry entry whose `.current` is null forever, so that sheet
  can never be opened again.

Reusing the registered ref makes "one registered id, one ref object" true by
construction, so every reader agrees without any cache reasoning. This is the
guard `useBottomSheetControl` already applies; the manager was the one writer
without it.
---
 src/__tests__/host.test.tsx   | 105 ++++++++++++++++++++++++++++++++++
 src/useBottomSheetManager.tsx |   8 ++-
 2 files changed, 111 insertions(+), 2 deletions(-)

diff --git a/src/__tests__/host.test.tsx b/src/__tests__/host.test.tsx
index 1c8744b..ca40d84 100644
--- a/src/__tests__/host.test.tsx
+++ b/src/__tests__/host.test.tsx
@@ -1,8 +1,10 @@
 import {
   Component,
   createRef,
+  useEffect,
   useImperativeHandle,
   type ReactElement,
+  type Ref,
 } from 'react';
 import { Text } from 'react-native';
 import { SafeAreaProvider } from 'react-native-safe-area-context';
@@ -10,10 +12,12 @@ import { act, render } from '@testing-library/react-native';
 
 import { BottomSheetHost, type SheetWrapperProps } from '../BottomSheetHost';
 import { BottomSheetManagerProvider } from '../BottomSheetManager.provider';
+import { BottomSheetPersistent } from '../BottomSheetPersistent';
 import type { SheetAdapterRef } from '../adapter.types';
 import { getSheetRef, setSheetRef } from '../refsMap';
 import { useAdapterRef } from '../useAdapterRef';
 import { useBottomSheetContext } from '../useBottomSheetContext';
+import { useBottomSheetManager } from '../useBottomSheetManager';
 import { makeRef, portal, setupSheetTest, store } from './testUtils';
 
 // QueueItem reads the frame, which the real provider gets from native.
@@ -29,15 +33,48 @@ const openInline = (id: string, content: ReactElement, groupId = 'g1') => {
   setSheetRef(id, makeRef());
 };
 
+const managerHolder = {} as { api: ReturnType<typeof useBottomSheetManager> };
+
+const ManagerProbe = () => {
+  const api = useBottomSheetManager();
+  useEffect(() => {
+    managerHolder.api = api;
+  });
+  return null;
+};
+
 const renderHost = (SheetWrapper?: React.ComponentType<SheetWrapperProps>) =>
   render(
     <SafeAreaProvider initialMetrics={initialMetrics}>
       <BottomSheetManagerProvider id="g1">
+        <ManagerProbe />
         <BottomSheetHost SheetWrapper={SheetWrapper} />
       </BottomSheetManagerProvider>
     </SafeAreaProvider>
   );
 
+const seenSheetRefs: unknown[] = [];
+const lastSeenSheetRef = () => seenSheetRefs[seenSheetRefs.length - 1];
+
+const RecordingWrapper = ({ sheetRef, children }: SheetWrapperProps) => {
+  seenSheetRefs.push(sheetRef);
+  return <>{children}</>;
+};
+
+// Stands in for an adapter, so the ref `open()` clones in carries a handle the
+// coordinator can drive. Module scope: the compiler outlines the
+// `useImperativeHandle` factory there.
+const BodyAdapter = ({
+  label,
+  ref,
+}: {
+  label: string;
+  ref?: Ref<SheetAdapterRef>;
+}) => {
+  useImperativeHandle(ref, () => ({ expand: jest.fn(), close: jest.fn() }));
+  return <Text>{label}</Text>;
+};
+
 const fallbackExpand = jest.fn();
 
 // Module scope: the compiler outlines the `useImperativeHandle` factory there,
@@ -170,3 +207,71 @@ describe('BottomSheetHost SheetWrapper', () => {
     expect(fallbackExpand).toHaveBeenCalledTimes(1);
   });
 });
+
+describe('registered ref identity', () => {
+  beforeEach(() => {
+    seenSheetRefs.length = 0;
+  });
+
+  // The coordinator queues its ref calls on requestAnimationFrame, which RN's
+  // jest setup polyfills with a timeout. A frame still pending when the file
+  // ends runs against a torn-down environment and fails the whole run.
+  const flushFrame = () =>
+    act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+
+  it('hands the wrapper the registered ref when an id is re-opened in one tick', async () => {
+    const screen = renderHost(RecordingWrapper);
+
+    act(() => {
+      managerHolder.api.open(<BodyAdapter label="first" />, { id: 'x' });
+      store().markOpen('x');
+    });
+
+    expect(screen.getByText('first')).toBeTruthy();
+    expect(lastSeenSheetRef()).toBe(getSheetRef('x'));
+
+    // The item keys on the id, so it never unmounts across this pair and its
+    // cached read of the registry stands.
+    act(() => {
+      managerHolder.api.destroyAll();
+      managerHolder.api.open(<BodyAdapter label="second" />, { id: 'x' });
+    });
+
+    expect(screen.getByText('second')).toBeTruthy();
+    expect(lastSeenSheetRef()).toBe(getSheetRef('x'));
+
+    await flushFrame();
+  });
+
+  it('leaves a mounted persistent sheet its own ref when the manager opens that id', async () => {
+    render(
+      <SafeAreaProvider initialMetrics={initialMetrics}>
+        <BottomSheetManagerProvider id="g1">
+          <ManagerProbe />
+          <BottomSheetPersistent id="persistent-notepad">
+            <Text>notepad</Text>
+          </BottomSheetPersistent>
+          <BottomSheetHost />
+        </BottomSheetManagerProvider>
+      </SafeAreaProvider>
+    );
+
+    const persistentRef = getSheetRef('persistent-notepad');
+    expect(persistentRef).toBeDefined();
+
+    act(() => {
+      managerHolder.api.open(<BodyAdapter label="inline" />, {
+        id: 'persistent-notepad',
+      });
+      // The persistent sheet's own ref carries no handle here, so leaving it
+      // 'opening' would keep the coordinator retrying past teardown.
+      store().markOpen('persistent-notepad');
+    });
+
+    expect(getSheetRef('persistent-notepad')).toBe(persistentRef);
+
+    await flushFrame();
+  });
+});
diff --git a/src/useBottomSheetManager.tsx b/src/useBottomSheetManager.tsx
index e44504a..a5019fc 100644
--- a/src/useBottomSheetManager.tsx
+++ b/src/useBottomSheetManager.tsx
@@ -6,7 +6,7 @@ import type { CascadeOptions, CloseAllResult, CloseResult } from './store';
 import { useMaybeBottomSheetManagerContext } from './BottomSheetManager.context';
 import type { SheetAdapterRef } from './adapter.types';
 import { closeAllAnimated, requestClose } from './bottomSheetCoordinator';
-import { setSheetRef } from './refsMap';
+import { getSheetRef, setSheetRef } from './refsMap';
 
 export const useBottomSheetManager = () => {
   const bottomSheetManagerContext = useMaybeBottomSheetManagerContext();
@@ -44,7 +44,11 @@ export const useBottomSheetManager = () => {
       options.groupId || bottomSheetManagerContext?.groupId || 'default';
 
     const id = options.id || Math.random().toString(36);
-    const ref = React.createRef<SheetAdapterRef>();
+    // One registered id must map to one ref object: QueueItem's render-time
+    // read is cached for the item's life, and a persistent sheet registers its
+    // own ref on mount.
+    const existing = getSheetRef(id);
+    const ref = existing ?? React.createRef<SheetAdapterRef>();
 
     const contentWithRef = React.cloneElement(content, {
       ref,

From 0303e004305531f84cc2b15e313833823569b976 Mon Sep 17 00:00:00 2001
From: VadymBezpalko <vadym@gigaverse.com>
Date: Tue, 8 Sep 2026 21:12:27 +0200
Subject: [PATCH 07/13] fix(manager): register the ref before the store write
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

QueueItem reads refsMap during its first render, and that render is
scheduled by the store write in open(). Registering after the write left
the read correct only because React defers a concurrent-root update — an
await or a flushSync between the two calls would have broken it silently,
and the compiler caches the read on the item's id, so a first render that
misses the entry misses it for the item's whole life. Registering first
makes the ordering structural instead of a property of the renderer.

A rejected open now reclaims only the entry it created. Deleting
unconditionally would strip the ref of a live sheet whose id was re-opened
and rejected as already-active, and permanently strip a persistent sheet's
mount-registered ref on a group-busy rejection, since nothing re-registers
it — the coordinator would then burn its retry frames on a ref with no
handle and force-close the sheet.

The code comment claiming the opposite order, and the two CLAUDE.md
statements of the same invariant, are corrected to match.
---
 CLAUDE.md                     |  6 +++---
 src/QueueItem.tsx             |  8 +++++---
 src/__tests__/hooks.test.tsx  |  9 +++++++--
 src/__tests__/host.test.tsx   | 17 +++++++++++++++++
 src/useBottomSheetManager.tsx | 20 +++++++++++++-------
 5 files changed, 45 insertions(+), 15 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 6422fba..66f0fe6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -145,7 +145,7 @@ Four maps that outlive React, which is why `resetBottomSheetRegistries()` exists
 
 | Registry | Holds | Non-obvious part |
 |---|---|---|
-| `refsMap` | adapter refs | Refs are not serializable, so they cannot live in the store. Registered **only after** the store accepts the open, or a rejected open leaks an entry nothing can reclaim. Cleaned up by `QueueItem`'s unmount. |
+| `refsMap` | adapter refs | Refs are not serializable, so they cannot live in the store. Registered **before** the store write, because that write is what schedules the `QueueItem` render which reads the map. A rejected open reclaims only the entry it created — an orphan is unreclaimable, and deleting a pre-existing one strips a live sheet. Cleaned up by `QueueItem`'s unmount. |
 | `animatedRegistry` | `SharedValue<number>` per sheet | Created **eagerly** in `open()` / `mount()` so the backdrop always finds one. `resetAnimatedIndex` rewinds to `-1` on open, so a re-opened persistent sheet does not carry last cycle's value. `getAnimatedIndex` is a pure read and never creates. |
 | `onBeforeCloseRegistry` | close interceptors | Found from outside React by `requestClose` / `handleDismiss`. Its presence also flips `preventDismiss` on the store record. |
 | `portalSessionRegistry` | monotonic counter per id | Feeds the `Portal`/`PortalHost` name. **Persists across sheet deletion on purpose** — reusing a name after a replace hits a react-native-teleport connection bug. |
@@ -209,8 +209,8 @@ whole stack above arbitrary app chrome — without it any host view with a modes
 `BottomSheetHost` takes `SheetWrapper?: ComponentType<SheetWrapperProps>`;
 `QueueItem` renders it around an inline sheet's `content`, inside
 `BottomSheetContext`, with `getSheetRef(id)` as `sheetRef`. The render-time
-registry read is sound because `open()` writes the store and registers the ref
-in the same synchronous call, and the store write only *schedules* the render
+registry read is sound because `open()` registers the ref and then writes the
+store in one synchronous call, and the store write only *schedules* the render
 that mounts the item — the item's first render already sees the final entry,
 which it must, because the compiler caches the read on `id` and never re-runs
 it. An inline id is minted per open and the item's unmount cleanup removes it,
diff --git a/src/QueueItem.tsx b/src/QueueItem.tsx
index 1872682..f0cacd3 100644
--- a/src/QueueItem.tsx
+++ b/src/QueueItem.tsx
@@ -51,9 +51,11 @@ export const QueueItem = memo(function QueueItem({
 
   const animatedIndex = getAnimatedIndex(id);
 
-  // Safe to read during render: `open()` registers the ref before the store
-  // write that schedules this render, and the entry outlives the item. A
-  // persistent id can be re-registered under a mounted item, hence the guard.
+  // `open()` registers the ref, then writes the store; React only schedules the
+  // render that write causes, so this first — and, with the compiler's
+  // `[id, usePortal]` cache, only — read sees the entry. Nothing async or
+  // render-flushing may go between those two calls. Guarded on `usePortal`
+  // because a persistent id can be re-registered under a still-mounted item.
   const sheetRef = usePortal ? undefined : getSheetRef(id);
 
   const inlineContent =
diff --git a/src/__tests__/hooks.test.tsx b/src/__tests__/hooks.test.tsx
index 1682a86..c5eee67 100644
--- a/src/__tests__/hooks.test.tsx
+++ b/src/__tests__/hooks.test.tsx
@@ -43,16 +43,21 @@ describe('useBottomSheetManager', () => {
       store().markOpen('a');
     });
 
+    const registered = getSheetRef('a');
+
     let second: string | null = 'unset';
     act(() => {
       second = result.current.open(<Sheet />, { id: 'a' });
     });
 
     expect(second).toBeNull();
+    // The live sheet keeps the ref the coordinator drives: a rejected open
+    // reclaims only an entry it registered itself.
+    expect(getSheetRef('a')).toBe(registered);
   });
 
-  // The ref map is only cleaned up by QueueItem's unmount, which never happens
-  // for a rejected open — so registering early leaked an unreclaimable entry.
+  // Inline IDs are random and QueueItem's unmount is the map's only other
+  // cleanup, so an entry a rejected open leaves behind is unreclaimable.
   it('does not leak a ref when the open is declined', () => {
     const { result } = renderHook(() => useBottomSheetManager(), { wrapper });
 
diff --git a/src/__tests__/host.test.tsx b/src/__tests__/host.test.tsx
index ca40d84..7072d7c 100644
--- a/src/__tests__/host.test.tsx
+++ b/src/__tests__/host.test.tsx
@@ -221,6 +221,23 @@ describe('registered ref identity', () => {
       await new Promise((resolve) => setTimeout(resolve, 0));
     });
 
+  it('hands the wrapper the registered ref on its first render', async () => {
+    const screen = renderHost(RecordingWrapper);
+
+    act(() => {
+      managerHolder.api.open(<BodyAdapter label="first" />, { id: 'x' });
+      store().markOpen('x');
+    });
+
+    expect(screen.getByText('first')).toBeTruthy();
+    expect(getSheetRef('x')).toBeDefined();
+    // The compiler caches the read on the item's id, so a first render that
+    // misses the entry misses it for the item's whole life.
+    expect(seenSheetRefs[0]).toBe(getSheetRef('x'));
+
+    await flushFrame();
+  });
+
   it('hands the wrapper the registered ref when an id is re-opened in one tick', async () => {
     const screen = renderHost(RecordingWrapper);
 
diff --git a/src/useBottomSheetManager.tsx b/src/useBottomSheetManager.tsx
index a5019fc..e44fa42 100644
--- a/src/useBottomSheetManager.tsx
+++ b/src/useBottomSheetManager.tsx
@@ -6,7 +6,7 @@ import type { CascadeOptions, CloseAllResult, CloseResult } from './store';
 import { useMaybeBottomSheetManagerContext } from './BottomSheetManager.context';
 import type { SheetAdapterRef } from './adapter.types';
 import { closeAllAnimated, requestClose } from './bottomSheetCoordinator';
-import { getSheetRef, setSheetRef } from './refsMap';
+import { cleanupSheetRef, getSheetRef, setSheetRef } from './refsMap';
 
 export const useBottomSheetManager = () => {
   const bottomSheetManagerContext = useMaybeBottomSheetManagerContext();
@@ -54,6 +54,10 @@ export const useBottomSheetManager = () => {
       ref,
     } as { ref: typeof ref });
 
+    // QueueItem reads this map during its first render, and the store write
+    // below is what schedules that render — so register before writing.
+    setSheetRef(id, ref);
+
     const result = storeOpen(
       {
         kind: 'inline',
@@ -66,16 +70,18 @@ export const useBottomSheetManager = () => {
       options.mode
     );
 
-    // Registered only after the store accepts the sheet. The ref map is
-    // module-global and is only ever cleaned up by QueueItem's unmount — so
-    // registering before a rejected open would leak an entry that nothing can
-    // reclaim, once per rejected call, since inline IDs are random.
+    // A rejected open reclaims only the entry it created: inline IDs are
+    // random and nothing but QueueItem's unmount cleans the map, so an orphan
+    // leaks per rejected call — but deleting a ref registered before this call
+    // strips a live explicit id or a persistent sheet of the one the
+    // coordinator drives.
     if (!result.opened) {
+      if (!existing) {
+        cleanupSheetRef(id);
+      }
       return null;
     }
 
-    setSheetRef(id, ref);
-
     applyDeprecatedBackdrop(id, options.backdrop, setBackdrop);
 
     return id;

From 249190e13965391b98a948b83e4021513f8ee466 Mon Sep 17 00:00:00 2001
From: VadymBezpalko <vadym@gigaverse.com>
Date: Tue, 8 Sep 2026 21:19:32 +0200
Subject: [PATCH 08/13] fix(host): always wrap an inline sheet, even without a
 registered ref

`SheetWrapperProps.sheetRef` was typed non-optional, but the wrapper was
rendered only when a ref happened to be registered for the id. The React
Compiler pins the registry read on `[id, usePortal]`, so a miss on the item's
first render is permanent: the sheet renders unwrapped for its whole life and a
throw in its body escapes the host, taking the group down instead of hitting
the per-sheet boundary. The type promised a box that a registry miss silently
removed.

Render the wrapper unconditionally in the inline branch and tell the truth in
the type: `sheetRef: SheetRef | undefined`. The boundary is then always there;
what a miss costs is only that the coordinator cannot drive a fallback adapter,
which is what the JSDoc and the types docs now say. `useAdapterRef`'s parameter
widens to match, since a wrapper following the documented contract forwards
`sheetRef` straight into it. No dev warning: with the wrapper unconditional the
miss has no observable effect left to warn about.
---
 docs/docs/api/types.md      |  4 +++-
 src/BottomSheetHost.tsx     | 10 ++++++++--
 src/QueueItem.tsx           | 15 +++++++--------
 src/__tests__/host.test.tsx | 21 +++++++++++++++++++++
 src/useAdapterRef.ts        |  4 ++--
 5 files changed, 41 insertions(+), 13 deletions(-)

diff --git a/docs/docs/api/types.md b/docs/docs/api/types.md
index 05e104c..147069f 100644
--- a/docs/docs/api/types.md
+++ b/docs/docs/api/types.md
@@ -200,13 +200,15 @@ type SheetRef = RefObject<SheetAdapterRef | null>;
 ```ts
 interface SheetWrapperProps {
   id: string; // same as useBottomSheetContext().id
-  sheetRef: SheetRef; // the ref the coordinator drives; bind a fallback adapter to it
+  sheetRef: SheetRef | undefined; // the ref the coordinator drives; bind a fallback adapter to it
   children: ReactNode;
 }
 ```
 
 Props of the component passed to `BottomSheetHost`'s `SheetWrapper`.
 
+`sheetRef` is `undefined` when no ref is registered for the id — the wrapper still renders, but the coordinator cannot drive a fallback adapter, so a programmatic close removes the sheet with no exit animation.
+
 ---
 
 ## Configuration Types
diff --git a/src/BottomSheetHost.tsx b/src/BottomSheetHost.tsx
index 395a66a..3076f8d 100644
--- a/src/BottomSheetHost.tsx
+++ b/src/BottomSheetHost.tsx
@@ -80,8 +80,14 @@ function reconcilePendingTransitions(groupId: string): () => void {
 
 export interface SheetWrapperProps {
   id: string;
-  /** The ref the coordinator drives; a fallback adapter binds to it so expand/close keep reaching the sheet. */
-  sheetRef: SheetRef;
+  /**
+   * The ref the coordinator drives; a fallback adapter binds to it so
+   * expand/close keep reaching the sheet. `undefined` when no ref is registered
+   * for the id — the wrapper still renders, but the coordinator cannot drive a
+   * fallback adapter, so a programmatic close removes the sheet with no exit
+   * animation.
+   */
+  sheetRef: SheetRef | undefined;
   children: ReactNode;
 }
 
diff --git a/src/QueueItem.tsx b/src/QueueItem.tsx
index f0cacd3..3c72e49 100644
--- a/src/QueueItem.tsx
+++ b/src/QueueItem.tsx
@@ -58,14 +58,13 @@ export const QueueItem = memo(function QueueItem({
   // because a persistent id can be re-registered under a still-mounted item.
   const sheetRef = usePortal ? undefined : getSheetRef(id);
 
-  const inlineContent =
-    SheetWrapper && sheetRef ? (
-      <SheetWrapper id={id} sheetRef={sheetRef}>
-        {content}
-      </SheetWrapper>
-    ) : (
-      content
-    );
+  const inlineContent = SheetWrapper ? (
+    <SheetWrapper id={id} sheetRef={sheetRef}>
+      {content}
+    </SheetWrapper>
+  ) : (
+    content
+  );
 
   useEffect(() => {
     return () => {
diff --git a/src/__tests__/host.test.tsx b/src/__tests__/host.test.tsx
index 7072d7c..66977f4 100644
--- a/src/__tests__/host.test.tsx
+++ b/src/__tests__/host.test.tsx
@@ -137,6 +137,27 @@ describe('BottomSheetHost SheetWrapper', () => {
     });
   });
 
+  it('wraps an inline sheet with no registered ref, handing the wrapper undefined', () => {
+    const seen: Array<{ id: string; sheetRef: unknown }> = [];
+    const Wrapper = ({ id, sheetRef, children }: SheetWrapperProps) => {
+      seen.push({ id, sheetRef });
+      return <>{children}</>;
+    };
+    const screen = renderHost(Wrapper);
+
+    act(() =>
+      store().open({
+        kind: 'inline',
+        id: 'a',
+        groupId: 'g1',
+        content: <Text>body</Text>,
+      })
+    );
+
+    expect(seen).toStrictEqual([{ id: 'a', sheetRef: undefined }]);
+    expect(screen.getByText('body')).toBeTruthy();
+  });
+
   it('does not wrap portal sheets', () => {
     const Wrapper = jest.fn(({ children }: SheetWrapperProps) => (
       <>{children}</>
diff --git a/src/useAdapterRef.ts b/src/useAdapterRef.ts
index 62dde2d..d6c4b86 100644
--- a/src/useAdapterRef.ts
+++ b/src/useAdapterRef.ts
@@ -23,8 +23,8 @@ import { useBottomSheetStore } from './store';
  * ```
  */
 export function useAdapterRef(
-  forwardedRef: ForwardedRef<SheetAdapterRef>
-): SheetRef | ForwardedRef<SheetAdapterRef> {
+  forwardedRef: ForwardedRef<SheetAdapterRef> | undefined
+): SheetRef | ForwardedRef<SheetAdapterRef> | undefined {
   const contextRef = useMaybeBottomSheetRef();
   const ref = contextRef ?? forwardedRef;
   const id = useMaybeBottomSheetContext()?.id;

From 6a45a6f53e42857c30f565d825b2ed53aa67d913 Mon Sep 17 00:00:00 2001
From: VadymBezpalko <vadym@gigaverse.com>
Date: Tue, 8 Sep 2026 21:27:45 +0200
Subject: [PATCH 09/13] fix(adapter): end a sheet whose adapter mounts while it
 is closing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The coordinator drives status changes only, so once driveSheetRef has landed
close() on the adapter that was mounted at the time, nothing ever calls the
give-up path again. An adapter that mounts afterwards under `closing` — an
error-boundary fallback replacing a body that threw mid-dismissal, or a
BottomSheetPortal remounted after being cleared mid-close — has nobody to drive
it, and the sheet stays `closing` forever: closeAll skips it, requestClose
answers not-closable, no back handler is registered, and its id answers
already-active for the rest of the session.

A fresh adapter cannot animate a close it never opened, so the catch-up ends the
sheet in the store instead, exactly as driveSheetRef's give-up path does. The
cost is that a mid-close remount finishes without re-animating, which is the
honest outcome for an adapter that has no open state to close from.

`hidden` is deliberately left out: a switch-parked sheet lives there on the
stack and is restored by detachFromGroup, and mount() parks every persistent
sheet there with its adapter rendered, so finishClosing would delete a live
sheet on every persistent mount.

Also corrects the pre-existing claim that a stuck `closing` sheet wedges later
opens in the group — group-busy guards `opening` only.
---
 CLAUDE.md                         | 27 ++++++----
 docs/docs/api/components.md       |  4 +-
 docs/docs/custom-adapters.md      |  2 +-
 src/__tests__/adapterRef.test.tsx | 40 +++++++++++++-
 src/__tests__/host.test.tsx       | 86 +++++++++++++++++++++++++------
 src/useAdapterRef.ts              | 18 ++++---
 6 files changed, 140 insertions(+), 37 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 66f0fe6..7328bcb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -123,16 +123,23 @@ is what makes a user gesture honour the interceptor — do not simplify it back.
 `driveSheetRef` retries a ref call across up to 10 `requestAnimationFrame`s,
 re-checking status each time. The store can reach a terminal status before the
 adapter mounts (a portal sheet must teleport first); a single attempt silently
-no-ops and wedges the sheet — and for `'closing'`, wedges every later open in the
-group on the `group-busy` guard.
-
-`useAdapterRef` catches up once on mount when the sheet is already `open`
-(`ref.current.expand()`): the coordinator drives status *changes*, so an adapter
-that replaces another under an open status has nobody else to open it.
-`opening` is left to `driveSheetRef`; `closing`/`hidden` are not caught up — an
-adapter that never opened cannot animate a close; the honest action would be
-`finishClosing(id)` as in `driveSheetRef`'s give-up path, deliberately not done
-yet.
+no-ops and wedges the sheet. A sheet stuck at `'closing'` does **not** wedge
+later opens in the group — `group-busy` is `'opening'`-only. It costs
+`closeAllAnimated` skipping it, `requestClose` answering `not-closable`, no back
+handler at all (`useIsTopmostAndOpen` needs `'open'` *and* top) and its own id
+answering `already-active` for the rest of the session.
+
+`useAdapterRef` catches up once on mount off the sheet's live status: `'open'` →
+`ref.current.expand()`, `'closing'` → `finishClosing(id)`. The coordinator
+drives status *changes*, so an adapter that replaces another under a live status
+has nobody else to drive it. `'opening'` is left to `driveSheetRef`. A fresh
+adapter cannot animate a close it never opened, so `'closing'` is ended in the
+store as in `driveSheetRef`'s give-up path — a mid-close remount ends the sheet
+without re-animating it out. `'hidden'` is deliberately excluded: a
+`switch`-parked sheet sits there *on* the stack and is restored by
+`detachFromGroup`, and `mount()` parks every persistent sheet there with its
+adapter rendered, so `finishClosing` would delete a live sheet on every
+persistent mount.
 
 Also exported publicly for adapter authors: `requestClose(id)` and
 `closeAllAnimated(groupId, opts)`.
diff --git a/docs/docs/api/components.md b/docs/docs/api/components.md
index eabe8af..7056e48 100644
--- a/docs/docs/api/components.md
+++ b/docs/docs/api/components.md
@@ -51,7 +51,7 @@ Place `BottomSheetHost` **outside** of `BottomSheetScaleView` to prevent sheets
 |------|------|-------------|
 | `SheetWrapper` | `React.ComponentType<SheetWrapperProps>` | Rendered around every **inline** sheet's content, inside that sheet's context. Receives `{ id, sheetRef, children }`. Portal and persistent sheets render where they are declared and are not wrapped. Define it at module scope. |
 
-Use it to put an error boundary around each sheet, so one sheet failing never takes the host down. The fallback renders an adapter bound to `sheetRef`, and the manager keeps driving the sheet — `useBottomSheetContext().close()` still closes it:
+Use it to put an error boundary around each sheet, so one sheet failing never takes the host down. The fallback **must** render an adapter bound to `sheetRef`, so the manager keeps driving the sheet — `useBottomSheetContext().close()` still closes it. A fallback without an adapter leaves a sheet that crashes mid-close stuck at `closing`: `closeAll` skips it, `close()` answers `not-closable`, the Android back button is dead for the group, and its id is unusable until `destroyAll()`.
 
 ```tsx
 class SheetErrorBoundary extends React.Component<
@@ -78,7 +78,7 @@ class SheetErrorBoundary extends React.Component<
 <BottomSheetHost SheetWrapper={SheetErrorBoundary} />;
 ```
 
-An adapter that mounts while its sheet is already `open` is expanded on mount, so the fallback appears in place without extra wiring.
+An adapter that mounts while its sheet is already `open` is expanded on mount, so the fallback appears in place without extra wiring. If it mounts while the sheet is `closing`, the sheet is ended instead — a crash mid-dismissal finishes the close rather than popping the error card back up.
 
 ---
 
diff --git a/docs/docs/custom-adapters.md b/docs/docs/custom-adapters.md
index 963e0b7..9e08bb8 100644
--- a/docs/docs/custom-adapters.md
+++ b/docs/docs/custom-adapters.md
@@ -292,7 +292,7 @@ const ref = useAdapterRef(forwardedRef);
 useImperativeHandle(ref, () => ({ expand: ..., close: ... }));
 ```
 
-An adapter that mounts while its sheet is already `open` is expanded once on mount. The coordinator only reacts to status changes, so this is what lets an adapter rendered *in place of* another — an error-boundary fallback under `BottomSheetHost`'s `SheetWrapper` — come up open. Your adapter needs nothing extra for it beyond `useAdapterRef` + `useImperativeHandle`.
+An adapter that mounts while its sheet is already `open` is expanded once on mount, and one that mounts while the sheet is `closing` ends that sheet instead (it never opened, so it cannot animate the close out). The coordinator only reacts to status changes, so this is what lets an adapter rendered *in place of* another — an error-boundary fallback under `BottomSheetHost`'s `SheetWrapper` — come up open, or finish a dismissal it interrupted. Your adapter needs nothing extra for it beyond `useAdapterRef` + `useImperativeHandle`.
 
 ### Prop-Controlled vs Ref-Controlled Libraries
 
diff --git a/src/__tests__/adapterRef.test.tsx b/src/__tests__/adapterRef.test.tsx
index fb1973e..ebd5b83 100644
--- a/src/__tests__/adapterRef.test.tsx
+++ b/src/__tests__/adapterRef.test.tsx
@@ -2,7 +2,15 @@ import { renderHook } from '@testing-library/react-native';
 
 import { BottomSheetRefContext } from '../BottomSheetRef.context';
 import { useAdapterRef } from '../useAdapterRef';
-import { inSheet, makeRef, portal, setupSheetTest, store } from './testUtils';
+import {
+  inSheet,
+  makeRef,
+  portal,
+  setupSheetTest,
+  stackOf,
+  statusOf,
+  store,
+} from './testUtils';
 
 setupSheetTest();
 
@@ -39,6 +47,36 @@ describe('useAdapterRef', () => {
     expect(ref.current.expand).not.toHaveBeenCalled();
   });
 
+  it('ends a sheet whose adapter mounts while it is closing', () => {
+    store().open(portal('a'));
+    store().markOpen('a');
+    store().startClosing('a');
+    const ref = makeRef();
+
+    renderHook(() => useAdapterRef(ref), { wrapper: inSheet('a') });
+
+    expect(ref.current.close).not.toHaveBeenCalled();
+    expect(store().sheetsById.a).toBeUndefined();
+    expect(stackOf('g1')).toEqual([]);
+  });
+
+  it('leaves a sheet parked as hidden by switch for the store to restore', () => {
+    store().open(portal('a'));
+    store().markOpen('a');
+    store().open(portal('b'), 'switch');
+    store().markOpen('b');
+    expect(statusOf('a')).toBe('hidden');
+    const ref = makeRef();
+
+    renderHook(() => useAdapterRef(ref), { wrapper: inSheet('a') });
+
+    expect(statusOf('a')).toBe('hidden');
+    expect(stackOf('g1')).toEqual(['a', 'b']);
+
+    store().startClosing('b');
+    expect(statusOf('a')).toBe('opening');
+  });
+
   it('does nothing for a hidden persistent sheet or outside a sheet context', () => {
     store().mount({ id: 'p', groupId: 'g1' });
     const hiddenRef = makeRef();
diff --git a/src/__tests__/host.test.tsx b/src/__tests__/host.test.tsx
index 66977f4..c6356e6 100644
--- a/src/__tests__/host.test.tsx
+++ b/src/__tests__/host.test.tsx
@@ -75,7 +75,16 @@ const BodyAdapter = ({
   return <Text>{label}</Text>;
 };
 
+// The coordinator queues its ref calls on requestAnimationFrame, which RN's
+// jest setup polyfills with a timeout. A frame still pending when the file ends
+// runs against a torn-down environment and fails the whole run.
+const flushFrame = () =>
+  act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+
 const fallbackExpand = jest.fn();
+const fallbackClose = jest.fn();
 
 // Module scope: the compiler outlines the `useImperativeHandle` factory there,
 // so a spy declared inside a test would be out of its reach.
@@ -87,11 +96,19 @@ const FallbackAdapter = ({
   const ref = useAdapterRef(sheetRef);
   useImperativeHandle(ref, () => ({
     expand: fallbackExpand,
-    close: jest.fn(),
+    close: fallbackClose,
   }));
   return <Text>fallback</Text>;
 };
 
+const Crashable = () => {
+  const { params } = useBottomSheetContext();
+  if ((params as { crash?: boolean } | undefined)?.crash) {
+    throw new Error('boom');
+  }
+  return <Text>alive</Text>;
+};
+
 class FallbackBoundary extends Component<
   SheetWrapperProps,
   { failed: boolean }
@@ -200,14 +217,6 @@ describe('BottomSheetHost SheetWrapper', () => {
     jest.spyOn(console, 'error').mockImplementation(() => {});
     fallbackExpand.mockClear();
 
-    const Crashable = () => {
-      const { params } = useBottomSheetContext();
-      if ((params as { crash?: boolean } | undefined)?.crash) {
-        throw new Error('boom');
-      }
-      return <Text>alive</Text>;
-    };
-
     const screen = renderHost(FallbackBoundary);
     act(() => {
       store().open({
@@ -227,6 +236,57 @@ describe('BottomSheetHost SheetWrapper', () => {
     expect(getSheetRef('a')?.current?.expand).toBe(fallbackExpand);
     expect(fallbackExpand).toHaveBeenCalledTimes(1);
   });
+
+  it('ends a sheet whose fallback adapter mounts while it is closing', async () => {
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+    fallbackExpand.mockClear();
+    fallbackClose.mockClear();
+
+    const bodyClose = jest.fn();
+    const bodyRef = createRef<SheetAdapterRef>() as {
+      current: SheetAdapterRef | null;
+    };
+
+    renderHost(FallbackBoundary);
+    act(() => {
+      store().open({
+        kind: 'inline',
+        id: 'a',
+        groupId: 'g1',
+        content: <Crashable />,
+      });
+      setSheetRef('a', bodyRef);
+      bodyRef.current = { expand: jest.fn(), close: bodyClose };
+      store().markOpen('a');
+    });
+
+    await act(async () => {
+      store().startClosing('a');
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+    expect(bodyClose).toHaveBeenCalledTimes(1);
+    expect(store().sheetsById.a?.status).toBe('closing');
+
+    act(() => store().updateParams('a', { crash: true }));
+
+    expect(store().sheetsById.a).toBeUndefined();
+    expect(store().stackOrderByGroup.g1).toBeUndefined();
+    expect(fallbackClose).not.toHaveBeenCalled();
+    expect(fallbackExpand).not.toHaveBeenCalled();
+    expect(
+      store().open({
+        kind: 'inline',
+        id: 'a',
+        groupId: 'g1',
+        content: <Text>again</Text>,
+      })
+    ).toEqual({ opened: true, id: 'a' });
+
+    // That re-open has no adapter, so leaving it would keep the coordinator
+    // retrying past teardown.
+    act(() => store().clearGroup('g1'));
+    await flushFrame();
+  });
 });
 
 describe('registered ref identity', () => {
@@ -234,14 +294,6 @@ describe('registered ref identity', () => {
     seenSheetRefs.length = 0;
   });
 
-  // The coordinator queues its ref calls on requestAnimationFrame, which RN's
-  // jest setup polyfills with a timeout. A frame still pending when the file
-  // ends runs against a torn-down environment and fails the whole run.
-  const flushFrame = () =>
-    act(async () => {
-      await new Promise((resolve) => setTimeout(resolve, 0));
-    });
-
   it('hands the wrapper the registered ref on its first render', async () => {
     const screen = renderHost(RecordingWrapper);
 
diff --git a/src/useAdapterRef.ts b/src/useAdapterRef.ts
index d6c4b86..14682c1 100644
--- a/src/useAdapterRef.ts
+++ b/src/useAdapterRef.ts
@@ -29,17 +29,23 @@ export function useAdapterRef(
   const ref = contextRef ?? forwardedRef;
   const id = useMaybeBottomSheetContext()?.id;
 
-  // The coordinator drives status *changes* only, so an adapter mounted under
-  // an already-open sheet (a wrapper's fallback) has nobody else to open it.
-  // Passive effect: the imperative handle is attached by then.
+  // The coordinator drives status *changes* only, so an adapter that mounts
+  // under a live status has nobody to drive it. Under `open` it opens itself;
+  // under `closing` a fresh adapter cannot animate a close it never opened, so
+  // the sheet is ended in the store instead (same as `driveSheetRef`'s give-up
+  // path) — a mid-close remount ends the sheet without re-animating. `hidden`
+  // is deliberately left alone: nothing is stuck there and the store owns the
+  // restore. Passive effect: the imperative handle is attached by then.
   useEffect(() => {
     if (!id || typeof ref !== 'object') {
       return;
     }
-    if (useBottomSheetStore.getState().sheetsById[id]?.status !== 'open') {
-      return;
+    const status = useBottomSheetStore.getState().sheetsById[id]?.status;
+    if (status === 'open') {
+      ref?.current?.expand();
+    } else if (status === 'closing') {
+      useBottomSheetStore.getState().finishClosing(id);
     }
-    ref?.current?.expand();
   }, [id, ref]);
 
   return ref;

From e24fbc038d3032d008c725aa76c272e283030478 Mon Sep 17 00:00:00 2001
From: VadymBezpalko <vadym@gigaverse.com>
Date: Tue, 8 Sep 2026 21:37:03 +0200
Subject: [PATCH 10/13] feat(host): warn in dev when SheetWrapper changes
 between renders
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The wrapper is used as an element type, so a new prop value remounts every
inline sheet: the adapter replays its open animation and a stateful wrapper
(an error boundary) loses the state it just derived. "Define it at module
scope" was not enough guidance — a derived prop value breaks it while the
wrapper already is module scope (`flag ? Wrapper : undefined`, or swapping
two wrappers), and React Compiler outlines a capture-free inline arrow, so
the shape the JSDoc warned about is the one case that is already safe.

The hook compares the prop value instead of skipping the first effect run:
StrictMode replays effects with the same ref object, and a run-counting
flag would warn on a wrapper that never changed. Warns once per host, so a
Fast Refresh session that remounts the host can warn again.

JSDoc, the docs prop description and CLAUDE.md now state the requirement as
a stable prop value and name the cost. No API change.
---
 CLAUDE.md                   |  8 +++--
 docs/docs/api/components.md |  4 ++-
 src/BottomSheetHost.tsx     | 46 ++++++++++++++++++++++++--
 src/__tests__/host.test.tsx | 64 +++++++++++++++++++++++++++++++++++++
 4 files changed, 117 insertions(+), 5 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 7328bcb..6129f9e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -225,8 +225,12 @@ so the value cannot change while the item is mounted; the read is guarded on
 `usePortal` because a persistent id *can* be re-registered under a
 still-mounted item. A caller-supplied inline id re-opened in the same tick as
 its removal hands the wrapper the previous ref; the coordinator reads the
-registry fresh, so the sheet still closes via the give-up path. The prop must be
-a module-scope component — `QueueItem` is `memo`.
+registry fresh, so the sheet still closes via the give-up path. The prop *value*
+must be stable for the life of the host: it is the element type, so a new value
+remounts every inline sheet (replayed open animation, a stateful wrapper's state
+gone). A derived value (`flag ? Wrapper : undefined`) breaks it even under the
+compiler, which outlines a capture-free inline arrow — hence a dev warning on
+change, not just a "module scope" line in the JSDoc.
 
 `BottomSheetBackdrop` is mounted from the sheet's first frame and faded purely by
 `animatedIndex`. Do not add a timer or delay gate: deferring the mount drops the
diff --git a/docs/docs/api/components.md b/docs/docs/api/components.md
index 7056e48..426259f 100644
--- a/docs/docs/api/components.md
+++ b/docs/docs/api/components.md
@@ -49,7 +49,9 @@ Place `BottomSheetHost` **outside** of `BottomSheetScaleView` to prevent sheets
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `SheetWrapper` | `React.ComponentType<SheetWrapperProps>` | Rendered around every **inline** sheet's content, inside that sheet's context. Receives `{ id, sheetRef, children }`. Portal and persistent sheets render where they are declared and are not wrapped. Define it at module scope. |
+| `SheetWrapper` | `React.ComponentType<SheetWrapperProps>` | Rendered around every **inline** sheet's content, inside that sheet's context. Receives `{ id, sheetRef, children }`. Portal and persistent sheets render where they are declared and are not wrapped. The prop **value** must stay stable for the life of the host — see below. |
+
+The wrapper is used as an element **type**, so a new prop value remounts every inline sheet: the adapter replays its open animation (its fresh shared value rewinds `animatedIndex`, so the backdrop blanks first) and a stateful wrapper loses its state — an error boundary forgets that it already failed. Pass a module-scope component; an inline arrow and a derived value (`flag ? SheetErrorBoundary : undefined`, or swapping one module-scope wrapper for another) both break it, the latter on the frame the flag resolves, typically while a sheet is open. Changing the value warns once per host in dev.
 
 Use it to put an error boundary around each sheet, so one sheet failing never takes the host down. The fallback **must** render an adapter bound to `sheetRef`, so the manager keeps driving the sheet — `useBottomSheetContext().close()` still closes it. A fallback without an adapter leaves a sheet that crashes mid-close stuck at `closing`: `closeAll` skips it, `close()` answers `not-closable`, the Android back button is dead for the group, and its id is unusable until `destroyAll()`.
 
diff --git a/src/BottomSheetHost.tsx b/src/BottomSheetHost.tsx
index 3076f8d..38c87d5 100644
--- a/src/BottomSheetHost.tsx
+++ b/src/BottomSheetHost.tsx
@@ -1,4 +1,4 @@
-import { useEffect, type ComponentType, type ReactNode } from 'react';
+import { useEffect, useRef, type ComponentType, type ReactNode } from 'react';
 
 import type { SheetRef } from './adapter.types';
 import { useBottomSheetStore, useClearGroup } from './store';
@@ -91,12 +91,52 @@ export interface SheetWrapperProps {
   children: ReactNode;
 }
 
+/**
+ * Warns once per host when the `SheetWrapper` prop value changes.
+ *
+ * The wrapper is used as an element type, so a new value remounts every inline
+ * sheet. Compares the value rather than skipping the first run: StrictMode
+ * replays effects with the same ref object, and a run-counting flag would warn
+ * on a wrapper that never changed.
+ */
+function useSheetWrapperIdentityWarning(
+  SheetWrapper?: ComponentType<SheetWrapperProps>
+) {
+  const seen = useRef({ last: SheetWrapper, warned: false });
+
+  useEffect(() => {
+    const state = seen.current;
+    if (state.last === SheetWrapper) {
+      return;
+    }
+    state.last = SheetWrapper;
+
+    if (__DEV__ && !state.warned) {
+      state.warned = true;
+      console.warn(
+        '[BottomSheet] `SheetWrapper` changed between renders, which remounts ' +
+          'every inline sheet: the adapter replays its open animation and a ' +
+          'stateful wrapper (an error boundary) loses its state. Keep the prop ' +
+          'value stable for the life of the host — a module-scope component, ' +
+          'not an inline arrow or a branch on a flag.'
+      );
+    }
+  }, [SheetWrapper]);
+}
+
 interface BottomSheetHostProps {
   /**
    * Wraps each inline sheet's content inside its context — the place for a
    * per-sheet error boundary whose fallback is an adapter bound to `sheetRef`.
    * Portal and persistent sheets render where they are declared and are not
-   * wrapped. Must be a module-scope component: `QueueItem` is memoized.
+   * wrapped.
+   *
+   * The prop *value* must stay stable for the life of the host: it is used as
+   * an element type, so a new value remounts every inline sheet — the adapter
+   * replays its open animation and a stateful wrapper loses its state. Pass a
+   * module-scope component, not an inline arrow and not a branch on a flag
+   * (`flag ? Wrapper : undefined` remounts on the frame the flag resolves).
+   * Changing it warns in dev.
    */
   SheetWrapper?: ComponentType<SheetWrapperProps>;
 }
@@ -106,6 +146,8 @@ export function BottomSheetHost({ SheetWrapper }: BottomSheetHostProps) {
   const clearGroup = useClearGroup();
   const { groupId } = useBottomSheetManagerContext();
 
+  useSheetWrapperIdentityWarning(SheetWrapper);
+
   useEffect(() => {
     const unsubscribe = initBottomSheetCoordinator(groupId);
     const cancelReconcile = reconcilePendingTransitions(groupId);
diff --git a/src/__tests__/host.test.tsx b/src/__tests__/host.test.tsx
index c6356e6..a7853bf 100644
--- a/src/__tests__/host.test.tsx
+++ b/src/__tests__/host.test.tsx
@@ -3,6 +3,7 @@ import {
   createRef,
   useEffect,
   useImperativeHandle,
+  useState,
   type ReactElement,
   type Ref,
 } from 'react';
@@ -365,3 +366,66 @@ describe('registered ref identity', () => {
     await flushFrame();
   });
 });
+
+const StableWrapper = ({ children }: SheetWrapperProps) => <>{children}</>;
+
+const TickWrapperBody = ({
+  children,
+}: SheetWrapperProps & { tick: number }) => <>{children}</>;
+
+let forceHostRender: (() => void) | undefined;
+
+const inProviders = (children: ReactElement) => (
+  <SafeAreaProvider initialMetrics={initialMetrics}>
+    <BottomSheetManagerProvider id="g1">{children}</BottomSheetManagerProvider>
+  </SafeAreaProvider>
+);
+
+// The closure captures `tick`, so the compiler cannot outline it to module
+// scope — the prop value really is new on every parent render.
+const UnstableWrapperHost = () => {
+  const [tick, setTick] = useState(0);
+  useEffect(() => {
+    forceHostRender = () => setTick((value) => value + 1);
+  }, []);
+  return inProviders(
+    <BottomSheetHost
+      SheetWrapper={(props: SheetWrapperProps) => (
+        <TickWrapperBody tick={tick} {...props} />
+      )}
+    />
+  );
+};
+
+const StableWrapperHost = () => {
+  const [, setTick] = useState(0);
+  useEffect(() => {
+    forceHostRender = () => setTick((value) => value + 1);
+  }, []);
+  return inProviders(<BottomSheetHost SheetWrapper={StableWrapper} />);
+};
+
+const identityWarnings = () =>
+  (console.warn as jest.Mock).mock.calls.filter(([message]) =>
+    /changed between renders/.test(String(message))
+  );
+
+describe('SheetWrapper identity warning', () => {
+  it('warns once when the prop value changes between renders', () => {
+    render(<UnstableWrapperHost />);
+
+    act(() => forceHostRender?.());
+    act(() => forceHostRender?.());
+
+    expect(identityWarnings()).toHaveLength(1);
+  });
+
+  it('stays quiet for a module-scope wrapper across the same re-renders', () => {
+    render(<StableWrapperHost />);
+
+    act(() => forceHostRender?.());
+    act(() => forceHostRender?.());
+
+    expect(identityWarnings()).toHaveLength(0);
+  });
+});

From f7fd81604bd0f97458d913c21b322fe941aaf804 Mon Sep 17 00:00:00 2001
From: VadymBezpalko <vadym@gigaverse.com>
Date: Tue, 8 Sep 2026 21:43:18 +0200
Subject: [PATCH 11/13] docs(example): drop the fallback's own scrim; note the
 animatedIndex rewind
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The error-boundary fallback painted rgba(0, 0, 0, 0.6) on its
contentContainerStyle, which stacks on the manager backdrop that is still
mounted behind it — the sheet it replaces dims twice. The colour was lifted
from the example's house style (ModalSheets and friends), so the style key is
renamed overlay -> content to stop it reading like a scrim. The same
0.6-over-0.5 double dim exists in those sibling example files on main; that is
left for a separate sweep rather than widened into this PR.

The docs note beside the fallback snippet is the other half: an adapter that
seeds its position from zero rewinds the sheet's shared animatedIndex on its
first render, so the manager backdrop visibly re-fades behind a fallback that
mounts under an open sheet, and the crashed adapter's backdrop cleanup hands the
group scrim back to a sheet that had opted out of it. Both are consequences an
app dev copying the snippet should know about; seeding CustomModalAdapter from
the sheet's status is a follow-up, since seeding it unconditionally wedges a
normal open.
---
 docs/docs/api/components.md                   | 2 ++
 docs/docs/custom-adapters.md                  | 2 ++
 example/src/components/SheetErrorBoundary.tsx | 5 ++---
 3 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/docs/docs/api/components.md b/docs/docs/api/components.md
index 426259f..8b943d4 100644
--- a/docs/docs/api/components.md
+++ b/docs/docs/api/components.md
@@ -82,6 +82,8 @@ class SheetErrorBoundary extends React.Component<
 
 An adapter that mounts while its sheet is already `open` is expanded on mount, so the fallback appears in place without extra wiring. If it mounts while the sheet is `closing`, the sheet is ended instead — a crash mid-dismissal finishes the close rather than popping the error card back up.
 
+Give the fallback no scrim of its own — the manager's backdrop is still mounted behind it, and a second dim stacks on the first. Expect one visual artefact instead: a fallback adapter that seeds its position from zero rewinds the sheet's shared `animatedIndex` to -1 on its first render, so under an open sheet the manager backdrop fades out and back in behind the fallback. Seed the adapter from the sheet's current status to avoid it. Note too that the crashed adapter's unmount re-enables the manager scrim through its backdrop cleanup, so a sheet that passed `backdrop={false}` gets the group backdrop back for its fallback.
+
 ---
 
 ## BottomSheetScaleView
diff --git a/docs/docs/custom-adapters.md b/docs/docs/custom-adapters.md
index 9e08bb8..1f53e0d 100644
--- a/docs/docs/custom-adapters.md
+++ b/docs/docs/custom-adapters.md
@@ -294,6 +294,8 @@ useImperativeHandle(ref, () => ({ expand: ..., close: ... }));
 
 An adapter that mounts while its sheet is already `open` is expanded once on mount, and one that mounts while the sheet is `closing` ends that sheet instead (it never opened, so it cannot animate the close out). The coordinator only reacts to status changes, so this is what lets an adapter rendered *in place of* another — an error-boundary fallback under `BottomSheetHost`'s `SheetWrapper` — come up open, or finish a dismissal it interrupted. Your adapter needs nothing extra for it beyond `useAdapterRef` + `useImperativeHandle`.
 
+An adapter that seeds its position from zero rewinds the sheet's shared `animatedIndex` on that mount, which the backdrop follows — see [`BottomSheetHost`](/api/components#bottomsheethost) for what a consumer sees and how to avoid it.
+
 ### Prop-Controlled vs Ref-Controlled Libraries
 
 **Ref-controlled** (e.g., TrueSheet with `present()`/`dismiss()`):
diff --git a/example/src/components/SheetErrorBoundary.tsx b/example/src/components/SheetErrorBoundary.tsx
index 83016d8..deb05f1 100644
--- a/example/src/components/SheetErrorBoundary.tsx
+++ b/example/src/components/SheetErrorBoundary.tsx
@@ -21,7 +21,7 @@ function FallbackSheet({
   const { close } = useBottomSheetContext();
 
   return (
-    <CustomModalAdapter ref={sheetRef} contentContainerStyle={styles.overlay}>
+    <CustomModalAdapter ref={sheetRef} contentContainerStyle={styles.content}>
       <View style={styles.card}>
         <Badge label="Fallback" color={colors.error} />
         <Text style={sharedStyles.h1}>This sheet could not be shown</Text>
@@ -64,8 +64,7 @@ export class SheetErrorBoundary extends Component<
 }
 
 const styles = StyleSheet.create({
-  overlay: {
-    backgroundColor: 'rgba(0, 0, 0, 0.6)',
+  content: {
     paddingHorizontal: 24,
   },
   card: {

From 26b8305546df4379168a53240d829bc2ad77013b Mon Sep 17 00:00:00 2001
From: VadymBezpalko <vadym@gigaverse.com>
Date: Tue, 8 Sep 2026 21:53:26 +0200
Subject: [PATCH 12/13] docs: reconcile SheetWrapper prose with the
 review-round commits

CLAUDE.md still described the same-tick re-open of an explicit inline id as
handing the wrapper a stale ref that the coordinator's give-up path closes;
since open() reuses the registered ref, both hold the same object. The
sheetRef JSDoc and types.md now say that with no registered ref the mount
catch-up is skipped entirely, not only that a programmatic close loses its
animation. components.md states the animatedIndex rewind once, and as a
blank-then-fade, which is what a plain interpolate on a snapped index does.
---
 CLAUDE.md                   | 4 ++--
 docs/docs/api/components.md | 4 ++--
 docs/docs/api/types.md      | 2 +-
 src/BottomSheetHost.tsx     | 7 ++++---
 4 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 6129f9e..3ce597f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -224,8 +224,8 @@ it. An inline id is minted per open and the item's unmount cleanup removes it,
 so the value cannot change while the item is mounted; the read is guarded on
 `usePortal` because a persistent id *can* be re-registered under a
 still-mounted item. A caller-supplied inline id re-opened in the same tick as
-its removal hands the wrapper the previous ref; the coordinator reads the
-registry fresh, so the sheet still closes via the give-up path. The prop *value*
+its removal keeps one ref object: `open()` reuses whatever is registered for the
+id, so the wrapper and the coordinator hold the same ref. The prop *value*
 must be stable for the life of the host: it is the element type, so a new value
 remounts every inline sheet (replayed open animation, a stateful wrapper's state
 gone). A derived value (`flag ? Wrapper : undefined`) breaks it even under the
diff --git a/docs/docs/api/components.md b/docs/docs/api/components.md
index 8b943d4..56c0c17 100644
--- a/docs/docs/api/components.md
+++ b/docs/docs/api/components.md
@@ -51,7 +51,7 @@ Place `BottomSheetHost` **outside** of `BottomSheetScaleView` to prevent sheets
 |------|------|-------------|
 | `SheetWrapper` | `React.ComponentType<SheetWrapperProps>` | Rendered around every **inline** sheet's content, inside that sheet's context. Receives `{ id, sheetRef, children }`. Portal and persistent sheets render where they are declared and are not wrapped. The prop **value** must stay stable for the life of the host — see below. |
 
-The wrapper is used as an element **type**, so a new prop value remounts every inline sheet: the adapter replays its open animation (its fresh shared value rewinds `animatedIndex`, so the backdrop blanks first) and a stateful wrapper loses its state — an error boundary forgets that it already failed. Pass a module-scope component; an inline arrow and a derived value (`flag ? SheetErrorBoundary : undefined`, or swapping one module-scope wrapper for another) both break it, the latter on the frame the flag resolves, typically while a sheet is open. Changing the value warns once per host in dev.
+The wrapper is used as an element **type**, so a new prop value remounts every inline sheet: the adapter replays its open animation and a stateful wrapper loses its state — an error boundary forgets that it already failed. Pass a module-scope component; an inline arrow and a derived value (`flag ? SheetErrorBoundary : undefined`, or swapping one module-scope wrapper for another) both break it, the latter on the frame the flag resolves, typically while a sheet is open. Changing the value warns once per host in dev.
 
 Use it to put an error boundary around each sheet, so one sheet failing never takes the host down. The fallback **must** render an adapter bound to `sheetRef`, so the manager keeps driving the sheet — `useBottomSheetContext().close()` still closes it. A fallback without an adapter leaves a sheet that crashes mid-close stuck at `closing`: `closeAll` skips it, `close()` answers `not-closable`, the Android back button is dead for the group, and its id is unusable until `destroyAll()`.
 
@@ -82,7 +82,7 @@ class SheetErrorBoundary extends React.Component<
 
 An adapter that mounts while its sheet is already `open` is expanded on mount, so the fallback appears in place without extra wiring. If it mounts while the sheet is `closing`, the sheet is ended instead — a crash mid-dismissal finishes the close rather than popping the error card back up.
 
-Give the fallback no scrim of its own — the manager's backdrop is still mounted behind it, and a second dim stacks on the first. Expect one visual artefact instead: a fallback adapter that seeds its position from zero rewinds the sheet's shared `animatedIndex` to -1 on its first render, so under an open sheet the manager backdrop fades out and back in behind the fallback. Seed the adapter from the sheet's current status to avoid it. Note too that the crashed adapter's unmount re-enables the manager scrim through its backdrop cleanup, so a sheet that passed `backdrop={false}` gets the group backdrop back for its fallback.
+Give the fallback no scrim of its own — the manager's backdrop is still mounted behind it, and a second dim stacks on the first. Expect one visual artefact instead: a fallback adapter that seeds its position from zero rewinds the sheet's shared `animatedIndex` to -1 on its first render, so under an open sheet the manager backdrop blanks and fades back in behind the fallback. Seed the adapter from the sheet's current status to avoid it. Note too that the crashed adapter's unmount re-enables the manager scrim through its backdrop cleanup, so a sheet that passed `backdrop={false}` gets the group backdrop back for its fallback.
 
 ---
 
diff --git a/docs/docs/api/types.md b/docs/docs/api/types.md
index 147069f..68366e5 100644
--- a/docs/docs/api/types.md
+++ b/docs/docs/api/types.md
@@ -207,7 +207,7 @@ interface SheetWrapperProps {
 
 Props of the component passed to `BottomSheetHost`'s `SheetWrapper`.
 
-`sheetRef` is `undefined` when no ref is registered for the id — the wrapper still renders, but the coordinator cannot drive a fallback adapter, so a programmatic close removes the sheet with no exit animation.
+`sheetRef` is `undefined` when no ref is registered for the id — the wrapper still renders, but nothing drives a fallback adapter: the mount catch-up is skipped (it neither opens under `open` nor ends the sheet under `closing`) and a programmatic close removes the sheet with no exit animation.
 
 ---
 
diff --git a/src/BottomSheetHost.tsx b/src/BottomSheetHost.tsx
index 38c87d5..b8eefbc 100644
--- a/src/BottomSheetHost.tsx
+++ b/src/BottomSheetHost.tsx
@@ -83,9 +83,10 @@ export interface SheetWrapperProps {
   /**
    * The ref the coordinator drives; a fallback adapter binds to it so
    * expand/close keep reaching the sheet. `undefined` when no ref is registered
-   * for the id — the wrapper still renders, but the coordinator cannot drive a
-   * fallback adapter, so a programmatic close removes the sheet with no exit
-   * animation.
+   * for the id — the wrapper still renders, but nothing drives a fallback
+   * adapter: the mount catch-up is skipped (it neither opens under `open` nor
+   * ends the sheet under `closing`) and a programmatic close removes the sheet
+   * with no exit animation.
    */
   sheetRef: SheetRef | undefined;
   children: ReactNode;

From c3fc83811913cf3438f94ec263e3a083eb35e5fe Mon Sep 17 00:00:00 2001
From: VadymBezpalko <vadym@gigaverse.com>
Date: Tue, 8 Sep 2026 22:22:04 +0200
Subject: [PATCH 13/13] refactor: trim the review-round comments and the
 identity-warning test harness

Comments and JSDoc keep one why each; the reasoning behind them lives in
CLAUDE.md. The identity-warning tests re-render the same host tree through
RNTL's rerender instead of two stateful host components and a module-level
trigger.
---
 src/BottomSheetHost.tsx       | 38 ++++++-------------
 src/QueueItem.tsx             |  8 ++--
 src/__tests__/host.test.tsx   | 69 +++++++++--------------------------
 src/useAdapterRef.ts          | 12 +++---
 src/useBottomSheetManager.tsx | 16 +++-----
 5 files changed, 43 insertions(+), 100 deletions(-)

diff --git a/src/BottomSheetHost.tsx b/src/BottomSheetHost.tsx
index b8eefbc..9a9a9a4 100644
--- a/src/BottomSheetHost.tsx
+++ b/src/BottomSheetHost.tsx
@@ -81,30 +81,21 @@ function reconcilePendingTransitions(groupId: string): () => void {
 export interface SheetWrapperProps {
   id: string;
   /**
-   * The ref the coordinator drives; a fallback adapter binds to it so
-   * expand/close keep reaching the sheet. `undefined` when no ref is registered
-   * for the id — the wrapper still renders, but nothing drives a fallback
-   * adapter: the mount catch-up is skipped (it neither opens under `open` nor
-   * ends the sheet under `closing`) and a programmatic close removes the sheet
-   * with no exit animation.
+   * The ref the coordinator drives; bind a fallback adapter to it. `undefined`
+   * when nothing is registered for the id: the wrapper still renders, but no
+   * catch-up or programmatic close reaches its fallback adapter.
    */
   sheetRef: SheetRef | undefined;
   children: ReactNode;
 }
 
-/**
- * Warns once per host when the `SheetWrapper` prop value changes.
- *
- * The wrapper is used as an element type, so a new value remounts every inline
- * sheet. Compares the value rather than skipping the first run: StrictMode
- * replays effects with the same ref object, and a run-counting flag would warn
- * on a wrapper that never changed.
- */
 function useSheetWrapperIdentityWarning(
   SheetWrapper?: ComponentType<SheetWrapperProps>
 ) {
   const seen = useRef({ last: SheetWrapper, warned: false });
 
+  // Compares the value instead of skipping the first run: StrictMode replays
+  // effects with the same ref object.
   useEffect(() => {
     const state = seen.current;
     if (state.last === SheetWrapper) {
@@ -116,10 +107,9 @@ function useSheetWrapperIdentityWarning(
       state.warned = true;
       console.warn(
         '[BottomSheet] `SheetWrapper` changed between renders, which remounts ' +
-          'every inline sheet: the adapter replays its open animation and a ' +
-          'stateful wrapper (an error boundary) loses its state. Keep the prop ' +
-          'value stable for the life of the host — a module-scope component, ' +
-          'not an inline arrow or a branch on a flag.'
+          'every inline sheet (open animation replays, a stateful wrapper loses ' +
+          'its state). Keep the value stable: a module-scope component, not an ' +
+          'inline arrow or a branch on a flag.'
       );
     }
   }, [SheetWrapper]);
@@ -129,15 +119,9 @@ interface BottomSheetHostProps {
   /**
    * Wraps each inline sheet's content inside its context — the place for a
    * per-sheet error boundary whose fallback is an adapter bound to `sheetRef`.
-   * Portal and persistent sheets render where they are declared and are not
-   * wrapped.
-   *
-   * The prop *value* must stay stable for the life of the host: it is used as
-   * an element type, so a new value remounts every inline sheet — the adapter
-   * replays its open animation and a stateful wrapper loses its state. Pass a
-   * module-scope component, not an inline arrow and not a branch on a flag
-   * (`flag ? Wrapper : undefined` remounts on the frame the flag resolves).
-   * Changing it warns in dev.
+   * Portal and persistent sheets are not wrapped. Keep the value stable for the
+   * life of the host: it is the element type, so a new value (an inline arrow,
+   * `flag ? Wrapper : undefined`) remounts every inline sheet; dev warns.
    */
   SheetWrapper?: ComponentType<SheetWrapperProps>;
 }
diff --git a/src/QueueItem.tsx b/src/QueueItem.tsx
index 3c72e49..495d93c 100644
--- a/src/QueueItem.tsx
+++ b/src/QueueItem.tsx
@@ -51,11 +51,9 @@ export const QueueItem = memo(function QueueItem({
 
   const animatedIndex = getAnimatedIndex(id);
 
-  // `open()` registers the ref, then writes the store; React only schedules the
-  // render that write causes, so this first — and, with the compiler's
-  // `[id, usePortal]` cache, only — read sees the entry. Nothing async or
-  // render-flushing may go between those two calls. Guarded on `usePortal`
-  // because a persistent id can be re-registered under a still-mounted item.
+  // `open()` registers the ref, then writes the store, and React only schedules
+  // the render that write causes — so this cached first read sees the entry.
+  // Guarded: a persistent id can be re-registered under a still-mounted item.
   const sheetRef = usePortal ? undefined : getSheetRef(id);
 
   const inlineContent = SheetWrapper ? (
diff --git a/src/__tests__/host.test.tsx b/src/__tests__/host.test.tsx
index a7853bf..2f59a8b 100644
--- a/src/__tests__/host.test.tsx
+++ b/src/__tests__/host.test.tsx
@@ -3,7 +3,6 @@ import {
   createRef,
   useEffect,
   useImperativeHandle,
-  useState,
   type ReactElement,
   type Ref,
 } from 'react';
@@ -44,15 +43,17 @@ const ManagerProbe = () => {
   return null;
 };
 
+const hostTree = (SheetWrapper?: React.ComponentType<SheetWrapperProps>) => (
+  <SafeAreaProvider initialMetrics={initialMetrics}>
+    <BottomSheetManagerProvider id="g1">
+      <ManagerProbe />
+      <BottomSheetHost SheetWrapper={SheetWrapper} />
+    </BottomSheetManagerProvider>
+  </SafeAreaProvider>
+);
+
 const renderHost = (SheetWrapper?: React.ComponentType<SheetWrapperProps>) =>
-  render(
-    <SafeAreaProvider initialMetrics={initialMetrics}>
-      <BottomSheetManagerProvider id="g1">
-        <ManagerProbe />
-        <BottomSheetHost SheetWrapper={SheetWrapper} />
-      </BottomSheetManagerProvider>
-    </SafeAreaProvider>
-  );
+  render(hostTree(SheetWrapper));
 
 const seenSheetRefs: unknown[] = [];
 const lastSeenSheetRef = () => seenSheetRefs[seenSheetRefs.length - 1];
@@ -369,41 +370,7 @@ describe('registered ref identity', () => {
 
 const StableWrapper = ({ children }: SheetWrapperProps) => <>{children}</>;
 
-const TickWrapperBody = ({
-  children,
-}: SheetWrapperProps & { tick: number }) => <>{children}</>;
-
-let forceHostRender: (() => void) | undefined;
-
-const inProviders = (children: ReactElement) => (
-  <SafeAreaProvider initialMetrics={initialMetrics}>
-    <BottomSheetManagerProvider id="g1">{children}</BottomSheetManagerProvider>
-  </SafeAreaProvider>
-);
-
-// The closure captures `tick`, so the compiler cannot outline it to module
-// scope — the prop value really is new on every parent render.
-const UnstableWrapperHost = () => {
-  const [tick, setTick] = useState(0);
-  useEffect(() => {
-    forceHostRender = () => setTick((value) => value + 1);
-  }, []);
-  return inProviders(
-    <BottomSheetHost
-      SheetWrapper={(props: SheetWrapperProps) => (
-        <TickWrapperBody tick={tick} {...props} />
-      )}
-    />
-  );
-};
-
-const StableWrapperHost = () => {
-  const [, setTick] = useState(0);
-  useEffect(() => {
-    forceHostRender = () => setTick((value) => value + 1);
-  }, []);
-  return inProviders(<BottomSheetHost SheetWrapper={StableWrapper} />);
-};
+const freshWrapper = () => (props: SheetWrapperProps) => <>{props.children}</>;
 
 const identityWarnings = () =>
   (console.warn as jest.Mock).mock.calls.filter(([message]) =>
@@ -412,19 +379,19 @@ const identityWarnings = () =>
 
 describe('SheetWrapper identity warning', () => {
   it('warns once when the prop value changes between renders', () => {
-    render(<UnstableWrapperHost />);
+    const { rerender } = render(hostTree(freshWrapper()));
 
-    act(() => forceHostRender?.());
-    act(() => forceHostRender?.());
+    rerender(hostTree(freshWrapper()));
+    rerender(hostTree(freshWrapper()));
 
     expect(identityWarnings()).toHaveLength(1);
   });
 
-  it('stays quiet for a module-scope wrapper across the same re-renders', () => {
-    render(<StableWrapperHost />);
+  it('stays quiet for a stable wrapper across the same re-renders', () => {
+    const { rerender } = render(hostTree(StableWrapper));
 
-    act(() => forceHostRender?.());
-    act(() => forceHostRender?.());
+    rerender(hostTree(StableWrapper));
+    rerender(hostTree(StableWrapper));
 
     expect(identityWarnings()).toHaveLength(0);
   });
diff --git a/src/useAdapterRef.ts b/src/useAdapterRef.ts
index 14682c1..3c0a169 100644
--- a/src/useAdapterRef.ts
+++ b/src/useAdapterRef.ts
@@ -29,13 +29,11 @@ export function useAdapterRef(
   const ref = contextRef ?? forwardedRef;
   const id = useMaybeBottomSheetContext()?.id;
 
-  // The coordinator drives status *changes* only, so an adapter that mounts
-  // under a live status has nobody to drive it. Under `open` it opens itself;
-  // under `closing` a fresh adapter cannot animate a close it never opened, so
-  // the sheet is ended in the store instead (same as `driveSheetRef`'s give-up
-  // path) — a mid-close remount ends the sheet without re-animating. `hidden`
-  // is deliberately left alone: nothing is stuck there and the store owns the
-  // restore. Passive effect: the imperative handle is attached by then.
+  // The coordinator drives status *changes*, so an adapter mounting under a
+  // live status has nobody to drive it: under `open` it opens itself; under
+  // `closing` it cannot animate a close it never opened, so the sheet is ended
+  // in the store, as driveSheetRef's give-up path does. Passive effect: the
+  // imperative handle is attached by then.
   useEffect(() => {
     if (!id || typeof ref !== 'object') {
       return;
diff --git a/src/useBottomSheetManager.tsx b/src/useBottomSheetManager.tsx
index e44fa42..715ebc5 100644
--- a/src/useBottomSheetManager.tsx
+++ b/src/useBottomSheetManager.tsx
@@ -44,9 +44,8 @@ export const useBottomSheetManager = () => {
       options.groupId || bottomSheetManagerContext?.groupId || 'default';
 
     const id = options.id || Math.random().toString(36);
-    // One registered id must map to one ref object: QueueItem's render-time
-    // read is cached for the item's life, and a persistent sheet registers its
-    // own ref on mount.
+    // One id, one ref object: QueueItem caches its render-time read, and a
+    // persistent sheet registers its own ref on mount.
     const existing = getSheetRef(id);
     const ref = existing ?? React.createRef<SheetAdapterRef>();
 
@@ -54,8 +53,8 @@ export const useBottomSheetManager = () => {
       ref,
     } as { ref: typeof ref });
 
-    // QueueItem reads this map during its first render, and the store write
-    // below is what schedules that render — so register before writing.
+    // Before the store write: QueueItem reads the map in the render that
+    // write schedules.
     setSheetRef(id, ref);
 
     const result = storeOpen(
@@ -70,11 +69,8 @@ export const useBottomSheetManager = () => {
       options.mode
     );
 
-    // A rejected open reclaims only the entry it created: inline IDs are
-    // random and nothing but QueueItem's unmount cleans the map, so an orphan
-    // leaks per rejected call — but deleting a ref registered before this call
-    // strips a live explicit id or a persistent sheet of the one the
-    // coordinator drives.
+    // Reclaim only what this call registered (random inline ids would leak one
+    // entry per rejection); a pre-existing ref belongs to a live sheet.
     if (!result.opened) {
       if (!existing) {
         cleanupSheetRef(id);