@delacour/react-native-bottom-sheet 0.1.0-alpha.0

package/src/no-classname.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { read, relative, SRC, sourceFiles } from "./source-tree.test";
+
+/**
+ * This package emits no `className`.
+ *
+ * That is the promise the engine/skin split rests on: radii, colours and
+ * spacing arrive as `style`, and `@delacour/react-native-ui` is the only place
+ * tokens exist. It also has a concrete consequence in the playground — Tailwind's
+ * scanner needs no `@source` line pointing here, because there is nothing to
+ * scan. A stray `className` would make that missing line a silent bug where a
+ * class compiles in development and vanishes from a release build.
+ *
+ * So the promise is checked rather than hoped for.
+ */
+describe("no className", () => {
+	const files = sourceFiles(SRC, { skipTests: true });
+
+	test("finds the source, so a broken walker cannot pass silently", () => {
+		expect(files.length).toBeGreaterThan(20);
+	});
+
+	test("no module names className", () => {
+		const offenders = files.filter((file) => read(file).includes("className")).map((file) => relative(file));
+		expect(offenders).toEqual([]);
+	});
+});

package/src/portal/AGENTS.md

@@ -0,0 +1,101 @@
+# portal
+
+Where a sheet draws, and who is on top: the provider, the host, the nearest-host
+context and the registry that `Portal` reads.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `bottom-sheet-provider.tsx` | `BottomSheetProvider` — teleport's `PortalProvider`, the registry provider and the host-name context set to `"root"`. The app mounts it once |
+| `bottom-sheet-host.tsx` | `BottomSheet.Host` — a teleport `PortalHost` (absolute fill, `box-none`) that provides its own name as the nearest one. The recipe for a native modal |
+| `host.context.tsx` | `BottomSheetHostNameContext` — the nearest host's name, `null` with no provider; `useBottomSheetHostName` / `useOptionalBottomSheetHostName` |
+| `sheet-registry.ts` | The pure reducer: `reduceRegistry`, `topOf`, `zIndexOf`, `isTop`, `INITIAL_REGISTRY`. Tested without a renderer |
+| `sheet-registry.test.ts` | Increasing z, re-open brings forward, `replace` closes the same host only, unknown close is the same state, top per host |
+| `sheet-registry.context.tsx` | `SheetRegistryProvider` (reducer state in React, the id → methods map) and `useBottomSheetRegistry() → { dismissAll, dismiss }` |
+
+`sheet-registry.ts` and `sheet-registry.context.tsx` are two files on purpose:
+`./sheet-registry` must resolve to the maths, and a `.ts` and a `.tsx` of one
+name would leave that to the bundler.
+
+## One implementation
+
+`BottomSheet.Portal` is one component with two destinations. With a
+`BottomSheetProvider` above it and no `inline`, the frame is written inside a
+teleport `Portal` bound to the nearest host — `"root"` under a bare provider,
+or the host a native modal screen wrote last, or the `hostName` prop. Teleport
+moves the **native** view and leaves the React tree where it was, so every
+context provided around the trigger — a theme, a form, a query client — still
+reaches the sheet's parts with nothing re-provided. Without a provider, or
+with `inline`, the frame renders where it is written.
+
+There is no `BottomSheetModal`, and no minimise/restore stack. A modal sheet is
+a sheet whose portal teleports, and that is the default.
+
+The teleport `Portal` wrapper is an absolute fill of the host with the
+registry's `zIndex`; the frame inside it is the same absolute fill, `box-none`,
+so a closed sheet takes no touch and the app under it stays interactive.
+Teleport's native `PortalView` hit-tests only its subviews, so the wrapper is
+transparent to touches too.
+
+## The registry
+
+A sheet is in the registry while it is **presented** — from the open that
+mounted its children to the settle at `-1` that unmounts them — under the host
+its portal chose. An inline sheet registers under a host of its own
+(`inline:<id>`), so nothing replaces it and it is always its own top.
+
+`reduceRegistry` stamps each open with the next `z`; the frame and the panel
+carry it as `zIndex`, and sheets in one host are siblings, so the later open
+draws on top. Opening a sheet already open re-stamps it, which brings it
+forward. `stackBehavior: "replace"` drops every other sheet in the same host
+and reports them; the provider calls each one's `close()`, they animate out,
+and their own settle finds nothing to remove.
+
+`useBottomSheetRegistry()` returns `dismissAll` and `dismiss(id)`; the root
+registers `{ close, forceClose }` under its `useId` on mount. Both throw
+outside the provider — there is nothing to ask without one — and the
+`useOptional` form returns `null`.
+
+`closeOnBack` subscribes to `BackHandler` only while the sheet is presented
+**and** `isTop` in its host, so a back press closes the top sheet and the one
+under it survives. Without a registry every sheet is its own top. iOS has no
+back button; the unit test on `isTop` is what stands in for the device check.
+
+## Hosts
+
+`BottomSheet.Host` is for the one place the root host cannot reach: a native
+modal. A `Modal`, or a screen a navigator presents as one, is its own window,
+and a sheet teleported to the root draws behind it. The host is written
+**last** in that screen so it is the topmost sibling, and it provides its own
+name as the nearest one, so every sheet written in the screen lands there
+without a `hostName`.
+
+A host needs the provider above it — teleport's `PortalHost` reads the
+provider's manager — and it must not be written inside a sheet: a sheet
+teleported into another sheet's panel is clipped by it and moves with it. Both
+warn in development.
+
+## Detached
+
+`detached` is resolved once by the root (`resolveDetached`) and handed to the
+parts through the internal context, next to the shared-value copy the geometry
+reads. `Container` derives `left` and `width` from `detachedFrame` on the UI
+thread, turns `overflow` visible so a card's shadow is not clipped, and is
+`box-none`, so a touch in the gap under the card falls through to the
+overlay. The frame is `overflow: visible` too. The overlay is unchanged — it
+fills the frame, margins and gap included, so a tap there closes. The rest is
+`core/`: `closedHeight` is `−restingBottom`, so closed is `translateY =
+containerHeight` and the card is fully off-screen; `%` detents resolve against
+the height above the resting line; `keyboardLift` subtracts the gap. The
+corners are the consumer's `Background` style.
+
+**The card moves as one rigid body.** The panel is as tall as the frame, so a
+detached `Background` is sized by the geometry's `surfaceHeight`
+(`core/geometry/surface-height.ts`): the sheet's `height` between its detents,
+the first detent's height below them and the last's above. A drag down to
+close, the close animation, a rubber-band under the lowest detent and an
+over-drag past the highest therefore leave the surface, the body and the
+footer exactly as they were and let `translateY` alone move the card, bottom
+corners included, through the gap and off the screen. `Content` clamps its
+body to `surfaceHeight − handleHeight` for the same reason.

