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

package/src/scrollable/AGENTS.md

@@ -0,0 +1,123 @@
+# scrollable
+
+A `ScrollView`, `FlatList` or `SectionList` as the sheet's body, and the
+factory that makes one out of any animated scrollable.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `scrollable.types.ts` | `BottomSheetScrollableProps` (`focusHook`), `FocusHook`, `ScrollableHandle`, the inner shape the wrapper is written against, and the restated generic component types |
+| `create-bottom-sheet-scrollable.tsx` | `createBottomSheetScrollable(AnimatedComponent, type)` — the two detectors, the lock, the clip and the clamp, the trailing spacer, content size, registration |
+| `bottom-sheet-scroll-view.tsx` | `BottomSheet.ScrollView` over `Animated.ScrollView` |
+| `bottom-sheet-flat-list.tsx` | `BottomSheet.FlatList` over `Animated.FlatList`, generic in `ItemT` |
+| `bottom-sheet-section-list.tsx` | `BottomSheet.SectionList` over a module-scope `createAnimatedComponent(SectionList)`, generic in `ItemT, SectionT` |
+
+The UI-thread half — the scroll handler, the lock reaction and the animated
+props — is `gesture/use-scroll-lock.ts`, beside the pan it cooperates with.
+The numbers are `core/scroll/`: `shouldLockScroll`, `listDragHeight`,
+`listOwnsRelease`, `scrollLockTarget`.
+
+## How a list and the sheet share a finger
+
+The content pan and the list's native scroll are **simultaneous**: the list's
+`Native` gesture is declared `simultaneousWithExternalGesture(pans.content)`,
+so both see every touch. The rule for who moves is the sheet's state:
+
+- **Below the highest detent — locked.** Every scroll event is answered with
+  `scrollTo(ref, 0, scrollLockedAt, false)` and the offset the pan reads is
+  pinned there, so the list consumes nothing and the pan moves the sheet. The
+  indicator is hidden, `bounces` is off and `decelerationRate` is `0`, so a
+  fling has no momentum for the lock to fight.
+- **At the highest detent — unlocked.** The list scrolls. The pan treats the
+  offset the list *began* the gesture with as a budget the finger spends
+  downward before the sheet moves (`listDragHeight`): the list scrolls
+  one-for-one under the same finger, so it reaches its top exactly as the
+  budget runs out and the sheet takes over from there. Upward, the clamp at
+  `highest` means the list scrolls and bounces rather than the sheet
+  over-dragging.
+- **A release while scrolled at the top** belongs to the list
+  (`listOwnsRelease`): the velocity is the list's momentum, not a snap. The
+  library this replaces snapped here and hopped a detent under interrupted
+  scrolls.
+
+The budget is the offset at the *start* of the gesture, never the live one.
+The live offset was tried first: the pan and the scroll event for one touch
+move land in the same frame in no fixed order, and when the pan ran first the
+sheet dipped a pixel, the lock engaged and the list froze where it was. A
+fixed budget cannot race anything. A list held by the lock — scrolled, and
+below the top — has no budget until the sheet reaches the top this gesture
+(`listHeld` in `use-sheet-pan.ts`), the previous engine's
+`isScrollablePositionLocked` under another name.
+
+The lock's target is taken when the lock engages, by any path — a drag, a
+`snapToIndex`, a keyboard — as `max(0, offset)`. A pull-down from the top
+locks at `0`; a handle drag on a scrolled list holds the rows where they are.
+
+## Sizing
+
+The list fills the body to the sheet's bottom line: its `maxHeight` follows
+`contentArea + bodyInset` on the UI thread, exactly as `Content`'s layout box
+does. What the footer or the safe-area band would cover is reserved *inside*
+the content, as a trailing spacer — appended to a `ScrollView`'s children,
+composed after the consumer's `ListFooterComponent` on a `FlatList` or
+`SectionList` — the height of the geometry's `bodyInset`, so the rows scroll
+under the footer or the band and the last row can still be brought fully clear
+of them. The spacer is animated because the band collapses as the keyboard
+rises, and `contentContainerStyle` cannot be; `scrollIndicatorInsets.bottom`
+follows the same value through the lock's `animatedProps`, so the indicator
+ends where the rows stop being visible. The outer view clips to `bodyClip`,
+which under a footer is the footer's live top edge.
+
+The list must not shrink to that clip. A React Native scrollable ships
+`flexShrink: 1`, and Yoga shrank it to the wrapper — the footer's top — so
+the spacer's clearance landed on top of the wrapper's and the last row stopped
+a whole footer above the footer. `flexShrink: 0` on the list leaves
+`maxHeight` as its only bound. A `marginBottom` of the footer's height was the
+earlier answer and is gone: it ended the list above the footer with the rows
+cut at that edge and an empty band under them.
+
+`onContentSizeChange`, less the spacer's own measured height
+(`scrollContentHeight`), writes `contentHeight`, which is the dynamic detent's
+measurement. A `BottomSheet.ScrollView` of forty rows therefore needs neither
+`snapPoints` nor `dynamicSizing={false}`: it sizes to its rows, capped by
+`maxDynamicContentSize`, and scrolls inside that. The content size and the
+spacer's layout arrive as two events from one commit; both are held in refs
+and folded into a single write after the batch, because the first open
+resolves on whatever `contentHeight` says first and the mount animation, once
+running, ignores a corrected detent list — a frame of rows-plus-spacer would
+open the sheet a footer too tall. `contentHeight` goes back to `UNMEASURED` on
+unmount for the same reason `useMeasureHeight` resets it.
+
+## The factory's contract
+
+The component handed to `createBottomSheetScrollable` must already be
+animated, and must be made **once at module scope** — `Animated.ScrollView`,
+`Animated.FlatList`, or `Animated.createAnimatedComponent(X)` in a module
+body. The wrapper drives it with `animatedProps` and an animated `onScroll`;
+a component created inside a render is a new type every frame and remounts
+its subtree.
+
+The wrapper is written once against the props every React Native scrollable
+shares (`ScrollableInnerProps`) and passes the rest through. The built-ins
+cast back to a generic signature so `data` and `renderItem` keep checking
+against each other — the same move `Screen.FlatList` makes in
+`@delacour/react-native-ui`.
+
+`contentContainerStyle` reaches the list flattened to one object. A
+virtualised list measures its content container, and an array style makes
+that measurement lag the layout by a frame.
+
+The consumer's `onScroll`, `onScrollBeginDrag`, `onScrollEndDrag` and
+`onMomentumScrollEnd` are called on the JS thread through `scheduleOnRN` with
+the event the worklet saw; they cannot be worklets of their own.
+
+`focusHook` defaults to `useEffect`. Under React Navigation pass
+`useFocusEffect`, and a list on a screen that is not showing withdraws from
+the sheet.
+
+## Out of scope
+
+Refresh control. `refreshControl` and `onRefresh` pass through untouched, but
+a pull-to-refresh at the top of a locked list fights the sheet's own
+pull-down, and no rule for that is written yet.

