@rootnative/inertia 0.0.9 → 0.0.10

package/src/motion/createMotionComponent.tsx

@@ -21,7 +21,7 @@ import {
   useNamedTransitions,
   useShouldReduceMotion,
 } from '../config'
-import { isFocusVisible } from '../gestures'
+import { installFocusVisibility, isFocusVisible } from '../gestures'
 import {
   layersToPayload,
   normalizeBoxShadow,
@@ -47,6 +47,7 @@ import { useStaggerDelay } from '../stagger'
 import {
   applyDelay,
   isTopLevelTransition,
+  repeatIterationsOf,
   resolveAnimatableValue,
   resolveTransition,
   stableSig,
@@ -271,6 +272,18 @@ const SHARED_STYLE_KEY_SET = new Set<AnimatableKey>(SHARED_STYLE_KEYS)
  */
 type AnimatableSlotValue = number | string | BoxShadowPayload
 
+/**
+ * The keys one instance animates plus the three flags the worklet branches
+ * on. Grown monotonically on the JS thread and mirrored to the UI thread
+ * through a shared value — see `activeSetSV` in the factory.
+ */
+type ActiveKeySet = {
+  keys: readonly AnimatableKey[]
+  hasTransform: boolean
+  hasShadowOffset: boolean
+  hasBoxShadow: boolean
+}
+
 /**
  * Resting `boxShadow` — no shadow at all. Frozen and hoisted so every
  * primitive shares one reference and an untouched slot never allocates.
@@ -603,10 +616,10 @@ export function createMotionComponent<C extends ComponentType<any>>(
       //      render silently dropped the new key (its SV updated, but the
       //      worklet — which iterates this set — never read it).
       //
-      // Growing-only keeps the worklet stable: the `activeKeysRef.current` array
-      // identity only changes on the renders that actually add a key, so the
-      // `useAnimatedStyle` worklet (which reads `.current` each frame) sees the
-      // expansion without churning frame-to-frame.
+      // Growing-only keeps the worklet stable: the set object only changes on
+      // the renders that actually add a key. The worklet reads it through a
+      // shared value (`activeSetSV`, below), so an expansion crosses to the UI
+      // thread once per growth and nothing churns frame-to-frame.
       const hasLayoutId = layoutId !== undefined
 
       // The static `style`, flattened at most once per render and only when
@@ -668,14 +681,11 @@ export function createMotionComponent<C extends ComponentType<any>>(
         }
       }
 
-      const activeKeysRef = useRef<readonly AnimatableKey[] | null>(null)
-      const hasTransformRef = useRef<boolean>(false)
-      const hasShadowOffsetRef = useRef<boolean>(false)
-      const hasBoxShadowRef = useRef<boolean>(false)
+      const activeSetRef = useRef<ActiveKeySet | null>(null)
       // Expand the active set only when this render touched a key we haven't
-      // recorded yet. When nothing new appears we keep the existing array
-      // identity so the worklet's captured ref doesn't see a fresh value.
-      const prevActive = activeKeysRef.current
+      // recorded yet. When nothing new appears we keep the existing object
+      // identity so the JS-side readers below see a stable value.
+      const prevActive = activeSetRef.current?.keys ?? null
       let grew = prevActive === null
       if (!grew && prevActive) {
         for (const k of touched) {
@@ -688,14 +698,13 @@ export function createMotionComponent<C extends ComponentType<any>>(
       if (grew) {
         const merged = new Set<AnimatableKey>(prevActive ?? [])
         for (const k of touched) merged.add(k)
-        activeKeysRef.current = ALL_KEYS.filter((k) => merged.has(k))
-        hasTransformRef.current = activeKeysRef.current.some((k) =>
-          TRANSFORM_KEY_SET.has(k),
-        )
-        hasShadowOffsetRef.current = activeKeysRef.current.some((k) =>
-          SHADOW_OFFSET_KEY_SET.has(k),
-        )
-        hasBoxShadowRef.current = activeKeysRef.current.includes('boxShadow')
+        const keys = ALL_KEYS.filter((k) => merged.has(k))
+        activeSetRef.current = {
+          keys,
+          hasTransform: keys.some((k) => TRANSFORM_KEY_SET.has(k)),
+          hasShadowOffset: keys.some((k) => SHADOW_OFFSET_KEY_SET.has(k)),
+          hasBoxShadow: keys.includes('boxShadow'),
+        }
         // Animating `boxShadow` alongside the native `shadow*` keys puts two
         // shadow systems on one element; whichever the underlying view resolves
         // last wins, and the result reads as a bug rather than a choice.
@@ -703,10 +712,8 @@ export function createMotionComponent<C extends ComponentType<any>>(
         // decides it, and this block only runs when that set grows.
         if (
           __DEV__ &&
-          hasBoxShadowRef.current &&
-          activeKeysRef.current.some(
-            (k) => k !== 'boxShadow' && k.startsWith('shadow'),
-          )
+          activeSetRef.current.hasBoxShadow &&
+          keys.some((k) => k !== 'boxShadow' && k.startsWith('shadow'))
         ) {
           warnOnce(
             'boxShadow-with-native-shadow',
@@ -717,6 +724,25 @@ export function createMotionComponent<C extends ComponentType<any>>(
           )
         }
       }
+      const activeKeys = activeSetRef.current!.keys
+
+      // The worklet's copy of the active set. It must be a shared value, not
+      // the ref above: react-native-worklets clones a captured plain object
+      // once, when the worklet is first serialised, and in dev it freezes the
+      // original so later writes to `.current` are dropped with a warning. A
+      // ref read inside the worklet therefore only ever sees the mount-time
+      // set, and a key added after mount drives its shared value but never
+      // reaches the screen (Worklet rule 2). The Jest mock runs the worklet on
+      // the JS thread, so only a device shows the difference. The write lives
+      // in an effect because Reanimated's strict mode warns on a shared-value
+      // write during render; it is declared before the value-driving effects
+      // below, so the grown set reaches the UI thread in the same commit as
+      // the first animation of the new key.
+      const activeSetSV = useSharedValue<ActiveKeySet>(activeSetRef.current!)
+      const activeSet = activeSetRef.current!
+      useEffect(() => {
+        if (activeSetSV.value !== activeSet) activeSetSV.value = activeSet
+      }, [activeSetSV, activeSet])
 
       // Which keys a record actually drives *right now*. Everything else in
       // the active set is there only because a gesture sub-state, an `exit`
@@ -741,7 +767,6 @@ export function createMotionComponent<C extends ComponentType<any>>(
       // Resting values pulled off the static `style`, for active keys nothing
       // has driven. Gated so the common `animate`-only instance never flattens
       // a style it has no use for.
-      const activeKeys = activeKeysRef.current!
       const everDriven = everDrivenRef.current
       const styleResting: Partial<Record<AnimatableKey, AnimatableSlotValue>> =
         {}
@@ -857,7 +882,7 @@ export function createMotionComponent<C extends ComponentType<any>>(
 
       const styleRestingSig = stableSig(styleResting)
       useEffect(() => {
-        for (const key of activeKeysRef.current!) {
+        for (const key of activeKeys) {
           if (everDrivenRef.current.has(key)) continue
           sharedValues[key].value = (styleResting[key] ??
             DEFAULT_RESTING[key]) as never
@@ -926,6 +951,11 @@ export function createMotionComponent<C extends ComponentType<any>>(
         (isExiting ? '|exit' : '') +
         (shouldReduceMotion ? '|rm' : '')
       const transitionSig = stableSig(transition)
+      // The callback factory skips callback installation when there is no
+      // `onAnimationEnd` and nothing to settle, so a handler that appears
+      // after mount needs the effect to run again. Keyed on presence, not
+      // identity: a changing handler is read through `onAnimationEndRef`.
+      const hasAnimationEnd = onAnimationEnd !== undefined
 
       // Stable ref to the live `safeToRemove` so the effect's settle-counter
       // closure can reach the latest <Presence> binding without retriggering.
@@ -943,6 +973,10 @@ export function createMotionComponent<C extends ComponentType<any>>(
           return
         }
 
+        // `done` doubles as the run token. When this effect re-runs, the
+        // cleanup below sets it, so the callbacks of the superseded animations
+        // — which Reanimated fires with `finished: false` as they are replaced
+        // — cannot drain this run's counter and release <Presence> early.
         let pending = 0
         let done = false
         const onSettle = () => {
@@ -1095,8 +1129,11 @@ export function createMotionComponent<C extends ComponentType<any>>(
         if (isExiting && pending === 0) {
           safeToRemoveRef.current?.()
         }
+        return () => {
+          done = true
+        }
         // eslint-disable-next-line react-hooks/exhaustive-deps
-      }, [baseSig, transitionSig])
+      }, [baseSig, transitionSig, hasAnimationEnd])
 
       // Per-layer progress: when a sub-state activation flips, animate its
       // progress SV 0↔1 with the layer's own transition (or the parent
@@ -1162,7 +1199,7 @@ export function createMotionComponent<C extends ComponentType<any>>(
         if (!hasLayoutId) return undefined
         const out: SharedStyleSnapshot = {}
         let any = false
-        for (const key of activeKeysRef.current!) {
+        for (const key of activeKeys) {
           if (!SHARED_STYLE_KEY_SET.has(key)) continue
           const v = sharedValues[key].value
           // Structured slots can't be carried, and a key nothing ever gave a
@@ -1186,10 +1223,11 @@ export function createMotionComponent<C extends ComponentType<any>>(
       const carry = sharedLayout.carry
 
       const animatedStyle = useAnimatedStyle(() => {
-        const activeKeys = activeKeysRef.current!
-        const hasTransform = hasTransformRef.current
-        const hasShadowOffset = hasShadowOffsetRef.current
-        const hasBoxShadow = hasBoxShadowRef.current
+        const activeSet = activeSetSV.value
+        const activeKeys = activeSet.keys
+        const hasTransform = activeSet.hasTransform
+        const hasShadowOffset = activeSet.hasShadowOffset
+        const hasBoxShadow = activeSet.hasBoxShadow
         const out: Record<string, unknown> = {}
         const transform: Array<Record<string, unknown>> = []
         // shadow-offset reassembly buffers. The two synthetic axis SVs feed in
@@ -1448,7 +1486,7 @@ type SharedValueMap = Record<AnimatableKey, SharedValue<AnimatableSlotValue>>
  * The ESLint exhaustive-deps rule can't see through the loop, hence the
  * disable — the invariant it would check for us is asserted above instead.
  *
- * Unused shared values are cheap; the worklet skips them via `activeKeysRef`.
+ * Unused shared values are cheap; the worklet skips them via `activeSetSV`.
  * Color keys are seeded with the initial color string so Reanimated's value
  * setter recognizes the slot as a color from the first `withSpring` /
  * `withTiming` call.
@@ -1805,12 +1843,9 @@ function stepCountOf(v: AnimatableValue<number | string> | undefined): number {
  */
 function totalIterationsOf(cfg: TransitionConfig | undefined): number {
   if (!cfg || cfg.type === 'no-animation' || cfg.type === 'decay') return 1
-  const r = cfg.repeat
-  if (r === undefined) return 1
-  if (r === 'infinite') return Number.POSITIVE_INFINITY
-  if (typeof r === 'number') return r
-  if (r.count === 'infinite') return Number.POSITIVE_INFINITY
-  return r.count
+  // Shares the resolver's count rule, so a `repeat: 0` that the resolver
+  // treats as "run once" is also counted as one iteration here.
+  return repeatIterationsOf(cfg.repeat)
 }
 
 /**
@@ -1880,16 +1915,23 @@ function resolveAnimateInput(
   variants: VariantsMap<unknown> | undefined,
   controllerKey: string | undefined,
 ): AnimateStyle<unknown> | undefined {
+  if (controllerKey !== undefined && animate !== undefined) {
+    warnOnce(
+      'controller-and-animate',
+      '[inertia] Both `controller` and `animate` are set on the same ' +
+        'primitive. The controller drives the animation and `animate` is ' +
+        'ignored — remove one of the two.',
+    )
+  }
   if (controllerKey !== undefined && variants && controllerKey in variants) {
     return variants[controllerKey]
   }
   if (typeof animate === 'string') {
     if (variants && animate in variants) return variants[animate]
-    if (__DEV__) {
-      console.warn(
-        `[inertia] animate="${animate}" but no matching variant. Did you forget to pass \`variants\`?`,
-      )
-    }
+    warnOnce(
+      `missing-variant:${animate}`,
+      `[inertia] animate="${animate}" but no matching variant. Did you forget to pass \`variants\`?`,
+    )
     return undefined
   }
   return animate as AnimateStyle<unknown> | undefined
@@ -2047,6 +2089,12 @@ function useGestureHandlers(
   const hasFocused = gesture?.focused ? 1 : 0
   const hasFocusVisible = gesture?.focusVisible ? 1 : 0
   const hasHovered = gesture?.hovered ? 1 : 0
+  // The web modality listeners attach on the first mount that tracks
+  // `focusVisible` — see `focusVisibility.ts` for why mount time is early
+  // enough and why import time is not an option.
+  useEffect(() => {
+    if (hasFocusVisible) installFocusVisibility()
+  }, [hasFocusVisible])
   return useMemo(() => {
     if (!gesture) return {}
     const handlers: GestureHandlers = {}

package/src/presence/Presence.tsx

@@ -9,6 +9,7 @@ import {
   useRef,
   useState,
 } from 'react'
+import { warnOnce } from '../internal/warnOnce'
 import { PresenceContext, type PresenceContextValue } from './PresenceContext'
 
 interface RenderEntry {
@@ -38,11 +39,10 @@ export function Presence({ children }: { children: ReactNode }) {
     Children.forEach(children, (child) => {
       if (!isValidElement(child)) return
       if (child.key === null) {
-        if (__DEV__) {
-          console.warn(
-            '[inertia] <Presence> children must have a `key`. Skipping a keyless child.',
-          )
-        }
+        warnOnce(
+          'presence-keyless-child',
+          '[inertia] <Presence> children must have a `key`. Skipping a keyless child.',
+        )
         return
       }
       out.push(child)
@@ -224,5 +224,3 @@ function PresenceItem({
     </PresenceContext.Provider>
   )
 }
-
-declare const __DEV__: boolean

package/src/touch/applyBounds.ts

@@ -0,0 +1,30 @@
+/**
+ * Clamp `value` to `[min, max]`. When `elastic > 0` the overshoot past a
+ * bound is scaled by `elastic` instead of hard-clamped, giving a rubber-band
+ * feel. `min` / `max` may be `undefined` to leave that side unbounded.
+ *
+ * Worklet, so it runs both inside a gesture-handler pan handler on the UI
+ * thread (`useDrag`) and from a JS-thread `PanResponder` callback
+ * (`useTouchDrag`).
+ *
+ * ```ts
+ * applyBounds(120, -100, 100, 0)    // 100
+ * applyBounds(120, -100, 100, 0.5)  // 110
+ * applyBounds(50, undefined, 100, 0) // 50
+ * ```
+ */
+export function applyBounds(
+  value: number,
+  min: number | undefined,
+  max: number | undefined,
+  elastic: number,
+): number {
+  'worklet'
+  if (min !== undefined && value < min) {
+    return elastic > 0 ? min + (value - min) * elastic : min
+  }
+  if (max !== undefined && value > max) {
+    return elastic > 0 ? max + (value - max) * elastic : max
+  }
+  return value
+}

package/src/touch/index.ts

@@ -8,6 +8,7 @@
  * prefer `useDrag` from `@rootnative/inertia-gestures` — its UI-thread
  * release path is more precise.
  */
+export { applyBounds } from './applyBounds'
 export { useTouchDrag } from './useTouchDrag'
 export type {
   TouchReleaseInfo,

package/src/touch/useTouchDrag.ts

@@ -1,15 +1,14 @@
-import { useMemo } from 'react'
+import { useMemo, useRef } from 'react'
 import {
   PanResponder,
   type PanResponderGestureState,
   type PanResponderInstance,
 } from 'react-native'
-import {
-  useAnimatedStyle,
-  useSharedValue,
-  type SharedValue,
-} from 'react-native-reanimated'
+import { useSharedValue, type SharedValue } from 'react-native-reanimated'
+import type { useAnimatedStyle } from 'react-native-reanimated'
 import { buildReleaseAnimation } from '../transitions'
+import { useTranslateStyle } from '../values/useTranslateStyle'
+import { applyBounds } from './applyBounds'
 import type { TransitionConfig } from '../types'
 
 /**
@@ -166,23 +165,17 @@ export function useTouchDrag(
   const top = constraints?.top
   const bottom = constraints?.bottom
   const elasticCoef = elastic
-  const { onDragStart, onDragEnd, onRelease } = options
+
+  // Callbacks are read through a ref at call time, so an inline arrow in
+  // `options` does not rebuild the PanResponder every render. PanResponder
+  // callbacks run on the JS thread, so a ref read is safe here.
+  const callbacksRef = useRef(options)
+  callbacksRef.current = options
 
   const responder = useMemo(
     () => buildResponder(),
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [
-      lockX,
-      lockY,
-      left,
-      right,
-      top,
-      bottom,
-      elasticCoef,
-      onDragStart,
-      onDragEnd,
-      onRelease,
-    ],
+    [lockX, lockY, left, right, top, bottom, elasticCoef],
   )
 
   // Hoisted out of the inline `useMemo` factory to keep the dep list readable
@@ -196,6 +189,7 @@ export function useTouchDrag(
       // `@rootnative/inertia-gestures` API (px/sec from gesture-handler).
       const vx = g.vx * 1000
       const vy = g.vy * 1000
+      const { onRelease, onDragEnd } = callbacksRef.current
       if (onRelease) {
         const result = onRelease({ x, y, velocity: { x: vx, y: vy } })
         if (result) {
@@ -228,7 +222,7 @@ export function useTouchDrag(
         startX.value = dragX.value
         startY.value = dragY.value
         isDragging.value = true
-        if (onDragStart) onDragStart()
+        callbacksRef.current.onDragStart?.()
       },
       onPanResponderMove: (_e, g) => {
         if (lockX) {
@@ -253,9 +247,7 @@ export function useTouchDrag(
     })
   }
 
-  const animatedStyle = useAnimatedStyle(() => ({
-    transform: [{ translateX: dragX.value }, { translateY: dragY.value }],
-  }))
+  const animatedStyle = useTranslateStyle(dragX, dragY)
 
   return {
     panHandlers: responder.panHandlers,
@@ -265,25 +257,3 @@ export function useTouchDrag(
     isDragging,
   }
 }
-
-/**
- * Clamp `value` to `[min, max]`. When `elastic > 0` the overshoot past a
- * bound is scaled by `elastic`, giving a rubber-band feel. `min` / `max`
- * may be `undefined` to leave that side unbounded.
- *
- * JS-thread (PanResponder callbacks are JS, not worklets).
- */
-function applyBounds(
-  value: number,
-  min: number | undefined,
-  max: number | undefined,
-  elastic: number,
-): number {
-  if (min !== undefined && value < min) {
-    return elastic > 0 ? min + (value - min) * elastic : min
-  }
-  if (max !== undefined && value > max) {
-    return elastic > 0 ? max + (value - max) * elastic : max
-  }
-  return value
-}

package/src/transitions/constants.ts

@@ -0,0 +1,14 @@
+/**
+ * Default `duration` for a `timing` transition that does not set one, in ms.
+ * Shared by the JS-thread resolver (`resolve.ts`) and the UI-thread builder
+ * (`runtime.ts`) so the two paths cannot drift apart.
+ */
+export const DEFAULT_TIMING_DURATION = 250
+
+/**
+ * Default `duration` for a `timing` layout transition (`layout` prop and
+ * `layoutId` shared-element legs), in ms. Layout moves cover more distance
+ * than a property tween, so the default is longer than
+ * `DEFAULT_TIMING_DURATION`.
+ */
+export const DEFAULT_LAYOUT_DURATION = 300

package/src/transitions/easing.ts

@@ -2,7 +2,11 @@
 // dep); Reanimated's own re-export is deprecated.
 import { isWorkletFunction } from 'react-native-worklets'
 import { warnNonWorkletOnce } from '../internal/nonWorkletWarning'
-import { type EasingInput } from '../types'
+import {
+  type EasingFunction,
+  type EasingFunctionFactory,
+  type EasingInput,
+} from '../types'
 
 /**
  * Reanimated 3.9+ validates that easing functions used in nested-transition
@@ -33,7 +37,7 @@ export function ensureWorkletEasing(
   // Reanimated 4 `EasingFunctionFactory` — unwrap via `.factory()` before
   // checking worklet status, so the wrapped fn (not the factory wrapper)
   // ends up in the transition config.
-  const fn = isEasingFactory(easing) ? easing.factory() : easing
+  const fn = unwrapEasingFactory(easing)
   if (isWorkletFunction(fn)) return fn
   warnNonWorkletOnce(
     'timing-easing',
@@ -46,13 +50,21 @@ export function ensureWorkletEasing(
   return wrapped
 }
 
-function isEasingFactory(
-  value: EasingInput,
-): value is { factory: () => (t: number) => number } {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'factory' in value &&
-    typeof (value as { factory: unknown }).factory === 'function'
-  )
+/**
+ * Return the easing function behind an `EasingInput`: a Reanimated 4
+ * `EasingFunctionFactory` is unwrapped through `.factory()`, a plain function
+ * passes through. Worklet, so `buildReleaseAnimation` can call it from a
+ * gesture `onEnd` handler on the UI thread.
+ */
+export function unwrapEasingFactory(easing: EasingInput): EasingFunction {
+  'worklet'
+  if (
+    typeof easing === 'object' &&
+    easing !== null &&
+    'factory' in easing &&
+    typeof (easing as { factory: unknown }).factory === 'function'
+  ) {
+    return (easing as EasingFunctionFactory).factory()
+  }
+  return easing as EasingFunction
 }

package/src/transitions/index.ts

@@ -1,9 +1,14 @@
 export {
   applyDelay,
+  applyRepeat,
+  normalizeRepeat,
+  repeatIterationsOf,
   resolveTransition,
   type AnimationCallback,
   type CallbackFactory,
+  type NormalizedRepeat,
 } from './resolve'
+export { DEFAULT_LAYOUT_DURATION, DEFAULT_TIMING_DURATION } from './constants'
 export { resolveAnimatableValue } from './resolveSequence'
 export { cubicBezier } from './cubicBezier'
 export { ensureWorkletEasing } from './easing'

package/src/transitions/keys.ts

@@ -14,8 +14,6 @@ export const TRANSITION_CONFIG_KEYS = new Set([
   'friction',
   'mass',
   'velocity',
-  'restSpeedThreshold',
-  'restDisplacementThreshold',
   'duration',
   'easing',
   'delay',

package/src/transitions/resolve.ts

@@ -6,8 +6,10 @@ import {
   withSpring,
   withTiming,
 } from 'react-native-reanimated'
+import { DEFAULT_TIMING_DURATION } from './constants'
 import { ensureWorkletEasing } from './easing'
 import { springToReanimated } from './spring'
+import { warnOnce } from '../internal/warnOnce'
 import {
   type DecayTransition,
   type RepeatConfig,
@@ -37,8 +39,6 @@ export type CallbackFactory = (
   step: number | undefined,
 ) => AnimationCallback | undefined
 
-const DEFAULT_TIMING_DURATION = 250
-
 function buildSpring(
   cfg: SpringTransition,
   toValue: number | string,
@@ -94,26 +94,101 @@ function buildOne(
   return buildSpring(cfg as SpringTransition, toValue, cb)
 }
 
+/**
+ * Normalised repeat: `count` is the total number of iterations
+ * (`Number.POSITIVE_INFINITY` for `'infinite'`), `alternate` is the resolved
+ * flag, `explicitAlternate` says whether the caller set `alternate` by hand.
+ */
+export interface NormalizedRepeat {
+  count: number
+  alternate: boolean
+  explicitAlternate: boolean
+}
+
+/**
+ * Reduce the three public `repeat` shapes to one record, or `undefined` when
+ * the animation runs once. A count below `1` is treated as "run once" and
+ * warns in dev: Reanimated's `withRepeat` reads `0` and negative counts as
+ * endless, so forwarding them would turn `repeat: 0` into an infinite loop.
+ */
+export function normalizeRepeat(
+  repeat: RepeatConfig | undefined,
+): NormalizedRepeat | undefined {
+  if (repeat === undefined) return undefined
+  if (repeat === 'infinite') {
+    return {
+      count: Number.POSITIVE_INFINITY,
+      alternate: true,
+      explicitAlternate: false,
+    }
+  }
+  const rawCount = typeof repeat === 'number' ? repeat : repeat.count
+  const alternate = typeof repeat === 'number' ? true : repeat.alternate
+  if (rawCount === 'infinite') {
+    return {
+      count: Number.POSITIVE_INFINITY,
+      alternate: alternate ?? true,
+      explicitAlternate: alternate !== undefined,
+    }
+  }
+  if (!(rawCount >= 1)) {
+    warnOnce(
+      `repeat-count:${String(rawCount)}`,
+      `[inertia] repeat count ${String(rawCount)} is below 1 — the ` +
+        `animation runs once. Use \`repeat: 2\` or more to repeat, or ` +
+        `\`repeat: 'infinite'\`. (Reanimated reads a count of 0 as endless, ` +
+        `so it is not forwarded.)`,
+    )
+    return undefined
+  }
+  return {
+    count: rawCount,
+    alternate: alternate ?? true,
+    explicitAlternate: alternate !== undefined,
+  }
+}
+
+/**
+ * Total number of iterations an animation built from `repeat` runs, including
+ * the first pass. `1` when there is no repeat or the count is below 1;
+ * `Number.POSITIVE_INFINITY` for `'infinite'`.
+ */
+export function repeatIterationsOf(repeat: RepeatConfig | undefined): number {
+  return normalizeRepeat(repeat)?.count ?? 1
+}
+
 /**
  * Wrap an animation in `withRepeat` per the unified `repeat` shape:
  *   - `number`              → finite count, alternating direction
  *   - `'infinite'`          → endless, alternating direction
  *   - `{ count, alternate }`→ explicit; `alternate` defaults to `true`
+ *
+ * Pass `{ sequence: true }` when `animation` is a `withSequence` result.
+ * Reanimated's `reverse` flag only swaps the wrapped animation's `toValue`,
+ * which a sequence ignores — it restarts at step 0 on every pass — so the
+ * flag is not forwarded for sequences. An explicit `alternate: true` on a
+ * sequence warns in dev; write the reverse steps into the sequence instead.
  */
 export function applyRepeat(
   animation: unknown,
   repeat: RepeatConfig | undefined,
+  options?: { sequence?: boolean },
 ) {
-  if (repeat === undefined) return animation
-  if (repeat === 'infinite') {
-    return withRepeat(animation as never, -1, true)
-  }
-  if (typeof repeat === 'number') {
-    return withRepeat(animation as never, repeat, true)
+  const r = normalizeRepeat(repeat)
+  if (r === undefined) return animation
+  const count = Number.isFinite(r.count) ? r.count : -1
+  if (options?.sequence) {
+    if (r.explicitAlternate && r.alternate) {
+      warnOnce(
+        'repeat-sequence-alternate',
+        '[inertia] repeat.alternate has no effect on a sequence — Reanimated ' +
+          'restarts a sequence at its first step on every pass. Append the ' +
+          'reverse steps to the sequence to alternate.',
+      )
+    }
+    return withRepeat(animation as never, count, false)
   }
-  const count = repeat.count === 'infinite' ? -1 : repeat.count
-  const alternate = repeat.alternate ?? true
-  return withRepeat(animation as never, count, alternate)
+  return withRepeat(animation as never, count, r.alternate)
 }
 
 /**