package/src/portal/bottom-sheet-host.tsx

@@ -0,0 +1,67 @@
+import { type ReactElement, type ReactNode, useEffect } from "react";
+import { StyleSheet, type ViewProps } from "react-native";
+import { PortalHost } from "react-native-teleport";
+import { useOptionalBottomSheetInternal } from "../components/bottom-sheet.context";
+import { BottomSheetHostNameContext, useOptionalBottomSheetHostName } from "./host.context";
+
+export type BottomSheetHostProps = {
+	/** What a `Portal`'s `hostName` names. Unique across the mounted hosts. */
+	name: string;
+	style?: ViewProps["style"];
+	/**
+	 * The screen the host serves. A sheet written inside targets this host
+	 * without a `hostName`, and teleport draws every portal over the children,
+	 * so the host is the screen's outermost view. With no children it is an
+	 * absolute fill instead, written last in the screen, and a sheet elsewhere
+	 * in that screen names it with `hostName`.
+	 */
+	children?: ReactNode;
+};
+
+/**
+ * A place for sheets to teleport to, other than the app root.
+ *
+ * The recipe for a native modal: a `Modal`, or a navigator screen presented
+ * as one, is its own window, and a sheet teleported to the root host draws
+ * behind it. Write `<BottomSheet.Host name="modal" />` last in that screen
+ * and every sheet written in the screen lands there — the host provides its
+ * own name as the nearest one, so no `Portal` needs telling.
+ *
+ * An absolute fill that takes no touch of its own, so the screen under it
+ * stays interactive until a sheet opens over it.
+ *
+ * A host inside a sheet is a mistake this warns about in development: a
+ * sheet teleported into another sheet's panel is clipped by that panel and
+ * moves with it.
+ */
+export function BottomSheetHost({ name, style, children }: BottomSheetHostProps): ReactElement {
+	const insideSheet = useOptionalBottomSheetInternal() !== null;
+	const provided = useOptionalBottomSheetHostName() !== null;
+
+	useEffect(() => {
+		if (!__DEV__) return;
+		if (insideSheet) {
+			console.warn(
+				`[@delacour/react-native-bottom-sheet] <BottomSheet.Host name="${name}"> is rendered inside a sheet. A host belongs in a screen, written last; a sheet teleported into another sheet's panel is clipped by it.`
+			);
+		}
+		if (!provided) {
+			console.warn(
+				`[@delacour/react-native-bottom-sheet] <BottomSheet.Host name="${name}"> has no <BottomSheetProvider> above it. Mount the provider at the app root.`
+			);
+		}
+	}, [insideSheet, provided, name]);
+
+	return (
+		<BottomSheetHostNameContext.Provider value={name}>
+			<PortalHost name={name} style={[children === undefined ? StyleSheet.absoluteFill : styles.fill, style]}>
+				{children}
+			</PortalHost>
+		</BottomSheetHostNameContext.Provider>
+	);
+}
+BottomSheetHost.displayName = "DelacourBottomSheet.BottomSheet.Host";
+
+const styles = StyleSheet.create({
+	fill: { flex: 1 },
+});

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

