@delacour/react-native-ui 0.1.0-alpha.20260928015421 → 0.1.0-alpha.20261004043720

package/README.md

@@ -82,7 +82,7 @@ import { IconArrowRight } from "@delacour/react-native-ui/icons/central";
 | --- | --- | --- |
 | Accordion | `@delacour/react-native-ui/accordion` | Selection modes, measured panels, indicators |
 | Badge | `@delacour/react-native-ui/badge` | Variants, colours, sizes, dismiss |
-| BottomSheet | `@delacour/react-native-ui/bottom-sheet` | Detents, keyboard, sticky footer, scrollables, steps, detached, teleported portal |
+| BottomSheet | `@delacour/react-native-ui/bottom-sheet` | Snap points, keyboard, sticky footer, scrollables, steps, detached, teleported portal |
 | Button | `@delacour/react-native-ui/button` | Variants, sizes, icons, loading |
 | Checkbox | `@delacour/react-native-ui/checkbox` | Colours, sizes, indeterminate, groups |
 | Field | `@delacour/react-native-ui/field` | Form layout, grouping, state cascade |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20260928015421",
+	"version": "0.1.0-alpha.20261004043720",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -71,10 +71,12 @@
 		"./textarea": "./src/components/textarea/index.ts",
 		"./toggle-button": "./src/components/toggle-button/index.ts",
 		"./expo/navigation-theme": "./src/expo/navigation-theme.tsx",
+		"./hooks/use-calm-motion": "./src/hooks/use-calm-motion.tsx",
 		"./hooks/use-controllable-state": "./src/hooks/use-controllable-state.ts",
 		"./hooks/use-keyboard-state-sync": "./src/hooks/use-keyboard-state-sync.tsx",
 		"./hooks/use-navigation-theme": "./src/hooks/use-navigation-theme.ts",
 		"./hooks/use-theme-color": "./src/hooks/use-theme-color.ts",
+		"./lib/calm-motion": "./src/lib/calm-motion.ts",
 		"./lib/cn": "./src/lib/cn.ts",
 		"./lib/color": "./src/lib/color.ts",
 		"./lib/compose-refs": "./src/lib/compose-refs.ts",