package/src/scrollable/bottom-sheet-flat-list.tsx

@@ -0,0 +1,15 @@
+import Animated from "react-native-reanimated";
+import { SCROLLABLE_TYPE } from "../core";
+import { createBottomSheetScrollable } from "./create-bottom-sheet-scrollable";
+import type { BottomSheetFlatListComponent } from "./scrollable.types";
+
+/**
+ * A `FlatList` as the sheet's body. `Animated.FlatList` is Reanimated's own,
+ * made once at module scope; the cast restores `<ItemT>` so `data` and
+ * `renderItem` check against each other.
+ */
+export const BottomSheetFlatList = createBottomSheetScrollable(
+	Animated.FlatList,
+	SCROLLABLE_TYPE.FLAT_LIST
+) as unknown as BottomSheetFlatListComponent;
+BottomSheetFlatList.displayName = "DelacourBottomSheet.BottomSheet.FlatList";

package/src/scrollable/bottom-sheet-scroll-view.tsx

@@ -0,0 +1,15 @@
+import Animated from "react-native-reanimated";
+import { SCROLLABLE_TYPE } from "../core";
+import { createBottomSheetScrollable } from "./create-bottom-sheet-scrollable";
+import type { BottomSheetScrollViewComponent } from "./scrollable.types";
+
+/**
+ * A `ScrollView` as the sheet's body: locked below the highest detent, sized
+ * to its content when the sheet is dynamic. `Animated.ScrollView` is
+ * Reanimated's own, made once at module scope.
+ */
+export const BottomSheetScrollView = createBottomSheetScrollable(
+	Animated.ScrollView,
+	SCROLLABLE_TYPE.SCROLL_VIEW
+) as unknown as BottomSheetScrollViewComponent;
+BottomSheetScrollView.displayName = "DelacourBottomSheet.BottomSheet.ScrollView";