@@ -0,0 +1,33 @@
+import type { ReactElement, ReactNode } from "react";
+import { PortalProvider } from "react-native-teleport";
+import { BottomSheetHostNameContext } from "./host.context";
+import { SheetRegistryProvider } from "./sheet-registry.context";
+
+export type BottomSheetProviderProps = {
+	children?: ReactNode;
+};
+
+/**
+ * The one provider this package renders, mounted once by the app — inside its
+ * gesture root and keyboard provider, around its navigator.
+ *
+ * Three things, in one: teleport's `PortalProvider`, which renders its
+ * children and then a `root` host that fills them, so a teleported sheet
+ * draws over the navigator and the tab bar; the sheet registry, which gives
+ * every presented sheet its place in the z-order and lets the app close them
+ * without a ref; and the host-name context, set to `"root"`, which is what
+ * makes a `Portal` written anywhere below teleport there without being told.
+ *
+ * Nothing else. `GestureHandlerRootView`, `SafeAreaProvider` and
+ * `KeyboardProvider` are the app's — see the package `AGENTS.md`.
+ */
+export function BottomSheetProvider({ children }: BottomSheetProviderProps): ReactElement {
+	return (
+		<PortalProvider>
+			<SheetRegistryProvider>
+				<BottomSheetHostNameContext.Provider value="root">{children}</BottomSheetHostNameContext.Provider>
+			</SheetRegistryProvider>
+		</PortalProvider>
+	);
+}
+BottomSheetProvider.displayName = "DelacourBottomSheet.BottomSheet.Provider";

package/src/portal/host.context.tsx

@@ -0,0 +1,25 @@
+import { createContext, useContext } from "react";
+
+/**
+ * The name of the nearest `BottomSheet.Host` above a sheet — `"root"` under a
+ * bare `BottomSheetProvider`, the host's own name under one written inside a
+ * native modal. A `Portal` with no `hostName` of its own teleports here.
+ *
+ * `null` means no provider at all, and a portal renders in place.
+ */
+export const BottomSheetHostNameContext = createContext<string | null>(null);
+BottomSheetHostNameContext.displayName = "DelacourBottomSheet.HostNameContext";
+
+export function useBottomSheetHostName(): string {
+	const value = useContext(BottomSheetHostNameContext);
+	if (value === null) {
+		throw new Error(
+			"[@delacour/react-native-bottom-sheet] useBottomSheetHostName outside <BottomSheetProvider>. Mount the provider at the app root."
+		);
+	}
+	return value;
+}
+
+export function useOptionalBottomSheetHostName(): string | null {
+	return useContext(BottomSheetHostNameContext);
+}