@@ -98,8 +100,8 @@
 	},
 	"peerDependencies": {
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-bottom-sheet": "0.1.0-alpha.20260928015421",
-		"@delacour/react-native-charts": "0.1.0-alpha.20260928015421",
+		"@delacour/react-native-bottom-sheet": "0.1.0-alpha.20261004043720",
+		"@delacour/react-native-charts": "0.1.0-alpha.20261004043720",
 		"@legendapp/list": ">=3.3",
 		"expo-linear-gradient": ">=15",
 		"expo-router": ">=57",

package/src/components/accordion/AGENTS.md

@@ -24,7 +24,7 @@ a list of rows.
 | `accordion.context.tsx` | `AccordionContext` and `AccordionItemContext`, with their hooks |
 | `accordion.types.ts` | Prop types shared by two or more parts |
 | `accordion.variants.ts` | Pure `tv()` slots + the selection maths, no RN imports |
-| `accordion.variants.test.ts` | |
+| `accordion.variants.test.ts` | `accordionTravelTarget`, and the sweep for a JS-thread `contentHeight.value` read (exports `jsThreadSource` and `CONTENT_HEIGHT_READ` for `Collapsible`'s) |
 
 ## Design
 
@@ -90,12 +90,23 @@ a list of rows.
   effect.** A panel that has never mounted has no height to travel against, so
   springing on the state change would run the whole animation at zero and jump
   the moment a measurement arrived. The item's effect skips exactly that one
-  case and `accordion-content.tsx`'s `onLayout` starts it instead. Every later
-  toggle, in either direction, is the item's.
+  case and `accordion-content.tsx`'s `onLayout` reports the measurement, which
+  flips the item's `isMeasured` state and re-runs the effect. Every later toggle,
+  in either direction, is the item's. The decision is `accordionTravelTarget`,
+  pure and tested.
+- **Nothing on the JS thread reads `contentHeight.value`.** "Has this panel
+  measured?" is React state (`isMeasured`, on both the item and the panel), never
+  a read of the shared value. A JS-thread write to a shared value is *queued* onto
+  the UI runtime, while a JS-thread read runs there synchronously under its lock
+  without draining that queue — so the item's effect, running straight after the
+  `onLayout` that wrote the height, can read `ACCORDION_UNMEASURED`. A Release
+  build does, deterministically: the effect bailed, nothing re-ran it, and the
+  panel reported `expanded` while never opening (a Debug client is slow enough
+  for the write to land first, which is why it hid). `accordion.variants.test.ts`
+  sweeps both files for such a read outside `useAnimatedStyle`.
 - **`ACCORDION_UNMEASURED` is negative, and that is load-bearing.** A panel that
-  measured `0` is a real answer — content that rendered nothing — and an item
-  treating it as "still waiting" would never start its spring, leaving the
-  indicator pointing the wrong way. Only a value no layout can produce can mean
+  measured `0` is a real answer — content that rendered nothing — and must still
+  open, indicator and all. Only a value no layout can produce can mean
   *unmeasured*, so the height style floors it.
 
 ## Selection

package/src/components/accordion/accordion-content.tsx

@@ -2,7 +2,7 @@ import { type ReactElement, type ReactNode, useCallback, useState } from "react"
 import { type LayoutChangeEvent, StyleSheet, View, type ViewProps } from "react-native";
 import Animated, { interpolate, useAnimatedStyle } from "react-native-reanimated";
 import { useAccordionItemPart, useAccordionPart } from "./accordion.context";
-import { ACCORDION_CONTENT_FADE, ACCORDION_UNMEASURED, accordionVariants } from "./accordion.variants";
+import { ACCORDION_CONTENT_FADE, accordionVariants } from "./accordion.variants";
 
 export type AccordionContentProps = Omit<ViewProps, "style"> & {
 	className?: string;
@@ -55,7 +55,6 @@ export function AccordionContent({ className, children, ...props }: AccordionCon
 
 	const handleLayout = useCallback(
 		(event: LayoutChangeEvent) => {
-			const wasMeasured = contentHeight.value > ACCORDION_UNMEASURED;
 			contentHeight.value = event.nativeEvent.layout.height;
 
 			// The panel reports its first measurement and stops there — it must not
@@ -64,11 +63,15 @@ export function AccordionContent({ className, children, ...props }: AccordionCon
 			// is sometimes cancelled a moment later by the cleanup of the item's
 			// effect it raced, leaving the panel shut and the indicator pointing the
 			// wrong way. Telling the item instead leaves one owner of the spring.
-			if (wasMeasured) return;
+			//
+			// "First" is this component's own state, never `contentHeight.value`: the
+			// write above is queued onto the UI runtime, and a JS-thread read straight
+			// after it can still see the old value.
+			if (isMeasured) return;
 			setMeasured(true);
 			onMeasured();
 		},
-		[contentHeight, onMeasured]
+		[contentHeight, isMeasured, onMeasured]
 	);
 
 	// Height and opacity off the one `progress`, never off a timing of their own —

package/src/components/accordion/accordion-item.tsx

@@ -5,6 +5,7 @@ import { type AccordionItemContextValue, AccordionItemProvider, useAccordionPart
 import {
 	ACCORDION_SPRING,
 	ACCORDION_UNMEASURED,
+	accordionTravelTarget,
 	accordionVariants,
 	isItemExpanded,
 	resolveAccordionItemAxes,
@@ -42,25 +43,26 @@ export function AccordionItem({ value, isDisabled, className, children, ...props
 	const progress = useSharedValue(isExpanded ? 1 : 0);
 	const contentHeight = useSharedValue(ACCORDION_UNMEASURED);
 
-	// Bumped the first time this item's panel reports a height, purely to make the
-	// effect below run again. See `onMeasured` on the item context for why the
-	// panel must not start the spring itself.
-	const [measurements, setMeasurements] = useState(0);
-	const onMeasured = useCallback(() => setMeasurements((count) => count + 1), []);
+	// Whether this item's panel has ever reported a height. React state, not a read
+	// of `contentHeight` on the JS thread: that write is queued onto the UI runtime
+	// and a read straight after it can still see `ACCORDION_UNMEASURED` — which a
+	// Release build does, every time. See `accordionTravelTarget`.
+	const [isMeasured, setMeasured] = useState(false);
+	const onMeasured = useCallback(() => setMeasured(true), []);
 
-	// `measurements` is not read in the body — being unread is the whole point of
-	// it, the way `settledDrags` is for a `Switch`. The first expand of a panel
-	// that has never been mounted has no height to travel against, so this run
-	// bails; the measurement that follows is what brings it back.
-	// biome-ignore lint/correctness/useExhaustiveDependencies: the extra dependency is the re-run trigger, see above
+	// The first expand of a panel that has never been mounted has no height to
+	// travel against, so this run waits; the measurement that follows flips
+	// `isMeasured` and brings it back. See `onMeasured` on the item context for why
+	// the panel must not start the spring itself.
 	useEffect(() => {
-		if (isExpanded && contentHeight.value === ACCORDION_UNMEASURED) return;
+		const target = accordionTravelTarget({ isExpanded, isMeasured });
+		if (target === null) return;
 
-		progress.value = withSpring(isExpanded ? 1 : 0, ACCORDION_SPRING);
+		progress.value = withSpring(target, ACCORDION_SPRING);
 
 		// Without this an item unmounted mid-travel leaves its spring running.
 		return () => cancelAnimation(progress);
-	}, [contentHeight, isExpanded, measurements, progress]);
+	}, [isExpanded, isMeasured, progress]);
 
 	const context = useMemo<AccordionItemContextValue>(
 		() => ({ contentHeight, isDisabled: axes.isDisabled, isExpanded, onMeasured, progress, value }),

package/src/components/accordion/accordion.context.tsx

@@ -35,8 +35,9 @@ export type AccordionItemContextValue = {
 	 * The panel's natural height in points, from its own `onLayout`.
 	 *
 	 * Holds {@link ACCORDION_UNMEASURED} until a panel has reported, which is not
-	 * the same as a panel that measured zero: the item's spring waits on the first
-	 * measurement rather than travelling against a height that is not there yet.
+	 * the same as a panel that measured zero. Read on the UI runtime only — by the
+	 * height style — and written from the panel's `onLayout`; nothing on the JS
+	 * thread reads it, because a JS read can lag a JS write. See {@link onMeasured}.
 	 */
 	contentHeight: SharedValue<number>;
 	/**
@@ -46,9 +47,14 @@ export type AccordionItemContextValue = {
 	 * spring. The panel cannot start the travel itself: `onLayout` is dispatched
 	 * from the native side and can land either side of React's effects, so a panel
 	 * that started its own spring would sometimes have it cancelled a moment later
-	 * by the cleanup of the effect it raced. This hands the item a reason to re-run
-	 * instead — `Slider`'s and `Switch`'s `settledDrags`, for the same reason: a
-	 * counter whose only job is to give an effect something to fire on.
+	 * by the cleanup of the effect it raced. This flips the item's own
+	 * `isMeasured` state instead, which is what re-runs the item's effect.
+	 *
+	 * That state, not a JS-thread read of {@link contentHeight}, is how the item
+	 * knows a panel has measured. The panel's write is queued onto the UI runtime
+	 * and a read straight after it can still see `ACCORDION_UNMEASURED` — a Release
+	 * build does, every time, and the panel stayed shut. See
+	 * `accordionTravelTarget`.
 	 */
 	onMeasured: () => void;
 };

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

@@ -16,6 +16,7 @@ import {
 	ACCORDION_SPRING,
 	ACCORDION_UNMEASURED,
 	ACCORDION_VARIANTS,
+	accordionTravelTarget,
 	accordionVariants,
 	isItemExpanded,
 	resolveAccordionItemAxes,
@@ -432,3 +433,64 @@ describe("accordion animation", () => {
 		expect(end).toBeLessThan(1);
 	});
 });
+
+describe("accordionTravelTarget", () => {
+	test("an expand waits for the panel's first measurement", () => {
+		expect(accordionTravelTarget({ isExpanded: true, isMeasured: false })).toBeNull();
+	});
+
+	test("an expand travels to 1 once the panel has measured", () => {
+		expect(accordionTravelTarget({ isExpanded: true, isMeasured: true })).toBe(1);
+	});
+
+	test("a collapse never waits, measured or not", () => {
+		expect(accordionTravelTarget({ isExpanded: false, isMeasured: false })).toBe(0);
+		expect(accordionTravelTarget({ isExpanded: false, isMeasured: true })).toBe(0);
+	});
+});
+
+/**
+ * A file's source with comments and every `useAnimatedStyle(...)` call stripped — the one
+ * place a read of a shared value runs on the UI runtime — leaving only code that runs on the
+ * JS thread.
+ */
+export function jsThreadSource(path: string): string {
+	const source = readFileSync(path, "utf8")
+		.replace(/\/\*[\s\S]*?\*\//g, "")
+		.replace(/\/\/.*$/gm, "");
+	let out = "";
+	let index = 0;
+	for (;;) {
+		const start = source.indexOf("useAnimatedStyle(", index);
+		if (start === -1) return out + source.slice(index);
+		out += source.slice(index, start);
+		let depth = 0;
+		let cursor = start + "useAnimatedStyle".length;
+		do {
+			if (source[cursor] === "(") depth++;
+			if (source[cursor] === ")") depth--;
+			cursor++;
+		} while (depth > 0 && cursor < source.length);
+		index = cursor;
+	}
+}
+
+/** `contentHeight.value` as a read: anything but the left side of a plain `=`. */
+export const CONTENT_HEIGHT_READ = /\bcontentHeight\.value\b(?!\s*=(?!=))/;
+
+describe("the measured height is never read on the JS thread", () => {
+	// A JS-thread write to a shared value is queued onto the UI runtime, while a JS-thread read
+	// runs there synchronously under its lock without draining that queue. A read straight after
+	// the write — the item's effect after the panel's `onLayout` — can see the old value. In a
+	// Release build it does, every time: the item read `ACCORDION_UNMEASURED`, bailed, and nothing
+	// re-ran it, so the panel said `expanded` and stayed shut.
+	test.each(["accordion-item.tsx", "accordion-content.tsx"])("%s", (file) => {
+		expect(jsThreadSource(join(import.meta.dirname, file))).not.toMatch(CONTENT_HEIGHT_READ);
+	});
+
+	test("the guard sees a read and ignores a write", () => {
+		expect("if (contentHeight.value === -1) return;").toMatch(CONTENT_HEIGHT_READ);
+		expect("const was = contentHeight.value > -1;").toMatch(CONTENT_HEIGHT_READ);
+		expect("contentHeight.value = event.nativeEvent.layout.height;").not.toMatch(CONTENT_HEIGHT_READ);
+	});
+});

package/src/components/accordion/accordion.variants.ts

@@ -76,17 +76,41 @@ export const ACCORDION_INDICATOR_ROTATION = { collapsed: 0, expanded: 180 } as c
  * What {@link AccordionItemContextValue.contentHeight} holds before a panel has
  * ever reported its own layout.
  *
- * Negative rather than zero, because the two mean different things and the
- * difference is load-bearing. A panel that measured `0` is a real answer — a
- * panel whose content rendered nothing — and an item that treated it as "still
- * waiting" would never start its spring, leaving the indicator stuck pointing the
- * wrong way for an empty panel. Only a value no layout can produce can mean
- * *unmeasured*.
+ * Negative rather than zero, because the two mean different things. A panel that
+ * measured `0` is a real answer — a panel whose content rendered nothing — and
+ * still opens, indicator and all. Only a value no layout can produce can mean
+ * *unmeasured*. Whether a panel *has* measured is never decided by comparing
+ * against this on the JS thread — see {@link accordionTravelTarget}.
  *
  * The height style therefore floors it: `progress * max(contentHeight, 0)`.
  */
 export const ACCORDION_UNMEASURED = -1;
 
+/**
+ * Where an item's `progress` should spring to, or `null` to wait.
+ *
+ * Only an expand waits, and only for a panel that has never measured: it has no
+ * height to travel against yet, and the measurement is what starts it. A collapse
+ * never waits.
+ *
+ * `isMeasured` is **React state**, never a read of `contentHeight` on the JS
+ * thread. A JS-thread write to a shared value is queued onto the UI runtime, while
+ * a JS-thread read runs there synchronously without draining that queue, so a read
+ * straight after the panel's `onLayout` wrote the height can still see
+ * {@link ACCORDION_UNMEASURED}. A Release build does, every time — the item bailed
+ * and nothing re-ran it, so the panel said `expanded` and stayed shut.
+ */
+export function accordionTravelTarget({
+	isExpanded,
+	isMeasured,
+}: {
+	isExpanded: boolean;
+	isMeasured: boolean;
+}): 0 | 1 | null {
+	if (!isExpanded) return 0;
+	return isMeasured ? 1 : null;
+}
+
 /**
  * The window of the travel the panel's opacity ramps across.
  *

package/src/components/bottom-sheet/AGENTS.md

@@ -71,7 +71,7 @@ engine's names win everywhere; this skin aliases nothing.
 ## What the engine owns
 
 Everything that is not a class. The open state and the intent queue; the
-height-space geometry and the detents; the handle and content pans and how a
+height-space geometry and the snap points; the handle and content pans and how a
 list shares a finger with them; the keyboard — who owns it, `interactive` /
 `extend` / `fillParent` / `none`, the lift and the restore; the sticky footer's
 line and the safe-area band under it; the teleport portal, the hosts, the
@@ -92,7 +92,7 @@ read those before touching behaviour, because behaviour is not here.
   components applies: the engine is another package.
 - **Where the classes land.** `Content`, `Footer` and `Steps` hand `style` to
   the engine's *measured* inner view, so a class there is height the dynamic
-  detent counts. `ScrollView` puts its content classes on an inner `View`
+  snap point counts. `ScrollView` puts its content classes on an inner `View`
   rather than the content container, so the one style this file writes there —
   the gap above a pinned footer — has a single writer. The three virtualised
   lists have no inner box, so theirs go on `contentContainerClassName`; the
@@ -115,16 +115,16 @@ read those before touching behaviour, because behaviour is not here.
   `fade` and an 8pt slop, for `Badge.CloseButton`'s and `Checkbox`'s reasons.
 - **The root fills in three defaults.** `bottomInset` is `useSafeAreaInsets().bottom`,
   so the engine reserves the home-indicator band and nobody pads for it by
-  hand. `onDetentHaptic` is `Presets.System.selection` and `onCloseHaptic` is
+  hand. `onSnapPointHaptic` is `Presets.System.selection` and `onCloseHaptic` is
   `Presets.System.impactLight` — pulsar's presets are worklets, so they are
   passed as they are; a JS function there is `undefined is not a function` on
   the UI thread. And `useKeyboardAnimationGuard()` runs on mount, the same
   stale-keyboard repair `Screen.Footer` runs. `topInset` stays at the engine's
-  zero, so a `%` detent is the fraction of the window it always was.
+  zero, so a `%` snap point is the fraction of the window it always was.
 - **`Footer.sticky` defaults to `false`**, matching `Screen.Footer`, and this is
   the one engine default the skin overrides. A pinned footer takes
   `padding={BOTTOM_SHEET_FOOTER_PADDING}` through the engine's prop rather
-  than a class, so the padding is inside the box the detent measures; the
+  than a class, so the padding is inside the box the snap point measures; the
   `stickyFooter` slot carries the gutter, the surface and the hairline, and
   the test asserts it carries no vertical padding.
 - **The overlay's opacity is 1**, because `--overlay` carries its own alpha and
@@ -178,7 +178,7 @@ problem it has:
 - nesting a sheet in a sheet — the registry stacks them; `stackBehavior` and
   `dismissAll` are for exactly that
 - `ScrollView` needing `dynamicSizing={false}` and `snapPoints` — a list's
-  content size is the dynamic detent
+  content size is the dynamic snap point
 - lifting `Overlay` and a sticky `Footer` out of the tree as render props —
   every part renders where it is written
 - a `Content` inside a `Container` paying the safe-area band by hand — the

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

@@ -37,7 +37,7 @@ export type BottomSheetFlatListProps<ItemT> = HeadlessProps<ItemT> & {
  * A virtualised body.
  *
  * The engine's `FlatList` — the scroll lock, the drag budget and content size
- * as the dynamic detent are all its — with the library's gutter on the content
+ * as the dynamic snap point are all its — with the library's gutter on the content
  * container. A virtualised list has no inner box to put the classes on, so
  * here they go on `contentContainerClassName`; the engine flattens the
  * resulting style to one object before the list measures it.

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

@@ -36,7 +36,7 @@ export type BottomSheetFooterProps = HeadlessProps & {
  * geometry's footer line, which the core proves holds still through a keyboard
  * animation, so its buttons land on the keyboard's top edge without moving;
  * the safe-area band under it is a spacer the geometry owns; and its measured
- * height is what the body reserves and the dynamic detent counts. The
+ * height is what the body reserves and the dynamic snap point counts. The
  * `padding` goes to the engine rather than a class for that reason — it has to
  * be inside the measured box.
  *

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

@@ -25,7 +25,7 @@ export type BottomSheetHandleProps = HeadlessProps & {
  *
  * The engine's handle draws nothing of its own: it owns the pan, measures
  * itself into the sheet's height, and is the adjustable element a screen
- * reader steps through the detents with. This puts the pill inside it, and
+ * reader steps through the snap points with. This puts the pill inside it, and
  * classes on both.
  *
  * Pass children to replace the pill; the row, the pan and the accessibility

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

@@ -44,7 +44,7 @@ export type BottomSheetLegendListProps<ItemT> = Omit<AnimatedLegendListProps<Ite
  * Built here rather than in the engine because `@legendapp/list` is this
  * library's optional peer, not the engine's: the engine exports the factory,
  * and this is what the factory is for. The same scroll lock, drag budget and
- * content-size detent as the other three bodies.
+ * content-size snap point as the other three bodies.
  *
  * @example
  * <BottomSheet.LegendList data={rows} keyExtractor={(row) => row.id} renderItem={renderRow} />

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

@@ -36,13 +36,13 @@ export type BottomSheetScrollViewProps = Omit<HeadlessProps, "children"> & {
  * A scrolling body.
  *
  * Use this rather than a plain `ScrollView`: the engine's scrollable and the
- * sheet's pan share a finger — below the highest detent the list is held and
+ * sheet's pan share a finger — below the highest snap point the list is held and
  * the drag moves the sheet, at the highest the list scrolls, and a drag down
  * from the top hands back to the sheet. A React Native `ScrollView` in here has
  * no such arrangement.
  *
  * **It needs no `snapPoints` and no `dynamicSizing={false}`.** The list
- * reports its content size, and that is the dynamic detent: six rows make a
+ * reports its content size, and that is the dynamic snap point: six rows make a
  * short sheet, forty make one capped at `maxDynamicContentSize` that scrolls
  * inside the cap. Explicit `snapPoints` on the root still work, for a height
  * that is a decision rather than a measurement.

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

@@ -38,11 +38,11 @@ export type BottomSheetProps = HeadlessBottomSheetProps;
  * Both run on the UI thread from inside the engine's pan, so they are
  * `Presets.System.*` — themselves worklets — and nothing else: a JS function
  * here would be `undefined is not a function` at the moment a finger crosses a
- * detent. `selection` on a detent because that is what a picker's tick feels
+ * snap point. `selection` on a snap point because that is what a picker's tick feels
  * like, and `impactLight` on a close because letting go of a sheet is a
  * heavier event than passing a stop, but not by much.
  */
-const detentHaptic = Presets.System.selection;
+const snapPointHaptic = Presets.System.selection;
 const closeHaptic = Presets.System.impactLight;
 
 /**
@@ -55,19 +55,19 @@ const closeHaptic = Presets.System.impactLight;
  *   `useSafeAreaInsets()`. The engine reserves that band under the body or the
  *   sticky footer and gives it back to the keyboard as it arrives; a caller
  *   never pads for the home indicator by hand.
- * - **The haptics are on by default.** Pass `onDetentHaptic={undefined}` to
+ * - **The haptics are on by default.** Pass `onSnapPointHaptic={undefined}` to
  *   turn one off, or a worklet of your own to change it.
  * - **The stale-keyboard guard runs on mount.** A sheet mounted while
  *   `KeyboardProvider`'s shared values are pinned open by a keyboard that
  *   vanished without a `will` event would lift for a keyboard that is not
  *   there; `Screen.Footer` runs the same repair for the same reason.
  *
- * `topInset` is left at the engine's zero, so a `%` detent is a fraction of the
+ * `topInset` is left at the engine's zero, so a `%` snap point is a fraction of the
  * whole window — the same fraction it was before this rewrite.
  */
 function BottomSheetRoot({
 	bottomInset,
-	onDetentHaptic = detentHaptic,
+	onSnapPointHaptic = snapPointHaptic,
 	onCloseHaptic = closeHaptic,
 	...props
 }: BottomSheetProps): ReactElement {
@@ -78,7 +78,7 @@ function BottomSheetRoot({
 		<Headless
 			bottomInset={bottomInset ?? insets.bottom}
 			onCloseHaptic={onCloseHaptic}
-			onDetentHaptic={onDetentHaptic}
+			onSnapPointHaptic={onSnapPointHaptic}
 			{...props}
 		/>
 	);

package/src/components/bottom-sheet/bottom-sheet.variants.test.ts

@@ -112,7 +112,7 @@ describe("every token the slots name", () => {
 });
 
 describe("the backdrop indices", () => {
-	test("show the scrim from the first detent and hide it only when closed", () => {
+	test("show the scrim from the first snap point and hide it only when closed", () => {
 		// A modal sheet has no resting state: presented or gone.
 		expect(BOTTOM_SHEET_BACKDROP_INDICES.appearsOnIndex).toBe(0);
 		expect(BOTTOM_SHEET_BACKDROP_INDICES.disappearsOnIndex).toBe(-1);
@@ -198,7 +198,7 @@ describe("bottomSheetVariants slots", () => {
 	test("a pinned footer writes its vertical padding as the engine's prop, never a class", () => {
 		// The engine measures the footer's inner box into the sheet's height, and
 		// padding handed to its `padding` prop lands on that box. A class on the
-		// outer view would be height the detent never counts.
+		// outer view would be height the snap point never counts.
 		expect(SLOTS.stickyFooter()).not.toMatch(/\bp[tby]?-[\d.]+\b/);
 		expect(BOTTOM_SHEET_FOOTER_PADDING).toBeGreaterThan(0);
 	});

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

@@ -21,10 +21,10 @@ export const BOTTOM_SHEET_OVERLAY_TOKEN = "overlay";
 export const BOTTOM_SHEET_OVERLAY_OPACITY = 1;
 
 /**
- * The detent indices the scrim appears and disappears on.
+ * The snap point indices the scrim appears and disappears on.
  *
  * A modal sheet has no resting state: it is either presented or gone, so the
- * scrim belongs from the FIRST detent (`0`) and is only absent when the sheet
+ * scrim belongs from the FIRST snap point (`0`) and is only absent when the sheet
  * is closed (`-1`). These are the engine's own defaults too; they are named
  * here so the test that pins them has something to read.
  */
@@ -43,7 +43,7 @@ export const BOTTOM_SHEET_CLOSE_HIT_SLOP = 8;
  * The padding a pinned footer's measured box carries.
  *
  * A number rather than a `p-4`, because it is handed to the engine's `padding`
- * prop: the engine measures the footer's inner box into the dynamic detent,
+ * prop: the engine measures the footer's inner box into the dynamic snap point,
  * and padding written there is counted where a class on the outer view would
  * not be. The horizontal gutter still comes from the `stickyFooter` slot, which
  * is merged after it.

package/src/components/collapsible/AGENTS.md

@@ -23,7 +23,7 @@ section first. What follows is only where a standalone disclosure differs.
 | `collapsible.context.tsx` | `CollapsibleContext`, `useCollapsible` and the internal part hook |
 | `collapsible.types.ts` | `CollapsibleTextProps`, shared by the title, description and trigger |
 | `collapsible.variants.ts` | Pure `tv()` slots, the constants, the toggle and the accessibility resolver — no RN imports |
-| `collapsible.variants.test.ts` | |
+| `collapsible.variants.test.ts` | `collapsibleTravelTarget`, pinned equal to the accordion's, and the JS-thread `contentHeight.value` sweep |
 
 ## Design
 
@@ -41,9 +41,14 @@ section first. What follows is only where a standalone disclosure differs.
   is the only thing that imports both, and tests are not shipped.
 - **The root owns the state and the travel.** With no item layer, what
   `Accordion.Item` owns — `progress`, `contentHeight`, the spring, the
-  `onMeasured` re-run counter — lives on the root. The race that counter closes
+  `isMeasured` state `onMeasured` flips — lives on the root. The race it closes
   (`onLayout` landing either side of React's effects) is the same one, so the
   panel reports its first measurement and never starts the spring itself.
+- **Nothing on the JS thread reads `contentHeight.value`** — the accordion's
+  Release-build bug, in the same shape: a JS read can lag the panel's queued
+  write, see `COLLAPSIBLE_UNMEASURED`, and leave the panel shut. "Measured" is
+  React state and the decision is `collapsibleTravelTarget`; the test sweeps both
+  files. See the accordion's AGENTS.md.
 - **The disabled fade lands on the root.** Never on the trigger, which is a
   `Pressable` whose `Animated.View` writes `opacity` every frame; the accordion
   fades its item for the same reason, and a collapsible's root is its item.

package/src/components/collapsible/collapsible-content.tsx

@@ -2,12 +2,7 @@ import { type ReactElement, type ReactNode, useCallback, useState } from "react"
 import { type LayoutChangeEvent, StyleSheet, View, type ViewProps } from "react-native";
 import Animated, { interpolate, useAnimatedStyle } from "react-native-reanimated";
 import { useCollapsiblePart } from "./collapsible.context";
-import {
-	COLLAPSIBLE_CONTENT_FADE,
-	COLLAPSIBLE_UNMEASURED,
-	collapsibleVariants,
-	resolveCollapsibleAccessibility,
-} from "./collapsible.variants";
+import { COLLAPSIBLE_CONTENT_FADE, collapsibleVariants, resolveCollapsibleAccessibility } from "./collapsible.variants";
 
 export type CollapsibleContentProps = Omit<ViewProps, "style"> & {
 	className?: string;
@@ -47,13 +42,15 @@ export function CollapsibleContent({ className, children, ...props }: Collapsibl
 
 	const handleLayout = useCallback(
 		(event: LayoutChangeEvent) => {
-			const wasMeasured = contentHeight.value > COLLAPSIBLE_UNMEASURED;
 			contentHeight.value = event.nativeEvent.layout.height;
-			if (wasMeasured) return;
+			// "First" is this component's own state, never `contentHeight.value`: the
+			// write above is queued onto the UI runtime, and a read straight after it
+			// can still see the old value.
+			if (isMeasured) return;
 			setMeasured(true);
 			onMeasured();
 		},
-		[contentHeight, onMeasured]
+		[contentHeight, isMeasured, onMeasured]
 	);
 
 	const clipStyle = useAnimatedStyle(() => ({

package/src/components/collapsible/collapsible.context.tsx

@@ -18,13 +18,18 @@ export type CollapsibleContextValue = {
 	 * and the indicator's rotation — so they cannot drift out of step by a frame.
 	 */
 	progress: SharedValue<number>;
-	/** The panel's natural height in points, or {@link COLLAPSIBLE_UNMEASURED} until it has reported. */
+	/**
+	 * The panel's natural height in points, or {@link COLLAPSIBLE_UNMEASURED} until it
+	 * has reported. Read on the UI runtime only, by the height style — a JS-thread read
+	 * can lag the panel's write. See {@link onMeasured}.
+	 */
 	contentHeight: SharedValue<number>;
 	/**
 	 * Told by the panel that it has measured itself for the first time.
 	 *
-	 * Internal machinery: the root is the only owner of the spring, and this gives
-	 * its effect a reason to re-run once there is a height to travel against. The
+	 * Internal machinery: the root is the only owner of the spring, and this flips
+	 * its `isMeasured` state — the reason its effect re-runs once there is a height
+	 * to travel against, and how it knows, never by reading `contentHeight`. The
 	 * panel cannot start the spring itself — `onLayout` lands either side of
 	 * React's effects, and a spring started there is sometimes cancelled by the
 	 * cleanup of the effect it raced. `Accordion.Item`'s `onMeasured`, verbatim.

package/src/components/collapsible/collapsible.tsx

@@ -10,6 +10,7 @@ import {
 	COLLAPSIBLE_UNMEASURED,
 	type CollapsibleSize,
 	type CollapsibleVariant,
+	collapsibleTravelTarget,
 	collapsibleVariants,
 	toggleCollapsibleOpen,
 } from "./collapsible.variants";
@@ -79,21 +80,22 @@ function CollapsibleRoot({
 	const progress = useSharedValue(isOpen ? 1 : 0);
 	const contentHeight = useSharedValue(COLLAPSIBLE_UNMEASURED);
 
-	// Bumped the first time the panel reports a height, purely to re-run the
-	// effect below. See `onMeasured` on the context.
-	const [measurements, setMeasurements] = useState(0);
-	const onMeasured = useCallback(() => setMeasurements((count) => count + 1), []);
+	// Whether the panel has ever reported a height — React state, never a JS-thread
+	// read of `contentHeight`, which can lag the write. See `collapsibleTravelTarget`
+	// and `onMeasured` on the context.
+	const [isMeasured, setMeasured] = useState(false);
+	const onMeasured = useCallback(() => setMeasured(true), []);
 
 	// The first open of a panel that has never mounted has no height to travel
-	// against, so that run bails and the measurement that follows brings it back.
-	// biome-ignore lint/correctness/useExhaustiveDependencies: `measurements` is the re-run trigger, see above
+	// against, so that run waits and the measurement that follows brings it back.
 	useEffect(() => {
-		if (isOpen && contentHeight.value === COLLAPSIBLE_UNMEASURED) return;
+		const target = collapsibleTravelTarget({ isMeasured, isOpen });
+		if (target === null) return;
 
-		progress.value = withSpring(isOpen ? 1 : 0, COLLAPSIBLE_SPRING);
+		progress.value = withSpring(target, COLLAPSIBLE_SPRING);
 
 		return () => cancelAnimation(progress);
-	}, [contentHeight, isOpen, measurements, progress]);
+	}, [isMeasured, isOpen, progress]);
 
 	const context = useMemo<CollapsibleContextValue>(
 		() => ({ contentHeight, isDisabled, isOpen, onMeasured, progress, size, toggle, variant }),

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

@@ -9,8 +9,10 @@ import {
 	ACCORDION_SIZES,
 	ACCORDION_SPRING,
 	ACCORDION_VARIANTS,
+	accordionTravelTarget,
 	accordionVariants,
 } from "../accordion/accordion.variants";
+import { CONTENT_HEIGHT_READ, jsThreadSource } from "../accordion/accordion.variants.test";
 import { ICON_SIZES } from "../icon/icon.variants";
 import {
 	COLLAPSIBLE_CONTENT_FADE,
@@ -24,6 +26,7 @@ import {
 	COLLAPSIBLE_SPRING,
 	COLLAPSIBLE_UNMEASURED,
 	COLLAPSIBLE_VARIANTS,
+	collapsibleTravelTarget,
 	collapsibleVariants,
 	resolveCollapsibleAccessibility,
 	toggleCollapsibleOpen,
@@ -300,3 +303,36 @@ describe("collapsible and accordion move alike", () => {
 		}
 	});
 });
+
+describe("collapsibleTravelTarget", () => {
+	test("an open waits for the panel's first measurement", () => {
+		expect(collapsibleTravelTarget({ isOpen: true, isMeasured: false })).toBeNull();
+	});
+
+	test("an open travels to 1 once the panel has measured", () => {
+		expect(collapsibleTravelTarget({ isOpen: true, isMeasured: true })).toBe(1);
+	});
+
+	test("a close never waits, measured or not", () => {
+		expect(collapsibleTravelTarget({ isOpen: false, isMeasured: false })).toBe(0);
+		expect(collapsibleTravelTarget({ isOpen: false, isMeasured: true })).toBe(0);
+	});
+
+	test("agrees with the accordion's rule on every input", () => {
+		for (const isOpen of [false, true]) {
+			for (const isMeasured of [false, true]) {
+				expect(collapsibleTravelTarget({ isOpen, isMeasured })).toBe(
+					accordionTravelTarget({ isExpanded: isOpen, isMeasured })
+				);
+			}
+		}
+	});
+});
+
+describe("the measured height is never read on the JS thread", () => {
+	// `Accordion`'s Release-build bug, in the same two files: a JS-thread read straight after the
+	// panel's `onLayout` wrote the height can still see `COLLAPSIBLE_UNMEASURED`.
+	test.each(["collapsible.tsx", "collapsible-content.tsx"])("%s", (file) => {
+		expect(jsThreadSource(join(import.meta.dirname, file))).not.toMatch(CONTENT_HEIGHT_READ);
+	});
+});

package/src/components/collapsible/collapsible.variants.ts

@@ -55,12 +55,33 @@ export const COLLAPSIBLE_INDICATOR_ROTATION = { collapsed: 0, expanded: 180 } as
 /**
  * What the measured height holds before the panel has ever reported its layout.
  *
- * Negative rather than zero: a panel that measured `0` is a real answer, and
- * treating it as "still waiting" would never start the spring. Only a value no
- * layout can produce can mean *unmeasured*, so the height style floors it.
+ * Negative rather than zero: a panel that measured `0` is a real answer and still
+ * opens. Only a value no layout can produce can mean *unmeasured*, so the height
+ * style floors it. Whether the panel *has* measured is never decided by comparing
+ * against this on the JS thread — see {@link collapsibleTravelTarget}.
  */
 export const COLLAPSIBLE_UNMEASURED = -1;
 
+/**
+ * Where the root's `progress` should spring to, or `null` to wait — only an open,
+ * and only before the panel's first measurement.
+ *
+ * `isMeasured` is React state, never a JS-thread read of the measured height: the
+ * panel's write is queued onto the UI runtime, and a read straight after it can
+ * still see {@link COLLAPSIBLE_UNMEASURED} — a Release build does, every time, and
+ * the panel stays shut. `accordionTravelTarget`, restated.
+ */
+export function collapsibleTravelTarget({
+	isOpen,
+	isMeasured,
+}: {
+	isOpen: boolean;
+	isMeasured: boolean;
+}): 0 | 1 | null {
+	if (!isOpen) return 0;
+	return isMeasured ? 1 : null;
+}
+
 /**
  * The window of the travel the panel's opacity ramps across — ahead of the
  * height, so the content is legible for most of an expand rather than half

package/src/components/provider/AGENTS.md

@@ -14,9 +14,9 @@ everything — a root layout, an `App.tsx`.
 
 ## Design
 
-- **Four layers, outermost first**: `GestureHandlerRootView` →
-  `SafeAreaProvider` → `KeyboardProvider` → `<KeyboardStateSync />` beside the
-  children. The order is not stylistic. The gesture root has to be an ancestor
+- **Five layers, outermost first**: `GestureHandlerRootView` →
+  `SafeAreaProvider` → `KeyboardProvider` → `<KeyboardStateSync />` beside
+  `CalmMotionProvider`, which wraps the children. The order is not stylistic. The gesture root has to be an ancestor
   native view of every handler a `Pressable` creates, and its absence is
   *silent* — no error, no warning, presses simply stop landing.
   `KeyboardStateSync` has to be a CHILD of `KeyboardProvider`, because it calls
@@ -67,6 +67,15 @@ everything — a root layout, an `App.tsx`.
   `BottomSheet.Portal` still renders, where it is written, as an inline sheet.
   The previous sheet library was a required peer while this component mounted
   its modal provider; nothing imports it any more.
+- **`isMotionCalm` is a behaviour prop, not a layer-named one.** It feeds
+  `CalmMotionProvider` (`hooks/use-calm-motion.tsx`), which `useCalmMotion()`
+  reads beside the OS reduce-motion setting. It exists for E2E builds: a runner
+  that waits for the screen to settle before each gesture (Argent waits up to
+  3 s) pays the whole wait on a screen holding a never-ending loop. Only
+  decorative loops ask — `Skeleton` today; `Spinner` and an indeterminate
+  `Progress` are the behaviour and keep moving. The context defaults to `false`,
+  so a component used without this provider (a `delacour add` copy in an app
+  with its own stack) still honours reduce motion.
 - **Deliberately not idempotent.** It does not detect an enclosing copy of
   itself. Nesting `GestureHandlerRootView` costs a `View`; nesting
   `SafeAreaProvider` seeds from the parent's insets and costs a native view;
@@ -87,7 +96,7 @@ everything — a root layout, an `App.tsx`.
   per-subpath and survives intact: `/button` still pulls nothing
   keyboard-related.
 - **Nothing here for `bun test`, and no `provider.variants.ts` to give it
-  some.** The component is four nested elements and one default parameter;
+  some.** The component is five nested elements and one default parameter;
   extracting a `resolveInitialMetrics()` would be a unit test of `??`. The rule
   that pure decisions live in a `*.variants.ts` has no decision here to
   relocate.

package/src/components/provider/provider.tsx

@@ -3,6 +3,7 @@ import type { StyleProp, ViewStyle } from "react-native";
 import { GestureHandlerRootView } from "react-native-gesture-handler";
 import { KeyboardProvider } from "react-native-keyboard-controller";
 import { initialWindowMetrics, type Metrics, SafeAreaProvider } from "react-native-safe-area-context";
+import { CalmMotionProvider } from "../../hooks/use-calm-motion";
 import { KeyboardStateSync } from "../../hooks/use-keyboard-state-sync";
 
 export type DelacourProviderProps = {
@@ -20,6 +21,16 @@ export type DelacourProviderProps = {
 	 * `null` is a value here rather than an absence.
 	 */
 	initialMetrics?: Metrics | null;
+	/**
+	 * Hold every decorative loop still — a skeleton's shimmer or pulse — whatever
+	 * the OS reduce-motion setting says. Defaults to `false`.
+	 *
+	 * For an E2E build. A test runner that waits for the screen to stop moving
+	 * before each gesture (Argent, Detox, Maestro) pays its whole timeout on any
+	 * screen holding a loop that never ends. Motion that *is* the behaviour — a
+	 * `Spinner`, an indeterminate `Progress` — keeps moving either way.
+	 */
+	isMotionCalm?: boolean;
 	/**
 	 * Style for the outermost `GestureHandlerRootView`.
 	 *
@@ -37,7 +48,7 @@ export type DelacourProviderProps = {
  * Mount it ONCE, around everything — a root layout, an `App.tsx`. It is not
  * idempotent and does not detect an enclosing copy of itself; see AGENTS.md.
  *
- * Four layers, outermost first, and the order is not stylistic:
+ * Five layers, outermost first, and the order is not stylistic:
  *
  * 1. `GestureHandlerRootView` — an ancestor native view every gesture handler
  *    `Pressable` creates has to attach to. Its absence is silent: no error, no
@@ -51,6 +62,9 @@ export type DelacourProviderProps = {
  *    `will` events, so a keyboard that vanishes without one — an interactive
  *    dismiss interrupted by navigation, a stack pop, an app suspend — leaves
  *    every screen in the app believing it is still open.
+ * 5. `CalmMotionProvider` — the app's `isMotionCalm`, for `useCalmMotion()`.
+ *    Pure context, no native view, so it wraps `{children}` alone — innermost,
+ *    where a new layer goes.
  *
  * **`BottomSheetProvider` is not here, and the app mounts it.** The sheet's
  * engine, `@delacour/react-native-bottom-sheet`, is an optional peer of this
@@ -92,10 +106,16 @@ export type DelacourProviderProps = {
  * // app that launches into a rotated or split-screen window and cannot
  * // tolerate one stale frame.
  * <DelacourProvider initialMetrics={null}>{children}</DelacourProvider>
+ *
+ * @example
+ * // An E2E build: decorative loops hold still so the test runner never waits
+ * // out a shimmer. `IS_E2E` is the app's own build flag.
+ * <DelacourProvider isMotionCalm={IS_E2E}>{children}</DelacourProvider>
  */
 export function DelacourProvider({
 	children,
 	initialMetrics = initialWindowMetrics,
+	isMotionCalm = false,
 	style,
 }: DelacourProviderProps): ReactElement {
 	return (
@@ -103,7 +123,7 @@ export function DelacourProvider({
 			<SafeAreaProvider initialMetrics={initialMetrics}>
 				<KeyboardProvider>
 					<KeyboardStateSync />
-					{children}
+					<CalmMotionProvider isMotionCalm={isMotionCalm}>{children}</CalmMotionProvider>
 				</KeyboardProvider>
 			</SafeAreaProvider>
 		</GestureHandlerRootView>

package/src/components/skeleton/AGENTS.md

@@ -78,9 +78,12 @@ with a glint sweeping across it, or a pulse, on the UI thread. Compound root plu
   line into a full one, that line's glint sat off-centre and swept visibly out
   of step with the rest. `StyleSheet.absoluteFill` plus
   `preserveAspectRatio="none"` makes the native view follow the band.
-- **Reduce-motion stills the skeleton, it does not hide it.**
-  `resolveSkeletonAnimation` returns `none` while the OS setting is on, and the
-  clock is never started. The shape is the message: a placeholder that stops
+- **Calm motion stills the skeleton, it does not hide it.**
+  `resolveSkeletonAnimation` returns `none` while `useCalmMotion()` is true — the
+  OS reduce-motion setting, or `DelacourProvider`'s `isMotionCalm` — and the
+  clock is never started. The second half is for E2E builds: a test runner that
+  waits for the screen to settle before each gesture pays its whole timeout on a
+  screen holding a shimmer that never ends. The shape is the message: a placeholder that stops
   moving still reads as content on its way. The clock's own timing sets
   `ReduceMotion.Never` because the decision has already been made one level up —
   under the default `System` policy `withTiming` completes instantly and

package/src/components/skeleton/skeleton-group.tsx

@@ -1,6 +1,6 @@
 import { type ReactElement, type ReactNode, useMemo } from "react";
 import { View, type ViewProps } from "react-native";
-import { useReducedMotion } from "react-native-reanimated";
+import { useCalmMotion } from "../../hooks/use-calm-motion";
 import { cn } from "../../lib/cn";
 import { type SkeletonGroupContextValue, SkeletonGroupProvider } from "./skeleton.context";
 import { resolveSkeletonAccessibility, resolveSkeletonAnimation, type SkeletonAnimation } from "./skeleton.variants";
@@ -38,8 +38,8 @@ export function SkeletonGroup({
 	children,
 	...props
 }: SkeletonGroupProps): ReactElement {
-	const isReduceMotion = useReducedMotion();
-	const resolvedAnimation = resolveSkeletonAnimation(animation, isReduceMotion);
+	const isCalm = useCalmMotion();
+	const resolvedAnimation = resolveSkeletonAnimation(animation, isCalm);
 	const isRunning = isLoading && resolvedAnimation !== "none";
 	const progress = useSkeletonClock(isRunning);
 

package/src/components/skeleton/skeleton.tsx

@@ -1,12 +1,7 @@
 import { type ReactElement, type ReactNode, useEffect } from "react";
 import { View, type ViewProps } from "react-native";
-import Animated, {
-	useAnimatedRef,
-	useAnimatedStyle,
-	useReducedMotion,
-	useSharedValue,
-	withTiming,
-} from "react-native-reanimated";
+import Animated, { useAnimatedRef, useAnimatedStyle, useSharedValue, withTiming } from "react-native-reanimated";
+import { useCalmMotion } from "../../hooks/use-calm-motion";
 import { cn } from "../../lib/cn";
 import { useSkeletonGroup } from "./skeleton.context";
 import {
@@ -29,7 +24,7 @@ export type SkeletonProps = Omit<ViewProps, "children"> & {
 	/**
 	 * `shimmer` sweeps a glint across the placeholder, `pulse` breathes its
 	 * opacity, `none` holds it still. Inherited from an enclosing `Skeleton.Group`,
-	 * then `shimmer`. Every animation stills under the OS reduce-motion setting.
+	 * then `shimmer`. Every animation stills under the OS reduce-motion setting, and under `DelacourProvider`'s `isMotionCalm`.
 	 */
 	animation?: SkeletonAnimation;
 	/**
@@ -63,10 +58,10 @@ function SkeletonRoot({
 	...props
 }: SkeletonProps): ReactElement {
 	const group = useSkeletonGroup();
-	const isReduceMotion = useReducedMotion();
+	const isCalm = useCalmMotion();
 
 	const loading = isLoading ?? group?.isLoading ?? true;
-	const resolvedAnimation = resolveSkeletonAnimation(animation ?? group?.animation, isReduceMotion);
+	const resolvedAnimation = resolveSkeletonAnimation(animation ?? group?.animation, isCalm);
 	const isAnimating = loading && resolvedAnimation !== "none";
 
 	// One clock drives either animation, so a group's clock serves every

package/src/components/skeleton/skeleton.variants.ts

@@ -61,16 +61,14 @@ export const SKELETON_SHIMMER_STOPS: readonly SkeletonShimmerStop[] = [
 /**
  * The animation a skeleton actually runs.
  *
- * Reduce-motion stills every animation rather than hiding the placeholder: the
- * shape is the message, and a shape that stops moving still reads as content on
- * its way. The clock then never starts, which is also why the timing itself can
- * set `ReduceMotion.Never` — see AGENTS.md.
+ * Calm motion — the OS reduce-motion setting, or an app's `isMotionCalm` — stills
+ * every animation rather than hiding the placeholder: the shape is the message,
+ * and a shape that stops moving still reads as content on its way. The clock then
+ * never starts, which is also why the timing itself can set `ReduceMotion.Never` —
+ * see AGENTS.md.
  */
-export function resolveSkeletonAnimation(
-	animation: SkeletonAnimation | undefined,
-	isReduceMotion: boolean
-): SkeletonAnimation {
-	if (isReduceMotion) return "none";
+export function resolveSkeletonAnimation(animation: SkeletonAnimation | undefined, isCalm: boolean): SkeletonAnimation {
+	if (isCalm) return "none";
 	return animation ?? SKELETON_FALLBACK_ANIMATION;
 }
 

package/src/hooks/use-calm-motion.tsx

@@ -0,0 +1,31 @@
+import { createContext, type ReactElement, type ReactNode, useContext } from "react";
+import { useReducedMotion } from "react-native-reanimated";
+import { calmMotion } from "../lib/calm-motion";
+
+const CalmMotionContext = createContext(false);
+
+export type CalmMotionProviderProps = {
+	/** Hold every decorative loop beneath this still, whatever the OS setting. */
+	isMotionCalm: boolean;
+	children: ReactNode;
+};
+
+/**
+ * Asks every decorative loop beneath it to hold still — for an E2E build, whose test runner waits
+ * for the screen to stop moving before each gesture. `DelacourProvider` mounts it from its own
+ * `isMotionCalm`; mount it by hand only in an app that composes its providers itself.
+ *
+ * Optional: without one, {@link useCalmMotion} follows the OS reduce-motion setting alone.
+ */
+export function CalmMotionProvider({ isMotionCalm, children }: CalmMotionProviderProps): ReactElement {
+	return <CalmMotionContext.Provider value={isMotionCalm}>{children}</CalmMotionContext.Provider>;
+}
+
+/**
+ * Whether decorative motion should hold still, for this device and this app: the one place a
+ * component asks whether to loop. See `calmMotion` for what counts as decorative.
+ */
+export function useCalmMotion(): boolean {
+	return calmMotion({ isMotionCalm: useContext(CalmMotionContext), isReduceMotion: useReducedMotion() });
+}
+CalmMotionProvider.displayName = "DelacourUI.CalmMotionProvider";

package/src/lib/calm-motion.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "bun:test";
+import { calmMotion } from "./calm-motion";
+
+describe("calmMotion", () => {
+	test("moves when neither the OS nor the app asks for stillness", () => {
+		expect(calmMotion({ isReduceMotion: false, isMotionCalm: false })).toBe(false);
+	});
+
+	test("holds still under the OS reduce-motion setting", () => {
+		expect(calmMotion({ isReduceMotion: true, isMotionCalm: false })).toBe(true);
+	});
+
+	test("holds still when the app asks, whatever the OS says", () => {
+		expect(calmMotion({ isReduceMotion: false, isMotionCalm: true })).toBe(true);
+		expect(calmMotion({ isReduceMotion: true, isMotionCalm: true })).toBe(true);
+	});
+});

package/src/lib/calm-motion.ts

@@ -0,0 +1,23 @@
+/**
+ * Whether decorative motion holds still: under the OS reduce-motion setting, or whenever the app
+ * asks — `DelacourProvider`'s `isMotionCalm`.
+ *
+ * The app's half is for automation, not accessibility. A UI test runner that waits for the screen
+ * to stop moving before every gesture (Argent waits up to 3 s, Detox and Maestro idle-wait the
+ * same way) pays the whole wait on any screen holding a loop that never ends — a shimmering
+ * skeleton turns every tap there into a timeout. An E2E build passes `isMotionCalm` and the loops
+ * hold still.
+ *
+ * Only motion that is decoration asks. Motion that *is* the behaviour — a spinner saying work is
+ * in flight, a progress bar a reader reads — keeps moving: stilling it would change what the
+ * screen says.
+ */
+export function calmMotion({
+	isReduceMotion,
+	isMotionCalm,
+}: {
+	isReduceMotion: boolean;
+	isMotionCalm: boolean;
+}): boolean {
+	return isReduceMotion || isMotionCalm;
+}