package/src/scrollable/bottom-sheet-section-list.tsx

@@ -0,0 +1,22 @@
+import { SectionList } from "react-native";
+import Animated from "react-native-reanimated";
+import { SCROLLABLE_TYPE } from "../core";
+import { createBottomSheetScrollable } from "./create-bottom-sheet-scrollable";
+import type { BottomSheetSectionListComponent } from "./scrollable.types";
+
+/**
+ * Reanimated ships no `Animated.SectionList`, so this is the one built-in
+ * that calls `createAnimatedComponent` — once, here, at module scope, never
+ * inside a render.
+ */
+const AnimatedSectionList = Animated.createAnimatedComponent(SectionList);
+
+/**
+ * A `SectionList` as the sheet's body; the cast restores `<ItemT, SectionT>`
+ * so `sections` and `renderItem` check against each other.
+ */
+export const BottomSheetSectionList = createBottomSheetScrollable(
+	AnimatedSectionList,
+	SCROLLABLE_TYPE.SECTION_LIST
+) as unknown as BottomSheetSectionListComponent;
+BottomSheetSectionList.displayName = "DelacourBottomSheet.BottomSheet.SectionList";

package/src/scrollable/create-bottom-sheet-scrollable.tsx

@@ -0,0 +1,248 @@
+import {
+	type ComponentType,
+	createElement,
+	isValidElement,
+	type ReactElement,
+	type Ref,
+	useCallback,
+	useEffect,
+	useMemo,
+	useRef,
+} from "react";
+import { type LayoutChangeEvent, StyleSheet } from "react-native";
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import Animated, { useAnimatedRef, useAnimatedStyle } from "react-native-reanimated";
+import { useBottomSheetInternal } from "../components/bottom-sheet.context";
+import { SCROLLABLE_TYPE, type ScrollableType, scrollContentHeight, UNMEASURED } from "../core";
+import { useScrollLock } from "../gesture/use-scroll-lock";
+import { composeRefs } from "../lib/compose-refs";
+import type {
+	BottomSheetScrollableProps,
+	ScrollableHandle,
+	ScrollableInnerComponent,
+	ScrollableInnerProps,
+	ScrollableListFooter,
+} from "./scrollable.types";
+
+/**
+ * Before the first layout there is no content area to clamp to, and a
+ * `maxHeight` of zero would clip the list while it measures itself. Tall
+ * enough that no sheet reaches it.
+ */
+const UNCLAMPED = 100_000;
+
+/** How often the list reports its offset, in milliseconds — every frame. */
+const SCROLL_EVENT_THROTTLE = 16;
+
+type ScrollableProps = ScrollableInnerProps & BottomSheetScrollableProps;
+
+/** A consumer's `ListFooterComponent` — an element, a component type, or nothing — as an element. */
+function footerElement(footer: ScrollableListFooter | undefined): ReactElement | null {
+	if (footer === undefined || footer === null) return null;
+	if (isValidElement(footer)) return footer;
+	return createElement(footer);
+}
+
+/**
+ * Wraps an animated scrollable as a sheet body.
+ *
+ * The component passed in must already be animated — `Animated.ScrollView`,
+ * `Animated.FlatList`, or the result of `Animated.createAnimatedComponent`
+ * made **once, at module scope** — because the wrapper drives it with
+ * `animatedProps` and an animated `onScroll`, and because a component created
+ * inside a render remounts its subtree every frame.
+ *
+ * What the wrapper does, top to bottom:
+ *
+ * - Two gesture detectors. The outer is the sheet's content pan, the same
+ *   object `Content` uses; the inner is a `Native` gesture on the list itself,
+ *   declared simultaneous with that pan and kept alive when the finger leaves
+ *   the view. Both run at once, and the pan subtracts what the list consumed.
+ * - The scroll lock (`useScrollLock`). Below the highest detent the list is
+ *   held where it was, so the pan moves the sheet; at the highest it scrolls,
+ *   and a drag down at the top hands back to the sheet. The indicator hides,
+ *   bounce switches off and momentum is cut while locked.
+ * - The sizing. The list fills the body to the sheet's bottom line —
+ *   `contentArea + bodyInset` — and reserves the footer or the safe-area band
+ *   as a trailing spacer *inside* its content, so the rows scroll under either
+ *   and the last row can be brought fully clear of them. The spacer is
+ *   animated: it collapses with the band as the keyboard rises. The indicator
+ *   is inset by the same amount so it ends above the footer. The outer view
+ *   clips to the geometry's `bodyClip`, so under a footer nothing of the list
+ *   shows below the footer's top edge, at rest or while the sheet is dragged
+ *   down; the list itself does not shrink to that clip (see `styles.list`).
+ * - Content size. `onContentSizeChange` less the spacer's own measured height
+ *   feeds `contentHeight`, which is the dynamic detent's measurement: a
+ *   `ScrollView` of forty rows needs no `snapPoints` and no
+ *   `dynamicSizing={false}` — it sizes to its rows up to
+ *   `maxDynamicContentSize`, then scrolls. The two layout events land in one
+ *   batch and are folded into one write, so the detent never sees the rows
+ *   plus the spacer for a frame — a first open resolved on that sum would
+ *   animate to it and ignore the correction.
+ * - Registration. On focus the list tells the sheet what kind it is, and on
+ *   blur it withdraws and the offset resets; `focusHook` is where a navigator's
+ *   `useFocusEffect` goes.
+ *
+ * `contentContainerStyle` is flattened to one object before it reaches the
+ * list: a virtualised list measures its content container, and an array style
+ * makes that measurement lag a frame behind the layout.
+ *
+ * Refresh control is out of scope here — a `refreshControl` prop passes
+ * through untouched, but a pull-to-refresh at the top of a locked list fights
+ * the sheet's own pull-down, and no rule for that is written yet.
+ */
+export function createBottomSheetScrollable<P extends object>(
+	Scrollable: ComponentType<P>,
+	type: ScrollableType
+): ComponentType<P & BottomSheetScrollableProps> {
+	// The wrapper reads and writes the props every React Native scrollable
+	// shares and passes the rest through, so it is written once against that
+	// common shape; the built-ins restate their own generic signatures.
+	const Inner = Scrollable as unknown as ScrollableInnerComponent;
+	const isScrollView = type === SCROLLABLE_TYPE.SCROLL_VIEW;
+
+	function BottomSheetScrollable({
+		focusHook = useEffect,
+		ref,
+		style,
+		contentContainerStyle,
+		onContentSizeChange,
+		onScroll,
+		onScrollBeginDrag,
+		onScrollEndDrag,
+		onMomentumScrollEnd,
+		showsVerticalScrollIndicator,
+		scrollIndicatorInsets,
+		bounces,
+		decelerationRate,
+		children,
+		ListFooterComponent,
+		...rest
+	}: ScrollableProps): ReactElement {
+		const { state, geometry, pans, enableContentPanningGesture, setScrollableRef, removeScrollableRef } =
+			useBottomSheetInternal();
+		const { contentArea, bodyInset, bodyClip, layoutReady } = geometry;
+		const animatedRef = useAnimatedRef<ScrollableHandle>();
+
+		const { scrollHandler, animatedProps } = useScrollLock(state, geometry, animatedRef, {
+			enableContentPan: enableContentPanningGesture,
+			showsVerticalScrollIndicator,
+			scrollIndicatorInsets,
+			indicatorInset: bodyInset,
+			bounces,
+			decelerationRate,
+			listeners: { onScroll, onScrollBeginDrag, onScrollEndDrag, onMomentumScrollEnd },
+		});
+
+		const native = useMemo(
+			() => Gesture.Native().simultaneousWithExternalGesture(pans.content).shouldCancelWhenOutside(false),
+			[pans.content]
+		);
+
+		const composedRef = useMemo(
+			() => composeRefs<ScrollableHandle>(animatedRef as unknown as Ref<ScrollableHandle>, ref),
+			[animatedRef, ref]
+		);
+
+		const clip = useAnimatedStyle(() => ({
+			maxHeight: layoutReady.value ? bodyClip.value : UNCLAMPED,
+		}));
+		const clamp = useAnimatedStyle(() => ({
+			maxHeight: layoutReady.value ? contentArea.value + bodyInset.value : UNCLAMPED,
+		}));
+		const spacer = useAnimatedStyle(() => ({ height: bodyInset.value }));
+
+		// The content size and the spacer's height arrive as two layout events
+		// from the same commit; both are kept and one write follows the batch.
+		const contentSize = useRef<number | null>(null);
+		const spacerHeight = useRef<number | null>(null);
+		const flushQueued = useRef(false);
+		const flush = useCallback(() => {
+			flushQueued.current = false;
+			if (contentSize.current === null || spacerHeight.current === null) return;
+			const rows = scrollContentHeight(contentSize.current, spacerHeight.current);
+			if (state.contentHeight.value !== rows) state.contentHeight.value = rows;
+		}, [state]);
+		const queueFlush = useCallback(() => {
+			if (flushQueued.current) return;
+			flushQueued.current = true;
+			queueMicrotask(flush);
+		}, [flush]);
+
+		const handleContentSizeChange = useCallback(
+			(width: number, height: number) => {
+				contentSize.current = height;
+				queueFlush();
+				if (onContentSizeChange) onContentSizeChange(width, height);
+			},
+			[queueFlush, onContentSizeChange]
+		);
+		const handleSpacerLayout = useCallback(
+			(event: LayoutChangeEvent) => {
+				spacerHeight.current = event.nativeEvent.layout.height;
+				queueFlush();
+			},
+			[queueFlush]
+		);
+
+		useEffect(
+			() => () => {
+				state.contentHeight.value = UNMEASURED;
+			},
+			[state]
+		);
+
+		const register = useCallback(() => {
+			setScrollableRef(animatedRef, type);
+			return () => removeScrollableRef(animatedRef);
+		}, [setScrollableRef, removeScrollableRef, animatedRef]);
+		focusHook(register, [register]);
+
+		const trailing = <Animated.View onLayout={handleSpacerLayout} pointerEvents="none" style={spacer} />;
+		const consumerFooter = footerElement(ListFooterComponent);
+		const listFooter = isScrollView ? undefined : (
+			<>
+				{consumerFooter}
+				{trailing}
+			</>
+		);
+
+		return (
+			<GestureDetector gesture={pans.content}>
+				<Animated.View style={[styles.outer, clip]}>
+					<GestureDetector gesture={native}>
+						<Inner
+							{...rest}
+							animatedProps={animatedProps}
+							contentContainerStyle={StyleSheet.flatten(contentContainerStyle)}
+							keyboardDismissMode="interactive"
+							ListFooterComponent={listFooter}
+							onContentSizeChange={handleContentSizeChange}
+							onScroll={scrollHandler}
+							overScrollMode="never"
+							ref={composedRef}
+							scrollEventThrottle={SCROLL_EVENT_THROTTLE}
+							style={[styles.list, style, clamp]}
+						>
+							{isScrollView ? children : undefined}
+							{isScrollView ? trailing : undefined}
+						</Inner>
+					</GestureDetector>
+				</Animated.View>
+			</GestureDetector>
+		);
+	}
+	BottomSheetScrollable.displayName = "DelacourBottomSheet.BottomSheet.Scrollable";
+
+	return BottomSheetScrollable as unknown as ComponentType<P & BottomSheetScrollableProps>;
+}
+
+// A React Native scrollable ships `flexShrink: 1`, and Yoga would shrink it to
+// the clipping wrapper — the footer's top edge — instead of letting it reach
+// the sheet's bottom line, which puts the trailing spacer's clearance on top
+// of the wrapper's and doubles it. `flexShrink: 0` leaves only `maxHeight` to
+// bound it, and the wrapper alone does the clipping.
+const styles = StyleSheet.create({
+	outer: { flexShrink: 1, overflow: "hidden" },
+	list: { flexShrink: 0 },
+});