package/src/portal/sheet-registry.context.tsx

@@ -0,0 +1,124 @@
+import {
+	createContext,
+	type ReactElement,
+	type ReactNode,
+	useCallback,
+	useContext,
+	useMemo,
+	useRef,
+	useState,
+} from "react";
+import { INITIAL_REGISTRY, reduceRegistry, type SheetRegistryState, type StackBehavior } from "./sheet-registry";
+
+/** What a sheet hands the registry so it can be closed from outside. */
+export type SheetRegistryMethods = {
+	close: () => void;
+	forceClose: () => void;
+};
+
+export type SheetRegistryValue = {
+	/** The open set and its z-order. React state: a change re-renders every presented sheet's frame. */
+	state: SheetRegistryState;
+	/** A root registers its methods on mount; the cleanup unregisters. */
+	register: (id: string, methods: SheetRegistryMethods) => () => void;
+	/** A portal reports that its sheet is presented, in which host, and how it stacks. */
+	present: (id: string, host: string, behavior: StackBehavior) => void;
+	/** The sheet's close settled, or its portal unmounted. */
+	dismissed: (id: string) => void;
+	dismiss: (id: string) => void;
+	dismissAll: () => void;
+};
+
+export const SheetRegistryContext = createContext<SheetRegistryValue | null>(null);
+SheetRegistryContext.displayName = "DelacourBottomSheet.RegistryContext";
+
+export function useSheetRegistry(): SheetRegistryValue {
+	const value = useContext(SheetRegistryContext);
+	if (value === null) {
+		throw new Error(
+			"[@delacour/react-native-bottom-sheet] useSheetRegistry outside <BottomSheetProvider>. Mount the provider at the app root."
+		);
+	}
+	return value;
+}
+
+export function useOptionalSheetRegistry(): SheetRegistryValue | null {
+	return useContext(SheetRegistryContext);
+}
+
+/** What `useBottomSheetRegistry()` returns — the two things an app does to sheets it does not hold a ref to. */
+export type BottomSheetRegistryValue = {
+	/** Closes every presented sheet, in every host. */
+	dismissAll: () => void;
+	/** Closes one sheet by the id its root registered. Unknown ids are nothing. */
+	dismiss: (id: string) => void;
+};
+
+/**
+ * The app's handle on every open sheet. Throws outside `BottomSheetProvider`:
+ * there is no registry to ask without one.
+ */
+export function useBottomSheetRegistry(): BottomSheetRegistryValue {
+	const { dismissAll, dismiss } = useSheetRegistry();
+	return useMemo(() => ({ dismissAll, dismiss }), [dismissAll, dismiss]);
+}
+
+export function useOptionalBottomSheetRegistry(): BottomSheetRegistryValue | null {
+	const registry = useOptionalSheetRegistry();
+	return useMemo(
+		() => (registry === null ? null : { dismissAll: registry.dismissAll, dismiss: registry.dismiss }),
+		[registry]
+	);
+}
+
+/**
+ * Holds the registry: the pure reducer's state, mirrored into React state for
+ * the frames that read a `zIndex` from it, and a map from sheet id to the
+ * methods a root registered.
+ *
+ * The reducer runs against a ref and its result is then set, rather than
+ * inside a `setState` updater, because a `replace` open has a side effect —
+ * telling the displaced sheets to close — and an updater may run twice.
+ */
+export function SheetRegistryProvider({ children }: { children?: ReactNode }): ReactElement {
+	const current = useRef<SheetRegistryState>(INITIAL_REGISTRY);
+	const [state, setState] = useState<SheetRegistryState>(INITIAL_REGISTRY);
+	const methods = useRef(new Map<string, SheetRegistryMethods>());
+
+	const register = useCallback((id: string, sheet: SheetRegistryMethods) => {
+		methods.current.set(id, sheet);
+		return () => {
+			if (methods.current.get(id) === sheet) methods.current.delete(id);
+		};
+	}, []);
+
+	const present = useCallback((id: string, host: string, behavior: StackBehavior) => {
+		const result = reduceRegistry(current.current, { type: "open", id, host, behavior });
+		current.current = result.state;
+		setState(result.state);
+		for (const victim of result.closed) methods.current.get(victim)?.close();
+	}, []);
+
+	const dismissed = useCallback((id: string) => {
+		const result = reduceRegistry(current.current, { type: "close", id });
+		if (result.state === current.current) return;
+		current.current = result.state;
+		setState(result.state);
+	}, []);
+
+	const dismiss = useCallback((id: string) => {
+		methods.current.get(id)?.close();
+	}, []);
+
+	const dismissAll = useCallback(() => {
+		for (const entry of current.current.open) methods.current.get(entry.id)?.close();
+	}, []);
+
+	const value = useMemo<SheetRegistryValue>(
+		() => ({ state, register, present, dismissed, dismiss, dismissAll }),
+		[state, register, present, dismissed, dismiss, dismissAll]
+	);
+
+	return <SheetRegistryContext.Provider value={value}>{children}</SheetRegistryContext.Provider>;
+}
+SheetRegistryProvider.displayName = "DelacourBottomSheet.RegistryProvider";

