@delacour/react-native-ui 0.1.0-alpha.20261005222904 → 0.1.0-alpha.20261006134908

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20261005222904",
+	"version": "0.1.0-alpha.20261006134908",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -53,6 +53,7 @@
 		"./label": "./src/components/label/index.ts",
 		"./list-group": "./src/components/list-group/index.ts",
 		"./meter": "./src/components/meter/index.ts",
+		"./overlay": "./src/components/overlay/index.ts",
 		"./pressable": "./src/components/pressable/index.ts",
 		"./progress": "./src/components/progress/index.ts",
 		"./provider": "./src/components/provider/index.ts",
@@ -100,8 +101,8 @@
 	},
 	"peerDependencies": {
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-bottom-sheet": "0.1.0-alpha.20261005222904",
-		"@delacour/react-native-charts": "0.1.0-alpha.20261005222904",
+		"@delacour/react-native-bottom-sheet": "0.1.0-alpha.20261006134908",
+		"@delacour/react-native-charts": "0.1.0-alpha.20261006134908",
 		"@legendapp/list": ">=3.3",
 		"expo-linear-gradient": ">=15",
 		"expo-router": ">=57",

package/src/components/avatar/AGENTS.md

@@ -44,11 +44,11 @@ Compound root plus `Avatar.Badge` and `Avatar.Group`.
   the clipped circle. An `Avatar.Badge` hangs over the circle's edge, and a
   single clipped box would cut it in half. A test asserts `overflow-hidden` is on
   `face` and never on `root`.
-- **Initials are the first letter of the first and last word.** `Mary Jane
-  Watson` is `MW`, the way a person signs, and `Cher` is `C`.
+- **Initials are the first letter of the first and last word.** `Anahera Rose
+  Tui` is `AT`, the way a person signs, and `Mihi` is `M`.
   `resolveAvatarInitials` walks code points rather than UTF-16 units, so a letter
   outside the basic plane is never split into a replacement box, and skips
-  leading punctuation so `"(Kate)"` still gives `K`. `fallback` overrides the
+  leading punctuation so `"(Aria)"` still gives `A`. `fallback` overrides the
   drawn text only; `name` is still what a screen reader reads.
 - **Two axes paint the fallback, on `Badge`'s six colours.** `variant` is `soft`
   or `solid`, `color` is `default` … `info`, and the twelve cells live in
@@ -77,7 +77,7 @@ Compound root plus `Avatar.Badge` and `Avatar.Group`.
 - **The avatar is one element to assistive technology.** The root is
   `accessible`, so an `Avatar.Badge` inside it is never focused on its own. A
   presence dot has no words; put the status into the avatar's
-  `accessibilityLabel` (`"Kate Austen, online"`).
+  `accessibilityLabel` (`"Aria Whitlock, online"`).
 - **`Avatar.Badge` is a pin, and a dot only when empty.** Given children — a
   `Badge` with a count, an `Icon` — it positions them and adds nothing else, so a
   count keeps the look it has everywhere else. Empty, it draws a dot sized to

package/src/components/avatar/avatar.tsx

@@ -165,7 +165,7 @@ function AvatarRoot({
  * is tried again. With no `fallback` and no `name` the fallback is a person glyph.
  *
  * `name` is what a screen reader reads, and its initials — first and last word,
- * `Mary Jane Watson` → `MW` — are the default fallback. `fallback` overrides the
+ * `Anahera Rose Tui` → `AT` — are the default fallback. `fallback` overrides the
  * drawn text only.
  *
  * `variant` and `color` paint the fallback surface, on the same six colours a
@@ -180,10 +180,10 @@ function AvatarRoot({
  * corner, outside the clipped circle so it is never cut in half.
  *
  * @example
- * <Avatar name="Kate Austen" source={{ uri: user.avatarUrl }} />
+ * <Avatar name="Aria Whitlock" source={{ uri: user.avatarUrl }} />
  *
  * @example
- * <Avatar accessibilityLabel="Kate Austen, online" name="Kate Austen">
+ * <Avatar accessibilityLabel="Aria Whitlock, online" name="Aria Whitlock">
  *   <Avatar.Badge placement="bottom-right" />
  * </Avatar>
  *

package/src/components/avatar/avatar.utils.test.ts

@@ -10,17 +10,17 @@ import {
 
 describe("resolveAvatarInitials", () => {
 	test("takes the first letter of the first and last words", () => {
-		expect(resolveAvatarInitials("Kate Austen")).toBe("KA");
-		expect(resolveAvatarInitials("Mary Jane Watson")).toBe("MW");
+		expect(resolveAvatarInitials("Aria Whitlock")).toBe("AW");
+		expect(resolveAvatarInitials("Anahera Rose Tui")).toBe("AT");
 	});
 
 	test("a single word gives a single letter", () => {
-		expect(resolveAvatarInitials("Cher")).toBe("C");
+		expect(resolveAvatarInitials("Mihi")).toBe("M");
 	});
 
 	test("uppercases, and ignores surrounding and repeated whitespace", () => {
-		expect(resolveAvatarInitials("  oliver   lee ")).toBe("OL");
-		expect(resolveAvatarInitials("ada\tlovelace")).toBe("AL");
+		expect(resolveAvatarInitials("  rawiri   kemp ")).toBe("RK");
+		expect(resolveAvatarInitials("lena\tvarga")).toBe("LV");
 	});
 
 	test("is empty for an empty, blank or missing name", () => {
@@ -31,15 +31,15 @@ describe("resolveAvatarInitials", () => {
 
 	test("never splits a letter outside the basic plane", () => {
 		// A naive `word[0]` would take half of a surrogate pair and draw a box.
-		expect(resolveAvatarInitials("𝒜da 𝒵ed")).toBe("𝒜𝒵");
+		expect(resolveAvatarInitials("𝒜ria 𝒲hitlock")).toBe("𝒜𝒲");
 	});
 
 	test("keeps letters in scripts with no case", () => {
-		expect(resolveAvatarInitials("李 小龍")).toBe("李小");
+		expect(resolveAvatarInitials("森山 健二")).toBe("森健");
 	});
 
 	test("skips a leading punctuation mark in a word", () => {
-		expect(resolveAvatarInitials("(Kate) 'Austen'")).toBe("KA");
+		expect(resolveAvatarInitials("(Aria) 'Whitlock'")).toBe("AW");
 	});
 });
 
@@ -156,11 +156,11 @@ describe("resolveAvatarOverflowLabel", () => {
 
 describe("resolveAvatarAccessibilityLabel", () => {
 	test("prefers the name", () => {
-		expect(resolveAvatarAccessibilityLabel({ name: "Kate Austen", fallback: "KA" })).toBe("Kate Austen");
+		expect(resolveAvatarAccessibilityLabel({ name: "Aria Whitlock", fallback: "AW" })).toBe("Aria Whitlock");
 	});
 
 	test("falls back to the fallback text", () => {
-		expect(resolveAvatarAccessibilityLabel({ fallback: "KA" })).toBe("KA");
+		expect(resolveAvatarAccessibilityLabel({ fallback: "AW" })).toBe("AW");
 	});
 
 	test("is undefined when there is nothing to read", () => {
@@ -169,6 +169,6 @@ describe("resolveAvatarAccessibilityLabel", () => {
 	});
 
 	test("an explicit label wins over both", () => {
-		expect(resolveAvatarAccessibilityLabel({ accessibilityLabel: "You", name: "Kate Austen" })).toBe("You");
+		expect(resolveAvatarAccessibilityLabel({ accessibilityLabel: "You", name: "Aria Whitlock" })).toBe("You");
 	});
 });

package/src/components/avatar/avatar.utils.ts

@@ -23,7 +23,7 @@ function initialOf(word: string): string {
 
 /**
  * Up to two initials from a name: the first letter of the first word and of the
- * last. `Mary Jane Watson` reads `MW`, which is how a person signs rather than
+ * last. `Anahera Rose Tui` reads `AT`, which is how a person signs rather than
  * how a form abbreviates them. A single word gives a single letter.
  *
  * Walks code points rather than UTF-16 units, so a letter outside the basic

package/src/components/bottom-sheet/bottom-sheet-provider.tsx

@@ -0,0 +1,42 @@
+import {
+	BottomSheetProvider as HeadlessProvider,
+	type BottomSheetProviderProps as HeadlessProviderProps,
+} from "@delacour/react-native-bottom-sheet";
+import type { ReactElement } from "react";
+import { TeleportProvidedContext, useIsTeleportProvided } from "../overlay/overlay.context";
+
+export type BottomSheetProviderProps = Omit<HeadlessProviderProps, "hasPortalProvider">;
+
+/**
+ * The engine's provider, mounted once by the app — and aware of
+ * `OverlayProvider`.
+ *
+ * Both providers need teleport's `PortalProvider`, and there must be exactly
+ * one: teleport registers hosts natively by name, so two would mean two hosts
+ * called `"root"`. Whichever of the two mounts outermost mounts it and says so
+ * through `TeleportProvidedContext`; the inner one skips its own. Sheets and
+ * overlays then share one `"root"` host, ordered by `zIndex` — every overlay's
+ * band starts above every sheet's.
+ *
+ * The overlay folder's context file is a leaf (rule 3): it imports nothing but
+ * React, so this cross-folder import cannot close a cycle.
+ *
+ * @example
+ * <DelacourProvider>
+ *   <OverlayProvider>
+ *     <BottomSheetProvider>
+ *       <Stack />
+ *     </BottomSheetProvider>
+ *   </OverlayProvider>
+ * </DelacourProvider>
+ */
+export function BottomSheetProvider({ children }: BottomSheetProviderProps): ReactElement {
+	const isTeleportProvided = useIsTeleportProvided();
+
+	return (
+		<HeadlessProvider hasPortalProvider={isTeleportProvided}>
+			<TeleportProvidedContext.Provider value>{children}</TeleportProvidedContext.Provider>
+		</HeadlessProvider>
+	);
+}
+BottomSheetProvider.displayName = "DelacourUI.BottomSheet.Provider";

package/src/components/bottom-sheet/bottom-sheet.tsx

@@ -1,6 +1,5 @@
 import {
 	BottomSheetHost,
-	BottomSheetProvider,
 	BottomSheet as Headless,
 	type BottomSheetProps as HeadlessBottomSheetProps,
 } from "@delacour/react-native-bottom-sheet";
@@ -18,6 +17,7 @@ import { BottomSheetFooter } from "./bottom-sheet-footer";
 import { BottomSheetHandle } from "./bottom-sheet-handle";
 import { BottomSheetLegendList } from "./bottom-sheet-legend-list";
 import { BottomSheetOverlay } from "./bottom-sheet-overlay";
+import { BottomSheetProvider } from "./bottom-sheet-provider";
 import { BottomSheetScrollView } from "./bottom-sheet-scroll-view";
 import { BottomSheetSectionList } from "./bottom-sheet-section-list";
 import { BottomSheetStep, BottomSheetSteps } from "./bottom-sheet-steps";
@@ -172,7 +172,7 @@ export const BottomSheet = Object.assign(BottomSheetRoot, {
 	Step: BottomSheetStep,
 	/** A place for sheets to teleport to other than the root — the recipe for a native modal. */
 	Host: BottomSheetHost,
-	/** The engine's provider. Mount it once, inside `DelacourProvider`. */
+	/** The engine's provider, sharing `OverlayProvider`'s teleport host. Mount it once, inside `DelacourProvider`. */
 	Provider: BottomSheetProvider,
 	displayName: "DelacourUI.BottomSheet",
 });

package/src/components/bottom-sheet/index.ts

@@ -3,8 +3,6 @@ export {
 	type BottomSheetContextValue,
 	type BottomSheetHostProps,
 	type BottomSheetPortalProps,
-	BottomSheetProvider,
-	type BottomSheetProviderProps,
 	type BottomSheetRef,
 	type BottomSheetRegistryValue,
 	type BottomSheetTextInputHandlers,
@@ -46,6 +44,7 @@ export type { BottomSheetFooterProps } from "./bottom-sheet-footer";
 export type { BottomSheetHandleProps } from "./bottom-sheet-handle";
 export type { BottomSheetLegendListProps } from "./bottom-sheet-legend-list";
 export type { BottomSheetOverlayProps } from "./bottom-sheet-overlay";
+export { BottomSheetProvider, type BottomSheetProviderProps } from "./bottom-sheet-provider";
 export type { BottomSheetScrollViewProps } from "./bottom-sheet-scroll-view";
 export type { BottomSheetSectionListProps } from "./bottom-sheet-section-list";
 export type { BottomSheetStepProps, BottomSheetStepsProps } from "./bottom-sheet-steps";

package/src/components/overlay/AGENTS.md

@@ -0,0 +1,89 @@
+# Overlay
+
+The layer under every overlay in this library — Dialog, Drawer, Popover, Tooltip, Toast,
+Feedback. Not a component anyone renders on its own: the provider an app mounts once, and the
+parts and hooks an overlay is drawn with.
+
+`import { Overlay, OverlayProvider, useOverlayBackHandler, useOverlayPresence } from "@delacour/react-native-ui/overlay";`
+
+`react-native-teleport` is an **optional peer**, as it is for `BottomSheet`: an app that never
+imports an overlay never resolves it. The consequence is the same one thing to do — **mount
+`OverlayProvider` once**, inside `DelacourProvider`, around `BottomSheetProvider` and the navigator.
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/overlay` |
+| `overlay.tsx` | `Overlay` — the root is the provider: teleport's `PortalProvider` (skipped when one is already above), the registry and the touch-start fan-out; the `Object.assign` names `Portal` and `Scrim`. `OverlayProvider` is the same component, under the name a root layout reads best with |
+| `overlay-portal.tsx` | `Overlay.Portal` — registers while mounted, teleports to `"root"` in a `box-none` absolute fill carrying the registry's `zIndex`; inline without a provider |
+| `overlay-scrim.tsx` | `Overlay.Scrim` — `bg-overlay`, opacity follows presence, hidden from assistive technology |
+| `overlay.context.tsx` | **Leaf.** `OverlayContext`, `TeleportProvidedContext` and their hooks. `bottom-sheet/` imports it |
+| `overlay-registry.ts` | **Pure.** The z-order reducer, `zIndexOfOverlay`, `topOverlay`, `isTopOverlay`, `OVERLAY_LAYER_BASE` |
+| `overlay-presence.ts` | **Pure.** `reducePresence` — `closed → entering → open → exiting → closed` |
+| `overlay.variants.ts` | `overlayVariants` (`scrim`), `OVERLAY_MOTION`, `OVERLAY_SCRIM_TOKEN` |
+| `use-overlay-presence.ts` | `useOverlayPresence` — keeps an overlay mounted through its exit, drives `progress` 0 → 1 |
+| `use-overlay-back-handler.ts` | `useOverlayBackHandler` — Android back, only while the overlay is the top |
+| `*.test.ts` | The registry, the presence machine, the scrim token and the motion constants |
+
+## Design
+
+- **There is exactly one teleport `PortalProvider` in an app, and this is why the folder
+  exists.** Teleport registers its hosts natively by name, and the bottom-sheet engine's
+  provider already mounts one with a `"root"` host. Six overlays each mounting their own would
+  mean seven hosts called `"root"`. So `OverlayProvider` and this library's `BottomSheetProvider`
+  each mount teleport's provider only when `TeleportProvidedContext` says none is above, and set
+  it when they do — either mount order works, and the engine's provider learned
+  `hasPortalProvider` to make the skip possible. Everything draws into one `"root"` host.
+- **One host means one z-order, so the layers are bands.** Sheets are stamped from 1 by the
+  engine's registry; overlays take `modal` 1000+, `anchored` 2000+, `toast` 3000+. Every overlay
+  draws over every sheet, a popover over the dialog that opened it, a toast over both. Within a
+  band the later open is on top, and a re-open brings an overlay forward. The number is base plus
+  **rank** in the band, never the raw open counter, so a long session cannot walk a dialog into
+  the popover band — a test opens five thousand to prove it. The cost: a sheet opened *from* a
+  dialog draws under it. Do not open a sheet from a dialog.
+- **The registry entry lives exactly as long as `Overlay.Portal` is mounted.** Mount the portal
+  only while `useOverlayPresence().isPresent`, and the registry, the z-order and the back button
+  all follow presence with nothing else to keep in sync.
+- **Back closes only the top overlay.** `useOverlayBackHandler` takes the portal's `id` and
+  subscribes only while that id is `topOverlay` among `modal` and `anchored` — a toast never takes
+  the back button. React Native calls the most recent listener first, and an overlay over a sheet
+  subscribed after it, so the overlay answers first and returns `true`.
+- **Presence is a reducer so an interrupted animation is boring.** A re-open mid-exit goes back
+  to `entering` from wherever `progress` is; a close mid-entrance goes to `exiting`. The finish
+  callback reaches React only when the timing ran to the end, and a stale finish (`entered` while
+  `exiting`) is a no-op in the reducer, so the hook keeps no generation counter.
+- **Overlay motion is behaviour, not decoration.** `isMotionCalm` does not still it — an overlay
+  that did not appear would change what the screen says — but every animation is finite, so an E2E
+  runner's settle wait ends anyway. Under reduce motion the fade still runs (opacity is not
+  motion) and `isReduced` tells the component to drop its transforms. Exit (160 ms) is quicker
+  than entrance (220 ms): a dismissed overlay should get out of the way.
+- **The scrim is `bg-overlay` at opacity 1**, the token carrying its own alpha, for
+  `BottomSheet.Overlay`'s reason. It is React Native's `Pressable`, not this library's: it wants
+  no feedback or haptic, and a Gesture Handler tap there would race a drawer's pan for the touch.
+  It always takes the touch, even with no `onDismiss`, because the app under a non-dismissible
+  dialog must not be pressable. It is hidden from assistive technology; a screen reader user
+  dismisses through the panel's `onAccessibilityEscape` or the back button.
+- **The portal's wrapper is `box-none`.** An overlay with no scrim — a toast, a tooltip — leaves
+  the app under it interactive.
+- **The provider hears every touch that starts beneath it, and claims none.** Its children sit in a
+  `flex: 1` `View` whose `onTouchStart` fans out to `subscribeTouchStart` listeners. `onTouchStart`
+  is a bubbling touch event, not a responder negotiation, so it never stops the touch reaching its
+  target or a Gesture Handler gesture; and React Native bubbles it through the React tree rather
+  than the native one, so a touch inside a teleported overlay arrives too. It exists for Tooltip,
+  whose outside tap must close it *and* still press what it landed on — a full-screen catcher
+  under the panel, Popover's way, would swallow that tap, and nothing but a common ancestor of the
+  whole app can hear a touch on a view the tooltip knows nothing about.
+- **No provider, no teleport.** Without `OverlayProvider` a portal renders inline, in an absolute
+  fill of the nearest positioned ancestor, and warns once in development; it may be clipped. That
+  is a working fallback for a `delacour add` copy in an app that has not mounted the provider yet,
+  not a supported layout.
+- **`DelacourProvider` cannot mount this** — the peer decision in
+  [DelacourProvider](../provider/AGENTS.md): teleport is optional. `apps/playground/src/app/_layout.tsx`
+  is the reference mount.
+
+## Testing
+
+`bun test` reaches the registry, the presence machine, the scrim token and the motion constants.
+The provider, the portal and the hooks are verified on a simulator through every overlay's
+gallery — the foundation has no gallery of its own, the way `DelacourProvider` has none.

package/src/components/overlay/index.ts

@@ -0,0 +1,27 @@
+export { Overlay, OverlayProvider, type OverlayProviderProps } from "./overlay";
+export {
+	OverlayContext,
+	type OverlayContextValue,
+	TeleportProvidedContext,
+	useIsTeleportProvided,
+	useOptionalOverlay,
+} from "./overlay.context";
+export { OVERLAY_MOTION, OVERLAY_SCRIM_TOKEN, type OverlayVariantProps, overlayVariants } from "./overlay.variants";
+export type { OverlayPortalProps } from "./overlay-portal";
+export { isPresent, type PresenceEvent, type PresencePhase, presenceTarget, reducePresence } from "./overlay-presence";
+export {
+	INITIAL_OVERLAY_REGISTRY,
+	isTopOverlay,
+	OVERLAY_LAYER_BASE,
+	OVERLAY_LAYERS,
+	type OverlayLayer,
+	type OverlayRegistryAction,
+	type OverlayRegistryEntry,
+	type OverlayRegistryState,
+	reduceOverlayRegistry,
+	topOverlay,
+	zIndexOfOverlay,
+} from "./overlay-registry";
+export type { OverlayScrimProps } from "./overlay-scrim";
+export { type UseOverlayBackHandlerOptions, useOverlayBackHandler } from "./use-overlay-back-handler";
+export { type OverlayPresence, type UseOverlayPresenceOptions, useOverlayPresence } from "./use-overlay-presence";

package/src/components/overlay/overlay-portal.tsx

@@ -0,0 +1,84 @@
+import { type ReactElement, type ReactNode, useEffect, useId } from "react";
+import { StyleSheet, View } from "react-native";
+import { Portal } from "react-native-teleport";
+import { useOptionalOverlay } from "./overlay.context";
+import { type OverlayLayer, zIndexOfOverlay } from "./overlay-registry";
+
+export type OverlayPortalProps = {
+	/** Which band of the z-order this overlay draws in. */
+	layer: OverlayLayer;
+	children?: ReactNode;
+	/**
+	 * The overlay's registry id. Pass the same id to `useOverlayBackHandler` so
+	 * the back button knows whether this overlay is the top. Defaults to a
+	 * `useId()` of the portal's own.
+	 */
+	id?: string;
+	/** Render where it is written instead of teleporting. Default false. */
+	isInline?: boolean;
+	/** The teleport host. Default `"root"` — the one `OverlayProvider`'s teleport provider fills the app with. */
+	hostName?: string;
+};
+
+let hasWarnedMissingProvider = false;
+
+/**
+ * Draws its children over the whole app, in its layer of the z-order.
+ *
+ * Teleport moves the native view and leaves the React tree where it was, so
+ * every context provided around the overlay's trigger — a theme, a form, a
+ * query client — still reaches what the portal draws.
+ *
+ * The overlay is in the registry for exactly as long as this is mounted, so
+ * mount it only while the overlay is present (`useOverlayPresence`). Its
+ * wrapper is an absolute fill and `box-none`: it takes no touch of its own, so
+ * an overlay with no scrim — a toast, a tooltip — leaves the app under it
+ * interactive.
+ *
+ * Without an `OverlayProvider` above, or with `isInline`, the children render
+ * where they are written, in an absolute fill of the nearest positioned
+ * ancestor — and the missing provider warns once in development.
+ */
+export function OverlayPortal({
+	layer,
+	children,
+	id,
+	isInline = false,
+	hostName = "root",
+}: OverlayPortalProps): ReactElement {
+	const ownId = useId();
+	const overlayId = id ?? ownId;
+	const registry = useOptionalOverlay();
+
+	const present = registry?.present;
+	const dismissed = registry?.dismissed;
+	useEffect(() => {
+		if (present === undefined || dismissed === undefined) return;
+		present(overlayId, layer);
+		return () => dismissed(overlayId);
+	}, [present, dismissed, overlayId, layer]);
+
+	useEffect(() => {
+		if (!__DEV__ || registry !== null || isInline || hasWarnedMissingProvider) return;
+		hasWarnedMissingProvider = true;
+		console.warn(
+			"Overlay.Portal: an overlay rendered with no <OverlayProvider> above it, so it draws inline and may be clipped. Mount OverlayProvider once at the app root."
+		);
+	}, [registry, isInline]);
+
+	const zIndex = registry === null ? 0 : zIndexOfOverlay(registry.state, overlayId);
+	const frame = (
+		<View pointerEvents="box-none" style={[StyleSheet.absoluteFill, { zIndex }]}>
+			{children}
+		</View>
+	);
+
+	if (isInline || registry === null) return frame;
+
+	return (
+		<Portal hostName={hostName} style={[StyleSheet.absoluteFill, { zIndex }]}>
+			{frame}
+		</Portal>
+	);
+}
+OverlayPortal.displayName = "DelacourUI.Overlay.Portal";

package/src/components/overlay/overlay-presence.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import { isPresent, type PresencePhase, presenceTarget, reducePresence } from "./overlay-presence";
+
+describe("reducePresence", () => {
+	const cases: [PresencePhase, Parameters<typeof reducePresence>[1]["type"], PresencePhase][] = [
+		["closed", "open", "entering"],
+		["closed", "close", "closed"],
+		["closed", "entered", "closed"],
+		["closed", "exited", "closed"],
+		["entering", "entered", "open"],
+		["entering", "close", "exiting"],
+		["entering", "open", "entering"],
+		["entering", "exited", "entering"],
+		["open", "close", "exiting"],
+		["open", "open", "open"],
+		["open", "entered", "open"],
+		["exiting", "exited", "closed"],
+		["exiting", "open", "entering"],
+		["exiting", "close", "exiting"],
+		["exiting", "entered", "exiting"],
+	];
+
+	for (const [from, event, to] of cases) {
+		test(`${from} + ${event} → ${to}`, () => {
+			expect(reducePresence(from, { type: event })).toBe(to);
+		});
+	}
+});
+
+describe("isPresent", () => {
+	test("is false only when closed", () => {
+		expect(isPresent("closed")).toBe(false);
+		expect(isPresent("entering")).toBe(true);
+		expect(isPresent("open")).toBe(true);
+		expect(isPresent("exiting")).toBe(true);
+	});
+});
+
+describe("presenceTarget", () => {
+	test("animates toward 1 while entering or open, 0 otherwise", () => {
+		expect(presenceTarget("entering")).toBe(1);
+		expect(presenceTarget("open")).toBe(1);
+		expect(presenceTarget("exiting")).toBe(0);
+		expect(presenceTarget("closed")).toBe(0);
+	});
+});

package/src/components/overlay/overlay-presence.ts

@@ -0,0 +1,49 @@
+/**
+ * Where an overlay is in its life: absent, arriving, shown, or leaving.
+ *
+ * `exiting` is the whole reason this exists — an overlay that unmounted the
+ * moment it closed would have no exit animation to play.
+ */
+export type PresencePhase = "closed" | "entering" | "open" | "exiting";
+
+export type PresenceEvent =
+	/** The owner asked for it to show. */
+	| { type: "open" }
+	/** The owner asked for it to hide. */
+	| { type: "close" }
+	/** The entrance animation finished. */
+	| { type: "entered" }
+	/** The exit animation finished. */
+	| { type: "exited" };
+
+/**
+ * The presence machine as a pure reducer.
+ *
+ * A re-open during the exit reverses into `entering` from wherever the
+ * animation is, and a close during the entrance reverses into `exiting`. A
+ * finish event from an animation that was interrupted — `entered` while
+ * already `exiting` — is stale and changes nothing, so the hook needs no
+ * generation counter to drop it.
+ */
+export function reducePresence(phase: PresencePhase, event: PresenceEvent): PresencePhase {
+	switch (event.type) {
+		case "open":
+			return phase === "closed" || phase === "exiting" ? "entering" : phase;
+		case "close":
+			return phase === "entering" || phase === "open" ? "exiting" : phase;
+		case "entered":
+			return phase === "entering" ? "open" : phase;
+		case "exited":
+			return phase === "exiting" ? "closed" : phase;
+	}
+}
+
+/** Whether the overlay is mounted: every phase but `closed`. */
+export function isPresent(phase: PresencePhase): boolean {
+	return phase !== "closed";
+}
+
+/** The progress value the phase animates toward — 1 shown, 0 hidden. */
+export function presenceTarget(phase: PresencePhase): 0 | 1 {
+	return phase === "entering" || phase === "open" ? 1 : 0;
+}

package/src/components/overlay/overlay-registry.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from "bun:test";
+import {
+	INITIAL_OVERLAY_REGISTRY,
+	isTopOverlay,
+	OVERLAY_LAYER_BASE,
+	type OverlayRegistryState,
+	reduceOverlayRegistry,
+	topOverlay,
+	zIndexOfOverlay,
+} from "./overlay-registry";
+
+function apply(...actions: Parameters<typeof reduceOverlayRegistry>[1][]): OverlayRegistryState {
+	return actions.reduce(reduceOverlayRegistry, INITIAL_OVERLAY_REGISTRY);
+}
+
+describe("OVERLAY_LAYER_BASE", () => {
+	test("orders modal under anchored under toast, all above the sheet engine's 1-up stamps", () => {
+		expect(OVERLAY_LAYER_BASE.modal).toBeGreaterThanOrEqual(1000);
+		expect(OVERLAY_LAYER_BASE.anchored).toBeGreaterThan(OVERLAY_LAYER_BASE.modal);
+		expect(OVERLAY_LAYER_BASE.toast).toBeGreaterThan(OVERLAY_LAYER_BASE.anchored);
+	});
+});
+
+describe("reduceOverlayRegistry", () => {
+	test("an open overlay draws above its layer's base", () => {
+		const state = apply({ type: "open", id: "a", layer: "modal" });
+		expect(zIndexOfOverlay(state, "a")).toBe(OVERLAY_LAYER_BASE.modal + 1);
+	});
+
+	test("a later open in the same layer draws above the earlier one", () => {
+		const state = apply({ type: "open", id: "a", layer: "modal" }, { type: "open", id: "b", layer: "modal" });
+		expect(zIndexOfOverlay(state, "b")).toBeGreaterThan(zIndexOfOverlay(state, "a"));
+	});
+
+	test("the layer wins over open order", () => {
+		const state = apply({ type: "open", id: "toast", layer: "toast" }, { type: "open", id: "dialog", layer: "modal" });
+		expect(zIndexOfOverlay(state, "toast")).toBeGreaterThan(zIndexOfOverlay(state, "dialog"));
+	});
+
+	test("re-opening brings an overlay forward instead of duplicating it", () => {
+		const state = apply(
+			{ type: "open", id: "a", layer: "modal" },
+			{ type: "open", id: "b", layer: "modal" },
+			{ type: "open", id: "a", layer: "modal" }
+		);
+		expect(state.open.filter((entry) => entry.id === "a")).toHaveLength(1);
+		expect(zIndexOfOverlay(state, "a")).toBeGreaterThan(zIndexOfOverlay(state, "b"));
+	});
+
+	test("a z never leaves its layer's band, however many opens came before", () => {
+		let state = INITIAL_OVERLAY_REGISTRY;
+		for (let i = 0; i < 5000; i++) {
+			state = reduceOverlayRegistry(state, { type: "open", id: `m${i}`, layer: "modal" });
+			state = reduceOverlayRegistry(state, { type: "close", id: `m${i}` });
+		}
+		state = reduceOverlayRegistry(state, { type: "open", id: "last", layer: "modal" });
+		expect(zIndexOfOverlay(state, "last")).toBeLessThan(OVERLAY_LAYER_BASE.anchored);
+	});
+
+	test("closing an overlay that is not open returns the same state", () => {
+		const state = apply({ type: "open", id: "a", layer: "modal" });
+		expect(reduceOverlayRegistry(state, { type: "close", id: "nope" })).toBe(state);
+	});
+
+	test("a closed overlay has no z", () => {
+		const state = apply({ type: "open", id: "a", layer: "modal" }, { type: "close", id: "a" });
+		expect(zIndexOfOverlay(state, "a")).toBe(0);
+	});
+});
+
+describe("topOverlay / isTopOverlay", () => {
+	test("is null with nothing open", () => {
+		expect(topOverlay(INITIAL_OVERLAY_REGISTRY)).toBeNull();
+	});
+
+	test("an anchored overlay over a dialog is the top", () => {
+		const state = apply({ type: "open", id: "dialog", layer: "modal" }, { type: "open", id: "pop", layer: "anchored" });
+		expect(topOverlay(state)).toBe("pop");
+		expect(isTopOverlay(state, "dialog")).toBe(false);
+	});
+
+	test("a toast never captures the back button", () => {
+		const state = apply({ type: "open", id: "dialog", layer: "modal" }, { type: "open", id: "toast", layer: "toast" });
+		expect(topOverlay(state)).toBe("dialog");
+		expect(isTopOverlay(state, "toast")).toBe(false);
+	});
+
+	test("closing the top hands it to the one beneath", () => {
+		const state = apply(
+			{ type: "open", id: "a", layer: "modal" },
+			{ type: "open", id: "b", layer: "modal" },
+			{ type: "close", id: "b" }
+		);
+		expect(isTopOverlay(state, "a")).toBe(true);
+	});
+});

package/src/components/overlay/overlay-registry.ts

@@ -0,0 +1,99 @@
+/** The band of the z-order an overlay draws in. */
+export type OverlayLayer = "modal" | "anchored" | "toast";
+
+export const OVERLAY_LAYERS = ["modal", "anchored", "toast"] as const satisfies readonly OverlayLayer[];
+
+/**
+ * Where each layer's band starts.
+ *
+ * Every overlay and every bottom sheet teleports into the same `"root"` host, so
+ * they are siblings ordered by `zIndex`. The sheet engine stamps its sheets from
+ * 1 upward; starting the first band at 1000 puts every overlay above every sheet.
+ * A dialog sits under a popover opened from it, and a toast sits above both.
+ */
+export const OVERLAY_LAYER_BASE = {
+	modal: 1000,
+	anchored: 2000,
+	toast: 3000,
+} as const satisfies Record<OverlayLayer, number>;
+
+/** The layers whose top overlay answers Android's back button. A toast never does. */
+const BACK_CAPTURING_LAYERS: ReadonlySet<OverlayLayer> = new Set(["modal", "anchored"]);
+
+/** One overlay that is presented — open, or animating closed. */
+export type OverlayRegistryEntry = {
+	id: string;
+	layer: OverlayLayer;
+	/** Open order across every layer; later is larger. */
+	seq: number;
+};
+
+export type OverlayRegistryState = {
+	nextSeq: number;
+	open: readonly OverlayRegistryEntry[];
+};
+
+export const INITIAL_OVERLAY_REGISTRY: OverlayRegistryState = { nextSeq: 1, open: [] };
+
+export type OverlayRegistryAction = { type: "open"; id: string; layer: OverlayLayer } | { type: "close"; id: string };
+
+/**
+ * The registry as a pure reducer, so the z-order is testable without a renderer.
+ *
+ * An `open` stamps the next sequence number; an overlay already open is
+ * re-stamped rather than duplicated, which brings it forward. A `close` of an
+ * overlay that is not open returns the same state object, so an unmount racing
+ * an exit causes no render.
+ */
+export function reduceOverlayRegistry(
+	state: OverlayRegistryState,
+	action: OverlayRegistryAction
+): OverlayRegistryState {
+	if (action.type === "close") {
+		if (!state.open.some((entry) => entry.id === action.id)) return state;
+		return { ...state, open: state.open.filter((entry) => entry.id !== action.id) };
+	}
+
+	const others = state.open.filter((entry) => entry.id !== action.id);
+	return {
+		nextSeq: state.nextSeq + 1,
+		open: [...others, { id: action.id, layer: action.layer, seq: state.nextSeq }],
+	};
+}
+
+/**
+ * The overlay's `zIndex` while presented, `0` otherwise.
+ *
+ * Its layer's base plus its rank among the open overlays of that layer — a rank,
+ * not the raw sequence number, so a long session's thousandth dialog still sits
+ * below the first popover.
+ */
+export function zIndexOfOverlay(state: OverlayRegistryState, id: string): number {
+	const entry = state.open.find((candidate) => candidate.id === id);
+	if (entry === undefined) return 0;
+	let rank = 1;
+	for (const other of state.open) {
+		if (other.layer === entry.layer && other.seq < entry.seq) rank++;
+	}
+	return OVERLAY_LAYER_BASE[entry.layer] + rank;
+}
+
+/** The back-capturing overlay drawn on top, or `null` when none is presented. */
+export function topOverlay(state: OverlayRegistryState): string | null {
+	let top: string | null = null;
+	let topZ = 0;
+	for (const entry of state.open) {
+		if (!BACK_CAPTURING_LAYERS.has(entry.layer)) continue;
+		const z = zIndexOfOverlay(state, entry.id);
+		if (z > topZ) {
+			top = entry.id;
+			topZ = z;
+		}
+	}
+	return top;
+}
+
+/** Whether `id` is the overlay a back press should close. */
+export function isTopOverlay(state: OverlayRegistryState, id: string): boolean {
+	return topOverlay(state) === id;
+}

package/src/components/overlay/overlay-scrim.tsx

@@ -0,0 +1,49 @@
+import type { ReactElement } from "react";
+import { Pressable, type PressableProps } from "react-native";
+import Animated, { type SharedValue, useAnimatedStyle } from "react-native-reanimated";
+import { overlayVariants } from "./overlay.variants";
+
+const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
+
+export type OverlayScrimProps = Omit<PressableProps, "style" | "children" | "onPress"> & {
+	/** The 0 → 1 presence progress from `useOverlayPresence`; the scrim's opacity follows it. */
+	progress: SharedValue<number>;
+	/**
+	 * Called on a tap. Omit it and the scrim still takes the touch — the app
+	 * under a non-dismissible overlay must not be pressable — but does nothing.
+	 */
+	onDismiss?: () => void;
+	className?: string;
+};
+
+/**
+ * The dim layer between the app and a modal overlay.
+ *
+ * `bg-overlay` at opacity 1 — the token carries its own alpha — faded in and
+ * out by presence. Written before the panel in the same portal, so view order
+ * gives a touch on the panel to the panel.
+ *
+ * Invisible to assistive technology. A scrim is not a control a screen reader
+ * user can find; they dismiss through the panel's `onAccessibilityEscape` and
+ * the back button instead.
+ *
+ * React Native's own `Pressable`, not this library's: it needs no feedback, no
+ * haptic and no gesture handler — a gesture-handler tap here would race the
+ * panel's own pans for the touch.
+ */
+export function OverlayScrim({ progress, onDismiss, className, ...props }: OverlayScrimProps): ReactElement {
+	const fade = useAnimatedStyle(() => ({ opacity: progress.value }));
+
+	return (
+		<AnimatedPressable
+			accessibilityElementsHidden
+			accessible={false}
+			className={overlayVariants().scrim({ className })}
+			importantForAccessibility="no-hide-descendants"
+			onPress={onDismiss}
+			style={fade}
+			{...props}
+		/>
+	);
+}
+OverlayScrim.displayName = "DelacourUI.Overlay.Scrim";

package/src/components/overlay/overlay.context.tsx

@@ -0,0 +1,48 @@
+import { createContext, useContext } from "react";
+import type { OverlayLayer, OverlayRegistryState } from "./overlay-registry";
+
+/** What `OverlayProvider` shares with every overlay beneath it. */
+export type OverlayContextValue = {
+	/** The open set and its z-order. A change re-renders every presented portal. */
+	state: OverlayRegistryState;
+	/** A portal reports that its overlay is presented, and in which layer. */
+	present: (id: string, layer: OverlayLayer) => void;
+	/** The overlay's portal unmounted. */
+	dismissed: (id: string) => void;
+	/**
+	 * Hear every touch that starts anywhere under the provider — the app, a
+	 * sheet, another overlay — without taking it. A non-modal overlay closes on
+	 * an outside tap this way and the tap still reaches what was under it.
+	 * Returns the unsubscribe.
+	 */
+	subscribeTouchStart: (listener: () => void) => () => void;
+};
+
+export const OverlayContext = createContext<OverlayContextValue | null>(null);
+OverlayContext.displayName = "DelacourUI.Overlay.Context";
+
+/** The overlay registry, or `null` outside an `OverlayProvider`. */
+export function useOptionalOverlay(): OverlayContextValue | null {
+	return useContext(OverlayContext);
+}
+
+/**
+ * Whether a teleport `PortalProvider` is already mounted above.
+ *
+ * Teleport registers its hosts natively by name, so two providers would mean
+ * two hosts called `"root"`. `OverlayProvider` and this library's
+ * `BottomSheetProvider` both set this when they mount one, and both skip
+ * their own when it is already set — which is what makes either mount order
+ * work.
+ *
+ * This file is a leaf on purpose: `bottom-sheet/` imports it across folders,
+ * and it imports nothing but React and types, so the import can never close a
+ * cycle (package rule 3).
+ */
+export const TeleportProvidedContext = createContext(false);
+TeleportProvidedContext.displayName = "DelacourUI.Overlay.TeleportProvided";
+
+/** True beneath a provider that mounted teleport's `PortalProvider`. */
+export function useIsTeleportProvided(): boolean {
+	return useContext(TeleportProvidedContext);
+}

package/src/components/overlay/overlay.tsx

@@ -0,0 +1,118 @@
+import { type ReactElement, type ReactNode, useCallback, useMemo, useRef, useState } from "react";
+import { StyleSheet, View } from "react-native";
+import { PortalProvider } from "react-native-teleport";
+import {
+	OverlayContext,
+	type OverlayContextValue,
+	TeleportProvidedContext,
+	useIsTeleportProvided,
+} from "./overlay.context";
+import { OverlayPortal } from "./overlay-portal";
+import {
+	INITIAL_OVERLAY_REGISTRY,
+	type OverlayLayer,
+	type OverlayRegistryState,
+	reduceOverlayRegistry,
+} from "./overlay-registry";
+import { OverlayScrim } from "./overlay-scrim";
+
+export type OverlayProviderProps = {
+	children?: ReactNode;
+};
+
+function OverlayRoot({ children }: OverlayProviderProps): ReactElement {
+	const isTeleportProvided = useIsTeleportProvided();
+	const current = useRef<OverlayRegistryState>(INITIAL_OVERLAY_REGISTRY);
+	const [state, setState] = useState<OverlayRegistryState>(INITIAL_OVERLAY_REGISTRY);
+
+	const present = useCallback((id: string, layer: OverlayLayer) => {
+		current.current = reduceOverlayRegistry(current.current, { type: "open", id, layer });
+		setState(current.current);
+	}, []);
+
+	const dismissed = useCallback((id: string) => {
+		const next = reduceOverlayRegistry(current.current, { type: "close", id });
+		if (next === current.current) return;
+		current.current = next;
+		setState(next);
+	}, []);
+
+	const touchListeners = useRef(new Set<() => void>());
+	const subscribeTouchStart = useCallback((listener: () => void) => {
+		touchListeners.current.add(listener);
+		return () => {
+			touchListeners.current.delete(listener);
+		};
+	}, []);
+	const onTouchStart = useCallback(() => {
+		for (const listener of [...touchListeners.current]) listener();
+	}, []);
+
+	const value = useMemo<OverlayContextValue>(
+		() => ({ state, present, dismissed, subscribeTouchStart }),
+		[state, present, dismissed, subscribeTouchStart]
+	);
+
+	// `onTouchStart` is a bubbling touch event, not a responder claim: it fires
+	// for a touch on any descendant in the React tree — teleported overlays
+	// included, since teleport leaves the fiber where it was — and never stops
+	// the touch reaching its target or a gesture handler.
+	const registry = (
+		<OverlayContext.Provider value={value}>
+			<View onTouchStart={onTouchStart} style={styles.fill}>
+				{children}
+			</View>
+		</OverlayContext.Provider>
+	);
+	if (isTeleportProvided) return registry;
+
+	return (
+		<PortalProvider>
+			<TeleportProvidedContext.Provider value>{registry}</TeleportProvidedContext.Provider>
+		</PortalProvider>
+	);
+}
+
+const styles = StyleSheet.create({ fill: { flex: 1 } });
+
+/**
+ * The layer every overlay in this library draws into. Mount it once, inside
+ * `DelacourProvider` and around the navigator — and around
+ * `BottomSheetProvider` when the app has sheets.
+ *
+ * Two things. Teleport's `PortalProvider`, whose `"root"` host fills the app
+ * and is where every dialog, drawer, popover, tooltip, toast and sheet draws —
+ * skipped when a provider above already mounted one, because two would mean
+ * two native hosts with one name. And the overlay registry, which gives every
+ * presented overlay a `zIndex` in its layer's band and tells each one whether it
+ * is the top, the one Android's back button closes. It also hears every touch
+ * that starts beneath it, without claiming one, so a tooltip can close on an
+ * outside tap that still lands where it was aimed.
+ *
+ * `DelacourProvider` cannot mount this, for the reason it cannot mount
+ * `BottomSheetProvider`: `react-native-teleport` is an optional peer, and an
+ * import there would make every app resolve it.
+ *
+ * `OverlayProvider` is the same component under the name a root layout reads
+ * best with; `Overlay.Portal` and `Overlay.Scrim` are the parts every overlay
+ * is drawn with.
+ *
+ * @example
+ * <DelacourProvider>
+ *   <OverlayProvider>
+ *     <BottomSheetProvider>
+ *       <Stack />
+ *     </BottomSheetProvider>
+ *   </OverlayProvider>
+ * </DelacourProvider>
+ */
+export const Overlay = Object.assign(OverlayRoot, {
+	/** Teleports its children over the app, in a layer of the z-order. */
+	Portal: OverlayPortal,
+	/** The dim layer under a modal overlay, faded by presence. */
+	Scrim: OverlayScrim,
+	displayName: "DelacourUI.Overlay",
+});
+
+/** `Overlay` under the name a root layout reads best with. */
+export const OverlayProvider = Overlay;

package/src/components/overlay/overlay.variants.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { declaredTokens } from "../../styles/theme-tokens.test";
+import { OVERLAY_MOTION, OVERLAY_SCRIM_TOKEN, overlayVariants } from "./overlay.variants";
+
+const LIGHT = declaredTokens("light");
+const DARK = declaredTokens("dark");
+
+describe("overlayVariants", () => {
+	test("the scrim fills its parent in the overlay token", () => {
+		const scrim = overlayVariants().scrim();
+		expect(scrim).toContain("absolute");
+		expect(scrim).toContain("inset-0");
+		expect(scrim).toContain(`bg-${OVERLAY_SCRIM_TOKEN}`);
+	});
+
+	test("a caller's className reaches the scrim and wins", () => {
+		expect(overlayVariants().scrim({ className: "bg-black/30" })).toContain("bg-black/30");
+		expect(overlayVariants().scrim({ className: "bg-black/30" })).not.toContain(`bg-${OVERLAY_SCRIM_TOKEN}`);
+	});
+
+	test("the scrim token exists in both themes", () => {
+		expect(LIGHT.has(OVERLAY_SCRIM_TOKEN)).toBe(true);
+		expect(DARK.has(OVERLAY_SCRIM_TOKEN)).toBe(true);
+	});
+});
+
+describe("OVERLAY_MOTION", () => {
+	test("is finite, so an E2E runner's settle wait always ends", () => {
+		expect(Number.isFinite(OVERLAY_MOTION.enterMs)).toBe(true);
+		expect(Number.isFinite(OVERLAY_MOTION.exitMs)).toBe(true);
+	});
+
+	test("leaves faster than it arrives", () => {
+		expect(OVERLAY_MOTION.exitMs).toBeLessThan(OVERLAY_MOTION.enterMs);
+		expect(OVERLAY_MOTION.exitMs).toBeGreaterThan(0);
+	});
+});

package/src/components/overlay/overlay.variants.ts

@@ -0,0 +1,33 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+
+/**
+ * The theme token every overlay's scrim paints with.
+ *
+ * `--overlay` carries its own alpha, and the two themes carry different ones,
+ * so a scrim draws it at opacity 1 and fades only through presence — the same
+ * rule `BottomSheet.Overlay` follows.
+ */
+export const OVERLAY_SCRIM_TOKEN = "overlay";
+
+/**
+ * How long an overlay takes to arrive and to leave, in milliseconds.
+ *
+ * Leaving is quicker than arriving: an overlay the user dismissed should get
+ * out of the way. Both are finite on purpose — overlay motion is behaviour, not
+ * decoration, so `isMotionCalm` does not still it, and a finite animation is
+ * what lets an E2E runner's settle wait end anyway.
+ */
+export const OVERLAY_MOTION = {
+	enterMs: 220,
+	exitMs: 160,
+} as const;
+
+/** Styling for the foundation's own parts. */
+export const overlayVariants = tv({
+	slots: {
+		scrim: "absolute inset-0 bg-overlay",
+	},
+});
+
+export type OverlayVariantProps = VariantProps<typeof overlayVariants>;

package/src/components/overlay/use-overlay-back-handler.ts

@@ -0,0 +1,34 @@
+import { useEffect } from "react";
+import { BackHandler } from "react-native";
+import { useOptionalOverlay } from "./overlay.context";
+import { isTopOverlay } from "./overlay-registry";
+
+export type UseOverlayBackHandlerOptions = {
+	/** The id the overlay's `Overlay.Portal` was given. */
+	id: string;
+	/** Listen only while true — typically `isPresent && isDismissible`. */
+	isEnabled: boolean;
+	onBack: () => void;
+};
+
+/**
+ * Closes the overlay on Android's back button, but only while it is the top
+ * one: a popover over a dialog closes, the dialog under it stays.
+ *
+ * Without an `OverlayProvider` every overlay is its own top. React Native calls
+ * the most recently added listener first, and an overlay drawn over a bottom
+ * sheet subscribed after it, so the overlay answers before the sheet does.
+ */
+export function useOverlayBackHandler({ id, isEnabled, onBack }: UseOverlayBackHandlerOptions): void {
+	const registry = useOptionalOverlay();
+	const isTop = registry === null ? true : isTopOverlay(registry.state, id);
+
+	useEffect(() => {
+		if (!isEnabled || !isTop) return;
+		const subscription = BackHandler.addEventListener("hardwareBackPress", () => {
+			onBack();
+			return true;
+		});
+		return () => subscription.remove();
+	}, [isEnabled, isTop, onBack]);
+}

package/src/components/overlay/use-overlay-presence.ts

@@ -0,0 +1,87 @@
+import { useCallback, useEffect, useState } from "react";
+import { Easing, type SharedValue, useReducedMotion, useSharedValue, withTiming } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { OVERLAY_MOTION } from "./overlay.variants";
+import { isPresent, type PresenceEvent, type PresencePhase, presenceTarget, reducePresence } from "./overlay-presence";
+
+export type UseOverlayPresenceOptions = {
+	isOpen: boolean;
+	/** Entrance duration, ms. Default `OVERLAY_MOTION.enterMs`. */
+	enterMs?: number;
+	/** Exit duration, ms. Default `OVERLAY_MOTION.exitMs`. */
+	exitMs?: number;
+	/** The entrance finished — the moment to move accessibility focus in. */
+	onEntered?: () => void;
+	/** The exit finished and the overlay is about to unmount. */
+	onExited?: () => void;
+};
+
+export type OverlayPresence = {
+	/** Keep the overlay mounted while true: from the open until the exit animation ends. */
+	isPresent: boolean;
+	/** 0 hidden → 1 shown, animated on the UI thread. Drive opacity and transforms from it. */
+	progress: SharedValue<number>;
+	/** Reduce motion is on: drop scales and translates, keep the fade. */
+	isReduced: boolean;
+	phase: PresencePhase;
+};
+
+const ENTER_EASING = Easing.out(Easing.cubic);
+const EXIT_EASING = Easing.in(Easing.cubic);
+
+/**
+ * Keeps an overlay mounted through its exit animation and drives its
+ * `progress` from 0 to 1 and back.
+ *
+ * `isOpen` is the owner's state; this follows it through `reducePresence`,
+ * which is what lets a re-open during the exit reverse smoothly from wherever
+ * the animation is. The finish of each animation reaches React through
+ * `scheduleOnRN`, and only when the animation ran to the end — an interrupted
+ * one reports nothing, and the reducer drops a stale finish anyway.
+ *
+ * Under reduce motion the fade still runs — an opacity change is not motion —
+ * and `isReduced` tells the component to drop its transforms.
+ */
+export function useOverlayPresence({
+	isOpen,
+	enterMs = OVERLAY_MOTION.enterMs,
+	exitMs = OVERLAY_MOTION.exitMs,
+	onEntered,
+	onExited,
+}: UseOverlayPresenceOptions): OverlayPresence {
+	const [phase, setPhase] = useState<PresencePhase>(isOpen ? "entering" : "closed");
+	const progress = useSharedValue(0);
+	const isReduced = useReducedMotion();
+
+	const send = useCallback((event: PresenceEvent) => {
+		setPhase((current) => reducePresence(current, event));
+	}, []);
+
+	const finishEnter = useCallback(() => {
+		send({ type: "entered" });
+		onEntered?.();
+	}, [send, onEntered]);
+
+	const finishExit = useCallback(() => {
+		send({ type: "exited" });
+		onExited?.();
+	}, [send, onExited]);
+
+	useEffect(() => {
+		send({ type: isOpen ? "open" : "close" });
+	}, [isOpen, send]);
+
+	useEffect(() => {
+		if (phase === "entering") {
+			progress.value = withTiming(presenceTarget(phase), { duration: enterMs, easing: ENTER_EASING }, (finished) => {
+				if (finished) scheduleOnRN(finishEnter);
+			});
+		} else if (phase === "exiting") {
+			progress.value = withTiming(presenceTarget(phase), { duration: exitMs, easing: EXIT_EASING }, (finished) => {
+				if (finished) scheduleOnRN(finishExit);
+			});
+		}
+	}, [phase, progress, enterMs, exitMs, finishEnter, finishExit]);
+
+	return { isPresent: isPresent(phase), progress, isReduced, phase };
+}