package/src/scrollable/scrollable.types.ts

@@ -0,0 +1,76 @@
+import type { Component, ComponentType, DependencyList, EffectCallback, ReactElement, Ref, RefAttributes } from "react";
+import type { FlatList, FlatListProps, ScrollView, ScrollViewProps, SectionList, SectionListProps } from "react-native";
+import type { AnimatedProps } from "react-native-reanimated";
+
+/**
+ * The list a scrollable registers with its sheet. Kept for identity — the
+ * lock scrolls it through Reanimated's own animated ref — so the constraint is
+ * only that it is a component instance.
+ */
+export type ScrollableHandle = Component;
+
+/**
+ * The hook that runs the registration effect.
+ *
+ * `useEffect` registers on mount. Under React Navigation `useFocusEffect` has
+ * the same shape and registers when the screen gains focus, so two screens in
+ * a stack, each with a list in the same sheet, hand the sheet the one that is
+ * showing.
+ */
+export type FocusHook = (effect: EffectCallback, deps?: DependencyList) => void;
+
+/** What every `createBottomSheetScrollable` component adds on top of the list's own props. */
+export type BottomSheetScrollableProps = {
+	/** @default useEffect */
+	focusHook?: FocusHook;
+};
+
+/** A list's `ListFooterComponent`, as the virtualised lists take it. */
+export type ScrollableListFooter = ComponentType<unknown> | ReactElement | null;
+
+/**
+ * The props the wrapper itself reads or writes, and that every React Native
+ * scrollable has. The generic list's remaining props pass through untouched.
+ * `ListFooterComponent` is the one list-only prop here: the wrapper appends
+ * its trailing spacer to it, where a `ScrollView` takes the spacer as a child.
+ */
+export type ScrollableInnerProps = Omit<ScrollViewProps, "style"> & {
+	ref?: Ref<ScrollableHandle>;
+	style?: AnimatedProps<ScrollViewProps>["style"];
+	animatedProps?: Partial<ScrollViewProps> | readonly Partial<ScrollViewProps>[];
+	ListFooterComponent?: ScrollableListFooter;
+};
+
+/** The animated list a factory wraps — `Animated.ScrollView`, `Animated.FlatList`, or one made with `createAnimatedComponent`. */
+export type ScrollableInnerComponent = ComponentType<ScrollableInnerProps>;
+
+export type BottomSheetScrollViewProps = ScrollViewProps &
+	BottomSheetScrollableProps & {
+		ref?: Ref<ScrollView>;
+	};
+
+export type BottomSheetFlatListProps<ItemT> = Omit<FlatListProps<ItemT>, "children"> & BottomSheetScrollableProps;
+
+export type BottomSheetSectionListProps<ItemT, SectionT> = Omit<SectionListProps<ItemT, SectionT>, "children"> &
+	BottomSheetScrollableProps;
+
+/**
+ * The generic component types, restated so `<ItemT>` survives the factory.
+ *
+ * `createBottomSheetScrollable` returns one concrete component, so `data` and
+ * `renderItem` would check against `unknown` and stop constraining each
+ * other. Writing the signature out is the same move
+ * `@delacour/react-native-ui`'s `Screen.FlatList` makes, and the `displayName`
+ * member is what keeps the trailing assignment legal after the cast.
+ */
+export type BottomSheetFlatListComponent = (<ItemT>(
+	props: BottomSheetFlatListProps<ItemT> & RefAttributes<FlatList<ItemT>>
+) => ReactElement) & { displayName?: string };
+
+export type BottomSheetSectionListComponent = (<ItemT, SectionT>(
+	props: BottomSheetSectionListProps<ItemT, SectionT> & RefAttributes<SectionList<ItemT, SectionT>>
+) => ReactElement) & { displayName?: string };
+
+export type BottomSheetScrollViewComponent = ((props: BottomSheetScrollViewProps) => ReactElement) & {
+	displayName?: string;
+};