package/src/portal/sheet-registry.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import { INITIAL_REGISTRY, isTop, reduceRegistry, type SheetRegistryState, topOf, zIndexOf } from "./sheet-registry";
+
+function open(state: SheetRegistryState, id: string, host = "root", behavior: "push" | "replace" = "push") {
+	return reduceRegistry(state, { type: "open", id, host, behavior });
+}
+
+describe("sheet registry", () => {
+	test("opening assigns increasing z, later on top", () => {
+		const a = open(INITIAL_REGISTRY, "a");
+		const b = open(a.state, "b");
+		expect(zIndexOf(b.state, "a")).toBeGreaterThan(0);
+		expect(zIndexOf(b.state, "b")).toBeGreaterThan(zIndexOf(b.state, "a"));
+		expect(topOf(b.state, "root")).toBe("b");
+	});
+
+	test("reopening a sheet already open brings it to the top", () => {
+		const a = open(INITIAL_REGISTRY, "a");
+		const b = open(a.state, "b");
+		const again = open(b.state, "a");
+		expect(topOf(again.state, "root")).toBe("a");
+		expect(again.state.open.filter((entry) => entry.id === "a")).toHaveLength(1);
+	});
+
+	test("push closes nothing", () => {
+		const a = open(INITIAL_REGISTRY, "a");
+		const b = open(a.state, "b");
+		expect(b.closed).toEqual([]);
+		expect(zIndexOf(b.state, "a")).toBeGreaterThan(0);
+	});
+
+	test("replace closes the other open sheets in the same host and reports them", () => {
+		const a = open(INITIAL_REGISTRY, "a");
+		const b = open(a.state, "b");
+		const c = open(b.state, "c", "root", "replace");
+		expect([...c.closed].sort()).toEqual(["a", "b"]);
+		expect(zIndexOf(c.state, "a")).toBe(0);
+		expect(zIndexOf(c.state, "b")).toBe(0);
+		expect(topOf(c.state, "root")).toBe("c");
+	});
+
+	test("replace leaves sheets in another host alone", () => {
+		const a = open(INITIAL_REGISTRY, "a", "modal");
+		const b = open(a.state, "b", "root", "replace");
+		expect(b.closed).toEqual([]);
+		expect(topOf(b.state, "modal")).toBe("a");
+		expect(topOf(b.state, "root")).toBe("b");
+	});
+
+	test("closing removes the entry and the next one down is top", () => {
+		const a = open(INITIAL_REGISTRY, "a");
+		const b = open(a.state, "b");
+		const closed = reduceRegistry(b.state, { type: "close", id: "b" });
+		expect(topOf(closed.state, "root")).toBe("a");
+		expect(zIndexOf(closed.state, "b")).toBe(0);
+	});
+
+	test("closing an unknown sheet returns the same state", () => {
+		const a = open(INITIAL_REGISTRY, "a");
+		const closed = reduceRegistry(a.state, { type: "close", id: "nope" });
+		expect(closed.state).toBe(a.state);
+		expect(closed.closed).toEqual([]);
+	});
+
+	test("top of an empty host is null; z of a closed sheet is zero", () => {
+		expect(topOf(INITIAL_REGISTRY, "root")).toBeNull();
+		expect(zIndexOf(INITIAL_REGISTRY, "a")).toBe(0);
+	});
+
+	test("z never reuses a number after a close", () => {
+		const a = open(INITIAL_REGISTRY, "a");
+		const zA = zIndexOf(a.state, "a");
+		const closed = reduceRegistry(a.state, { type: "close", id: "a" });
+		const b = open(closed.state, "b");
+		expect(zIndexOf(b.state, "b")).toBeGreaterThan(zA);
+	});
+
+	test("isTop is true only for the topmost sheet of its own host", () => {
+		const a = open(INITIAL_REGISTRY, "a");
+		const b = open(a.state, "b");
+		const m = open(b.state, "m", "modal");
+		expect(isTop(m.state, "a")).toBe(false);
+		expect(isTop(m.state, "b")).toBe(true);
+		expect(isTop(m.state, "m")).toBe(true);
+		expect(isTop(m.state, "nope")).toBe(false);
+	});
+});

package/src/portal/sheet-registry.ts

@@ -0,0 +1,78 @@
+/** One sheet that is currently presented — open, or on its way closed. */
+export type SheetRegistryEntry = {
+	id: string;
+	/** The host the sheet's frame lives in; `replace` and `top` are scoped to it. */
+	host: string;
+	/** Later opens get larger numbers, so the sibling order in a host is the open order. */
+	z: number;
+};
+
+export type SheetRegistryState = {
+	nextZ: number;
+	open: readonly SheetRegistryEntry[];
+};
+
+export const INITIAL_REGISTRY: SheetRegistryState = { nextZ: 1, open: [] };
+
+export type StackBehavior = "push" | "replace";
+
+export type SheetRegistryAction =
+	| { type: "open"; id: string; host: string; behavior: StackBehavior }
+	| { type: "close"; id: string };
+
+export type SheetRegistryResult = {
+	state: SheetRegistryState;
+	/** Sheets the action displaced: a `replace` open's victims. The provider tells each to close. */
+	closed: readonly string[];
+};
+
+/**
+ * The registry as a pure reducer over plain data, so the z-order, `replace` and
+ * `dismissAll` are testable without a renderer.
+ *
+ * An `open` stamps the next `z` and puts the sheet on top of its host; a sheet
+ * already open is re-stamped rather than duplicated, so re-presenting brings
+ * it forward. With `replace`, every other sheet in the same host is dropped
+ * and reported in `closed` — the provider calls their `close()`, and their
+ * own settle at `-1` is then a no-op here. A `close` of a sheet that is not
+ * open returns the same state object, so a settle that races an unmount
+ * causes no render.
+ */
+export function reduceRegistry(state: SheetRegistryState, action: SheetRegistryAction): SheetRegistryResult {
+	if (action.type === "close") {
+		if (!state.open.some((entry) => entry.id === action.id)) return { state, closed: [] };
+		return { state: { ...state, open: state.open.filter((entry) => entry.id !== action.id) }, closed: [] };
+	}
+
+	const others = state.open.filter((entry) => entry.id !== action.id);
+	const displaced = action.behavior === "replace" ? others.filter((entry) => entry.host === action.host) : [];
+	const kept = displaced.length === 0 ? others : others.filter((entry) => entry.host !== action.host);
+	const entry: SheetRegistryEntry = { id: action.id, host: action.host, z: state.nextZ };
+	return {
+		state: { nextZ: state.nextZ + 1, open: [...kept, entry] },
+		closed: displaced.map((victim) => victim.id),
+	};
+}
+
+/** The sheet drawn on top in `host`, or `null` when nothing is presented there. */
+export function topOf(state: SheetRegistryState, host: string): string | null {
+	let top: SheetRegistryEntry | null = null;
+	for (const entry of state.open) {
+		if (entry.host !== host) continue;
+		if (top === null || entry.z > top.z) top = entry;
+	}
+	return top === null ? null : top.id;
+}
+
+/** The sheet's `zIndex` while presented, `0` otherwise. */
+export function zIndexOf(state: SheetRegistryState, id: string): number {
+	const entry = state.open.find((candidate) => candidate.id === id);
+	return entry === undefined ? 0 : entry.z;
+}
+
+/** Whether `id` is the sheet on top of its own host — the one a back press should close. */
+export function isTop(state: SheetRegistryState, id: string): boolean {
+	const entry = state.open.find((candidate) => candidate.id === id);
+	if (entry === undefined) return false;
+	return topOf(state, entry.host) === id;
+}