package/src/source-tree.test.ts

@@ -0,0 +1,33 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** Every `.ts`/`.tsx` under `dir`, tests included unless `skipTests`. */
+export function sourceFiles(dir: string, options: { skipTests?: boolean } = {}): string[] {
+	const found: string[] = [];
+	const walk = (current: string): void => {
+		for (const entry of readdirSync(current)) {
+			const path = join(current, entry);
+			if (statSync(path).isDirectory()) {
+				walk(path);
+				continue;
+			}
+			if (!/\.tsx?$/.test(entry)) continue;
+			if (options.skipTests && /\.test\.tsx?$/.test(entry)) continue;
+			found.push(path);
+		}
+	};
+	walk(dir);
+	return found;
+}
+
+export const SRC = import.meta.dir;
+export const PACKAGE_ROOT = join(SRC, "..");
+
+export function read(path: string): string {
+	return readFileSync(path, "utf8");
+}
+
+/** `path` relative to the package, for a failure message that can be acted on. */
+export function relative(path: string): string {
+	return path.slice(PACKAGE_ROOT.length + 1);
+}

package/src/state/AGENTS.md

@@ -0,0 +1,63 @@
+# state
+
+The shared values a sheet owns, the numbers derived from them, and the intent
+queue that moves them.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `state.types.ts` | `SheetSharedState` (the raw shared values), `SheetGeometry` (the derived ones), `SheetWorkletConfig` (the props a worklet reads), `ANIM_STATUS` |
+| `use-sheet-state.ts` | Allocates the raw values once per sheet; mirrors `snapPoints` and the config into them, keyed on serialisation rather than identity |
+| `use-detents.ts` | `detents` — `normalizeDetents` plus the dynamic detent once handle and content have measured |
+| `use-sheet-geometry.ts` | Every formula in `core/AGENTS.md` as a `useDerivedValue`, in dependency order |
+| `use-sheet-intents.ts` | The JS-thread `dispatch`, the reaction that resolves an intent on the UI thread, and the reaction that follows a detent change or a container resize |
+
+## The model
+
+`base` is the only value an animation or a gesture writes. Everything a view
+reads — `height`, `position`, `index`, `contentArea` — is derived from it and
+from the measurements, on the UI thread, by the core's pure functions. Nothing
+in this folder contains a formula; it contains `useDerivedValue(() =>
+coreFunction(...))` and nothing else, which is what keeps the numbers
+testable.
+
+Measurements start at `UNMEASURED` (`-1`) and go back to it when the part that
+reported them unmounts (`layout/`). `layoutReady` is derived from them, and an
+`open` intent waits on it.
+
+The keyboard values — `keyboardHeight`, `keyboardProgress`, `keyboardOwned` —
+are allocated here and every keyboard term in the geometry is a real
+derivation over them. BSHEET-3 writes them; until then they are `0`, `0` and
+`false`, and every keyboard term is inert. `footerContentHeight` is the same:
+allocated, derived over, and unmeasured until BSHEET-3 mounts a footer and the
+root sets `hasFooter`.
+
+## Intents
+
+`dispatch({ kind: "open" })` writes `state.intent`; a reaction keyed on the
+intent's `id` and on `layoutReady` runs `resolveIntent` from the core and calls
+`animateTo` or `jumpTo`. The JS thread never animates and never reads a
+measurement to decide whether it may.
+
+The resolver is told the sheet's **effective** index: the settled one, or the
+running animation's target. Without that a `close()` during the open animation
+would see a closed sheet, resolve to nothing, and let the sheet finish opening.
+
+The first open a sheet resolves is reported as `"mount"` and, with
+`animateOnMount: false`, jumps. `mountPending` is that flag.
+
+## Detents moving under a settled sheet
+
+The second reaction watches the detent list and the container height. When
+the list changes with the sheet idle and open, the sheet animates to the same
+index in the new list — dynamic content growing, a `snapPoints` change. When
+the container changed, it jumps there instead: a rotation is not something to
+animate through. Neither runs while a gesture or an animation owns `base`.
+
+## Why the config is one shared value
+
+A worklet that captured a dozen boolean props would rebuild every time one of
+them changed, and a gesture captures the pan handlers. `config` is one object
+written by one effect, and a worklet reads `state.config.value.x` at the
+moment it needs it.