package/src/purity.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "bun:test";
+import { dirname, join, resolve } from "node:path";
+import { read, relative, SRC, sourceFiles } from "./source-tree.test";
+
+/**
+ * Modules `src/core` may not import a runtime value from.
+ *
+ * React Native ships Flow-typed source that Bun's transpiler cannot parse, so
+ * one of these anywhere under `core/` takes the *entire* suite down — and the
+ * error names whichever file happened to import the offender first, not the
+ * file that broke the rule. Hence this test: it fails first, and it fails by
+ * name.
+ *
+ * Type-only imports are fine. Types are erased before Bun sees them.
+ */
+const FORBIDDEN = [
+	"react",
+	"react-native",
+	"react-dom",
+	"react-native-reanimated",
+	"react-native-gesture-handler",
+	"react-native-worklets",
+	"react-native-keyboard-controller",
+	"react-native-safe-area-context",
+	"react-native-teleport",
+	"react-native-pulsar",
+];
+
+const IMPORT = /^\s*import\s+([\s\S]*?)\s*from\s*["']([^"']+)["']/gm;
+
+/** Whether an import clause brings in nothing but types. */
+function isTypeOnly(clause: string): boolean {
+	const trimmed = clause.trim();
+	if (trimmed.startsWith("type ")) return true;
+
+	const named = trimmed.match(/^\{([\s\S]*)\}$/);
+	if (!named) return false;
+
+	return (named[1] as string)
+		.split(",")
+		.map((specifier) => specifier.trim())
+		.filter((specifier) => specifier !== "")
+		.every((specifier) => specifier.startsWith("type "));
+}
+
+describe("core purity", () => {
+	const files = sourceFiles(join(SRC, "core"));
+
+	test("finds the core modules, so a broken walker cannot pass silently", () => {
+		expect(files.length).toBeGreaterThan(20);
+	});
+
+	test("no module under src/core imports a React Native runtime value", () => {
+		const offenders: string[] = [];
+
+		for (const file of files) {
+			const source = read(file);
+			IMPORT.lastIndex = 0;
+			for (let match = IMPORT.exec(source); match !== null; match = IMPORT.exec(source)) {
+				const clause = match[1] as string;
+				const specifier = match[2] as string;
+				const root = specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
+				if (!FORBIDDEN.includes(root as string)) continue;
+				if (isTypeOnly(clause)) continue;
+				offenders.push(`${relative(file)} imports ${specifier}`);
+			}
+		}
+
+		expect(offenders).toEqual([]);
+	});
+
+	// `core/` is the bottom of the package. A relative import that resolves
+	// outside it would pull a hook, a component or a native module into the
+	// maths — and into `bun test`.
+	test("no module under src/core reaches sideways or upward out of core", () => {
+		const core = join(SRC, "core");
+		const offenders: string[] = [];
+		for (const file of files) {
+			const source = read(file);
+			IMPORT.lastIndex = 0;
+			for (let match = IMPORT.exec(source); match !== null; match = IMPORT.exec(source)) {
+				const specifier = match[2] as string;
+				if (!specifier.startsWith(".")) continue;
+				const target = resolve(dirname(file), specifier);
+				if (!target.startsWith(`${core}/`)) offenders.push(`${relative(file)} imports ${specifier}`);
+			}
+		}
+		expect(offenders).toEqual([]);
+	});
+});