@rootnative/inertia 0.0.1 → 0.0.3

package/dist/index.mjs

@@ -1,21 +1,21 @@
 export { useGesture } from './chunk-RGNX6UZN.mjs';
-import { MotionView } from './chunk-6SMPIOIC.mjs';
-export { MotionView } from './chunk-6SMPIOIC.mjs';
-import { MotionText } from './chunk-JVBXPF2G.mjs';
-export { MotionText } from './chunk-JVBXPF2G.mjs';
-import { MotionImage } from './chunk-ALRHDFZE.mjs';
-export { MotionImage } from './chunk-ALRHDFZE.mjs';
-import { MotionPressable } from './chunk-NXDJZD6A.mjs';
-export { MotionPressable } from './chunk-NXDJZD6A.mjs';
-import { MotionScrollView } from './chunk-CWLFUYIY.mjs';
-export { MotionScrollView } from './chunk-CWLFUYIY.mjs';
-export { Presence, createMotionComponent, usePresence } from './chunk-DWCLIBYO.mjs';
+import { MotionView } from './chunk-BQQTHG2V.mjs';
+export { MotionView } from './chunk-BQQTHG2V.mjs';
+import { MotionText } from './chunk-SGUHE5CX.mjs';
+export { MotionText } from './chunk-SGUHE5CX.mjs';
+import { MotionImage } from './chunk-O22NXXCZ.mjs';
+export { MotionImage } from './chunk-O22NXXCZ.mjs';
+import { MotionPressable } from './chunk-46P57VMY.mjs';
+export { MotionPressable } from './chunk-46P57VMY.mjs';
+import { MotionScrollView } from './chunk-OQV66TBQ.mjs';
+export { MotionScrollView } from './chunk-OQV66TBQ.mjs';
+export { Presence, createMotionComponent, usePresence } from './chunk-CSODMRJ7.mjs';
 import { useShouldReduceMotion, resolveNamedTransition, useNamedTransitions, lookupNamedTransition } from './chunk-R63GIUNU.mjs';
 export { MotionConfig, resolveNamedTransition, useMotionConfig, useNamedTransitions, useShouldReduceMotion } from './chunk-R63GIUNU.mjs';
 import { stableSig, resolveTransition, springToReanimated, warnNonWorkletOnce } from './chunk-CY7Y64C3.mjs';
 export { buildReleaseAnimation, cubicBezier, ensureWorkletEasing, resolveAnimatableValue, resolveTransition } from './chunk-CY7Y64C3.mjs';
-import { useEffect, useMemo, useRef } from 'react';
-import { useSharedValue, withSpring, useAnimatedReaction, useAnimatedStyle, interpolateColor, useDerivedValue, Extrapolation, useAnimatedScrollHandler, interpolate } from 'react-native-reanimated';
+import { useEffect, useRef, useCallback, useMemo } from 'react';
+import { useSharedValue, cancelAnimation, withSpring, useAnimatedReaction, useAnimatedStyle, interpolateColor, interpolate, useDerivedValue, Extrapolation, useAnimatedScrollHandler } from 'react-native-reanimated';
 import { isWorkletFunction } from 'react-native-worklets';
 
 // src/motion/index.ts
@@ -35,8 +35,27 @@ function useAnimation(target, transition) {
     const cfg = shouldReduceMotion ? { type: "no-animation" } : resolved ?? { type: "spring" };
     output.value = resolveTransition(cfg, target);
   }, [target, cfgSig, shouldReduceMotion]);
+  useEffect(
+    () => () => cancelAnimation(output),
+    // `output` is identity-stable per hook instance (Reanimated guarantee).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []
+  );
   return output;
 }
+function useAnimator() {
+  const registry = useNamedTransitions();
+  const shouldReduceMotion = useShouldReduceMotion();
+  const registryRef = useRef(registry);
+  registryRef.current = registry;
+  const reduceMotionRef = useRef(shouldReduceMotion);
+  reduceMotionRef.current = shouldReduceMotion;
+  return useCallback((value, to, transition) => {
+    const resolved = resolveNamedTransition(transition, registryRef.current);
+    const cfg = reduceMotionRef.current ? { type: "no-animation" } : resolved ?? { type: "spring" };
+    value.value = resolveTransition(cfg, to);
+  }, []);
+}
 function useSpring(target, config) {
   const spring = resolveSpringInput(config, useNamedTransitions());
   const reanimConfig = useMemo(
@@ -75,6 +94,12 @@ function useSpring(target, config) {
     },
     [isSharedTarget, reanimConfig]
   );
+  useEffect(
+    () => () => cancelAnimation(output),
+    // `output` is identity-stable per hook instance (Reanimated guarantee).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []
+  );
   return output;
 }
 function resolveSpringInput(config, registry) {
@@ -96,6 +121,36 @@ function isSharedValue(v) {
 function useBooleanSpring(active, springConfig) {
   return useSpring(active ? 1 : 0, springConfig);
 }
+function useColorCascade(rest, layers, options) {
+  const key = options?.key ?? "backgroundColor";
+  const sig = `${key}|${rest}|${layers.length}|${layers.map((l) => l.color).join(",")}`;
+  const colors = useMemo(() => layers.map((l) => l.color), [sig]);
+  const progressRef = useRef([]);
+  const prevProgress = progressRef.current;
+  let progressChanged = prevProgress.length !== layers.length;
+  if (!progressChanged) {
+    for (let i = 0; i < layers.length; i++) {
+      if (prevProgress[i] !== layers[i].progress) {
+        progressChanged = true;
+        break;
+      }
+    }
+  }
+  if (progressChanged) progressRef.current = layers.map((l) => l.progress);
+  const progressValues = progressRef.current;
+  return useAnimatedStyle(() => {
+    "worklet";
+    let acc = rest;
+    for (let i = 0; i < colors.length; i++) {
+      acc = interpolateColor(
+        progressValues[i].value,
+        [0, 1],
+        [acc, colors[i]]
+      );
+    }
+    return { [key]: acc };
+  });
+}
 function useColorTransition(progress, range, options) {
   const key = options?.key ?? "backgroundColor";
   const from = range[0];
@@ -105,8 +160,139 @@ function useColorTransition(progress, range, options) {
     return { [key]: interpolateColor(progress.value, [0, 1], [from, to]) };
   });
 }
+var TRANSFORM_KEYS = /* @__PURE__ */ new Set([
+  "translateX",
+  "translateY",
+  "scale",
+  "scaleX",
+  "scaleY",
+  "rotate",
+  "rotateX",
+  "rotateY"
+]);
+var ROTATION_KEYS = /* @__PURE__ */ new Set(["rotate", "rotateX", "rotateY"]);
+var COLOR_KEYS = /* @__PURE__ */ new Set([
+  "backgroundColor",
+  "color",
+  "borderColor",
+  "borderTopColor",
+  "borderRightColor",
+  "borderBottomColor",
+  "borderLeftColor",
+  "tintColor",
+  "shadowColor"
+]);
+function evenlySpaced(count) {
+  if (count <= 1) return [0];
+  const out = [];
+  for (let i = 0; i < count; i++) out.push(i / (count - 1));
+  return out;
+}
+function mapExtrapolation(mode) {
+  if (mode === "identity") return Extrapolation.IDENTITY;
+  if (mode === "extend") return Extrapolation.EXTEND;
+  return Extrapolation.CLAMP;
+}
+function buildSignature(map, options) {
+  let sig = "";
+  for (const key of Object.keys(map)) {
+    const output = map[key];
+    sig += `${key}:${JSON.stringify(output)}|`;
+  }
+  sig += `#ir:${JSON.stringify(options?.inputRange)}|ex:${options?.extrapolate ?? ""}`;
+  return sig;
+}
+function buildEntries(map, options) {
+  const explicitInput = options?.inputRange;
+  const entries = [];
+  for (const key of Object.keys(map)) {
+    const output = map[key];
+    if (output === void 0 || output.length === 0) continue;
+    const input = explicitInput ? explicitInput : output.length === 2 ? [0, 1] : evenlySpaced(output.length);
+    if (__DEV__ && explicitInput && explicitInput.length !== output.length) {
+      console.warn(
+        `[inertia] useInterpolatedStyle: inputRange has ${explicitInput.length} stops but the "${String(
+          key
+        )}" output has ${output.length}. They must match \u2014 interpolation results are undefined otherwise.`
+      );
+    }
+    const isColor = COLOR_KEYS.has(key) && typeof output[0] === "string";
+    if (isColor) {
+      entries.push({
+        kind: "color",
+        key,
+        input,
+        output
+      });
+    } else if (ROTATION_KEYS.has(key)) {
+      entries.push({
+        kind: "rotation",
+        key,
+        input,
+        output
+      });
+    } else if (TRANSFORM_KEYS.has(key)) {
+      entries.push({
+        kind: "transform-numeric",
+        key,
+        input,
+        output
+      });
+    } else {
+      entries.push({
+        kind: "numeric",
+        key,
+        input,
+        output
+      });
+    }
+  }
+  return entries;
+}
+function useInterpolatedStyle(progress, map, options) {
+  const extrapolate = mapExtrapolation(options?.extrapolate);
+  const sig = buildSignature(map, options);
+  const entries = useMemo(() => buildEntries(map, options), [sig]);
+  return useAnimatedStyle(() => {
+    "worklet";
+    const out = {};
+    const transform = [];
+    for (const e of entries) {
+      if (e.kind === "color") {
+        out[e.key] = interpolateColor(progress.value, e.input, e.output);
+      } else if (e.kind === "numeric") {
+        out[e.key] = interpolate(progress.value, e.input, e.output, {
+          extrapolateLeft: extrapolate,
+          extrapolateRight: extrapolate
+        });
+      } else if (e.kind === "transform-numeric") {
+        transform.push({
+          [e.key]: interpolate(progress.value, e.input, e.output, {
+            extrapolateLeft: extrapolate,
+            extrapolateRight: extrapolate
+          })
+        });
+      } else {
+        const deg = interpolate(progress.value, e.input, e.output, {
+          extrapolateLeft: extrapolate,
+          extrapolateRight: extrapolate
+        });
+        transform.push({ [e.key]: `${deg}deg` });
+      }
+    }
+    if (transform.length > 0) out.transform = transform;
+    return out;
+  });
+}
 function useMotionValue(initial) {
-  return useSharedValue(initial);
+  const sv = useSharedValue(initial);
+  useEffect(
+    () => () => cancelAnimation(sv),
+    // `sv` is identity-stable per hook instance (Reanimated guarantee).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []
+  );
+  return sv;
 }
 function useTransform(arg1, inputRange, outputRange, options) {
   let producer;
@@ -129,8 +315,8 @@ function useTransform(arg1, inputRange, outputRange, options) {
     const input = inputRange;
     const output = outputRange;
     const isColor = output.length > 0 && typeof output[0] === "string";
-    const extrapolateLeft = mapExtrapolation(options?.extrapolateLeft);
-    const extrapolateRight = mapExtrapolation(options?.extrapolateRight);
+    const extrapolateLeft = mapExtrapolation2(options?.extrapolateLeft);
+    const extrapolateRight = mapExtrapolation2(options?.extrapolateRight);
     producer = isColor ? () => {
       "worklet";
       return interpolateColor(
@@ -150,7 +336,7 @@ function useTransform(arg1, inputRange, outputRange, options) {
   }
   return useDerivedValue(producer);
 }
-function mapExtrapolation(mode) {
+function mapExtrapolation2(mode) {
   if (mode === "identity") return Extrapolation.IDENTITY;
   if (mode === "extend") return Extrapolation.EXTEND;
   return Extrapolation.CLAMP;
@@ -401,4 +587,4 @@ function useVariants(variants, initial) {
   }, []);
 }
 
-export { Motion, useAnimation, useBooleanSpring, useColorTransition, useMotionValue, useScroll, useShadow, useSpring, useTransform, useVariants };
+export { Motion, useAnimation, useAnimator, useBooleanSpring, useColorCascade, useColorTransition, useInterpolatedStyle, useMotionValue, useScroll, useShadow, useSpring, useTransform, useVariants };

package/dist/motion/Image.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunk3UTJJ4A3_js = require('../chunk-3UTJJ4A3.js');
-require('../chunk-7UDYEFBU.js');
+var chunkKBP4LR75_js = require('../chunk-KBP4LR75.js');
+require('../chunk-BP3Y2SHQ.js');
 require('../chunk-7AOERN53.js');
 require('../chunk-PTRF47DA.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PTRF47DA.js');
 
 Object.defineProperty(exports, "MotionImage", {
   enumerable: true,
-  get: function () { return chunk3UTJJ4A3_js.MotionImage; }
+  get: function () { return chunkKBP4LR75_js.MotionImage; }
 });

package/dist/motion/Image.mjs

@@ -1,4 +1,4 @@
-export { MotionImage } from '../chunk-ALRHDFZE.mjs';
-import '../chunk-DWCLIBYO.mjs';
+export { MotionImage } from '../chunk-O22NXXCZ.mjs';
+import '../chunk-CSODMRJ7.mjs';
 import '../chunk-R63GIUNU.mjs';
 import '../chunk-CY7Y64C3.mjs';

package/dist/motion/Pressable.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkTDSO63CJ_js = require('../chunk-TDSO63CJ.js');
-require('../chunk-7UDYEFBU.js');
+var chunk3XTVY34H_js = require('../chunk-3XTVY34H.js');
+require('../chunk-BP3Y2SHQ.js');
 require('../chunk-7AOERN53.js');
 require('../chunk-PTRF47DA.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PTRF47DA.js');
 
 Object.defineProperty(exports, "MotionPressable", {
   enumerable: true,
-  get: function () { return chunkTDSO63CJ_js.MotionPressable; }
+  get: function () { return chunk3XTVY34H_js.MotionPressable; }
 });

package/dist/motion/Pressable.mjs

@@ -1,4 +1,4 @@
-export { MotionPressable } from '../chunk-NXDJZD6A.mjs';
-import '../chunk-DWCLIBYO.mjs';
+export { MotionPressable } from '../chunk-46P57VMY.mjs';
+import '../chunk-CSODMRJ7.mjs';
 import '../chunk-R63GIUNU.mjs';
 import '../chunk-CY7Y64C3.mjs';

package/dist/motion/ScrollView.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunk2HYD2ZBK_js = require('../chunk-2HYD2ZBK.js');
-require('../chunk-7UDYEFBU.js');
+var chunkW5MC3P4N_js = require('../chunk-W5MC3P4N.js');
+require('../chunk-BP3Y2SHQ.js');
 require('../chunk-7AOERN53.js');
 require('../chunk-PTRF47DA.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PTRF47DA.js');
 
 Object.defineProperty(exports, "MotionScrollView", {
   enumerable: true,
-  get: function () { return chunk2HYD2ZBK_js.MotionScrollView; }
+  get: function () { return chunkW5MC3P4N_js.MotionScrollView; }
 });

package/dist/motion/ScrollView.mjs

@@ -1,4 +1,4 @@
-export { MotionScrollView } from '../chunk-CWLFUYIY.mjs';
-import '../chunk-DWCLIBYO.mjs';
+export { MotionScrollView } from '../chunk-OQV66TBQ.mjs';
+import '../chunk-CSODMRJ7.mjs';
 import '../chunk-R63GIUNU.mjs';
 import '../chunk-CY7Y64C3.mjs';

package/dist/motion/Text.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkZ7HIOFKQ_js = require('../chunk-Z7HIOFKQ.js');
-require('../chunk-7UDYEFBU.js');
+var chunkFWQOXA43_js = require('../chunk-FWQOXA43.js');
+require('../chunk-BP3Y2SHQ.js');
 require('../chunk-7AOERN53.js');
 require('../chunk-PTRF47DA.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PTRF47DA.js');
 
 Object.defineProperty(exports, "MotionText", {
   enumerable: true,
-  get: function () { return chunkZ7HIOFKQ_js.MotionText; }
+  get: function () { return chunkFWQOXA43_js.MotionText; }
 });

package/dist/motion/Text.mjs

@@ -1,4 +1,4 @@
-export { MotionText } from '../chunk-JVBXPF2G.mjs';
-import '../chunk-DWCLIBYO.mjs';
+export { MotionText } from '../chunk-SGUHE5CX.mjs';
+import '../chunk-CSODMRJ7.mjs';
 import '../chunk-R63GIUNU.mjs';
 import '../chunk-CY7Y64C3.mjs';

package/dist/motion/View.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunk4QGXK6TF_js = require('../chunk-4QGXK6TF.js');
-require('../chunk-7UDYEFBU.js');
+var chunkFNVFV4EY_js = require('../chunk-FNVFV4EY.js');
+require('../chunk-BP3Y2SHQ.js');
 require('../chunk-7AOERN53.js');
 require('../chunk-PTRF47DA.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PTRF47DA.js');
 
 Object.defineProperty(exports, "MotionView", {
   enumerable: true,
-  get: function () { return chunk4QGXK6TF_js.MotionView; }
+  get: function () { return chunkFNVFV4EY_js.MotionView; }
 });

package/dist/motion/View.mjs

@@ -1,4 +1,4 @@
-export { MotionView } from '../chunk-6SMPIOIC.mjs';
-import '../chunk-DWCLIBYO.mjs';
+export { MotionView } from '../chunk-BQQTHG2V.mjs';
+import '../chunk-CSODMRJ7.mjs';
 import '../chunk-R63GIUNU.mjs';
 import '../chunk-CY7Y64C3.mjs';

package/llms.txt

@@ -26,6 +26,8 @@ import {
   useTransform,
   useShadow,
   useColorTransition,
+  useColorCascade,
+  useInterpolatedStyle,
   useScroll,
 } from '@rootnative/inertia'
 // Opt-in MD3 / iOS state-layer overlay helper:
@@ -50,11 +52,14 @@ import { MotionScrollView } from '@rootnative/inertia/scroll-view'
 - `useVariants(variants, initial?)` — returns `{ current, transitionTo }` controller for the `controller` prop.
 - `useMotionValue(initial)` — thin pass-through over `useSharedValue<T>`. Returns a `SharedValue<T>` directly so it interops with every Reanimated API without unwrapping.
 - `useAnimation(target, transition?)` — drive a `SharedValue<number>` toward `target` with any `TransitionConfig` (spring / timing / decay / no-animation, plus `repeat`) or a registered `TransitionName`. The general-purpose value-layer hook for boolean-state progress, indeterminate loops, and anywhere the same value needs to feed multiple `useAnimatedStyle` blocks.
+- `useAnimator()` — the **imperative** counterpart to `useAnimation`. Returns an identity-stable `(value: SharedValue<number>, to: number, transition?: TransitionConfig | TransitionName) => void` setter to call from event handlers (hover-in, focus, press) rather than from an effect. Resolves registered `TransitionName`s through the nearest `<MotionConfig transitions>` and gates on `<MotionConfig reducedMotion>` (`'no-animation'` downgrade) — the two things a hand-rolled `resolveTransition` write in an event handler silently gets wrong. Default transition is the library spring. Not a new animation API — the hooks-layer equivalent of `useMotionValue` + `resolveTransition`, minus the footguns.
 - `useSpring(target, config?)` — spring-only shorthand. Animates a `SharedValue<number>` toward `target` with react-spring vocab (or a spring-typed registered `TransitionName`; non-spring names warn and fall back to the default spring). `target` may be a plain number (effect-driven) or a `SharedValue<number>` (UI-thread reaction); the latter is the gesture-smoothing path.
 - `useBooleanSpring(active, config?)` — sugar over `useSpring` for the recurring "spring 0↔1 progress from a boolean" shape (checkbox checks, accordion expansions, drawer open/closed). Identical mechanics to `useSpring(active ? 1 : 0, config)` — the named form so the call site reads as the boolean it represents.
 - `useTransform(value, inputRange, outputRange, options?)` / `useTransform(transformer)` — interpolate a numeric shared value onto a number or color range, or derive any value from any number of shared values via a worklet. Non-worklet transformers are auto-wrapped.
 - `useShadow({ from, to, progress })` — pure value-layer interpolator between two `ShadowConfig`s (`shadowOpacity` / `shadowRadius` / `shadowOffset` / `elevation` / `shadowColor`, plus `boxShadow` as a CSS string or `BoxShadowLayer[]` — the shadow surface on web and RN 0.76+ new-arch; multi-layer, CSS-transition padding semantics, malformed strings throw at setup) driven by a `SharedValue<number>` (0→1). Returns an animated style fragment to spread onto `style`; only emits keys present on either side, absent sides default to natural zero. The hook does not animate on its own — drive `progress` with a spring, a scroll-derived `useTransform`, or any other shared value source.
 - `useColorTransition(progress, [from, to], options?)` — pure value-layer interpolator for a single color channel, driven by a `SharedValue<number>` (0→1). Returns an animated style fragment with one color key (default `backgroundColor`; configurable via `options.key` to `color` / `borderColor` / `tintColor` / `shadowColor` / per-side border colors). For raw `SharedValue<string>` output, use `useTransform(progress, [0, 1], [from, to])` instead.
+- `useColorCascade(rest, layers, options?)` — pure value-layer interpolator compositing a **priority-ordered** stack of color layers over a base `rest` color; each `layers` entry is `{ progress: SharedValue<number>, color: string }`, later entries win as their progress rises (equivalent to the nested `focus(error(hover(rest)))` `interpolateColor` chain). `options.key` reuses `ColorStyleKey` (default `backgroundColor`). Returns a spreadable animated style fragment; memoized on a colors+key signature. Color-only by design — cascade a numeric key separately via `useInterpolatedStyle` + `useTransform` max. `useColorTransition` stays the single-layer fast path.
+- `useInterpolatedStyle(progress, map, options?)` — pure value-layer interpolator mapping one `SharedValue<number>` onto **N** style props at once, returned as a spreadable animated style fragment (the multi-key, style-fragment counterpart to `useTransform`'s output-range form). Numeric keys (`opacity` / `height` / `fontSize` / …) route through `interpolate`; transform keys (`translateX` / `scale` / `rotate` / …) lift into a `transform` array in map key-order (`rotate*` emit `'<n>deg'`); color keys (`backgroundColor` / `borderColor` / …) route through `interpolateColor` (a multi-stop `useColorTransition`). Stop types are compile-checked. `options.inputRange` (default `[0,1]` / evenly-spaced) and `options.extrapolate` (default `'clamp'`) apply to every key. Memoized on an order-preserving signature. For function-valued or multi-source composition, drop to `useTransform`'s worklet form or a hand-rolled `useAnimatedStyle`.
 - `useScroll()` — returns `{ scrollX, scrollY, onScroll }` for use with `Motion.ScrollView`. Scroll events fire on the UI thread.
 - `createMotionComponent<C>(C)` — wrap any component with the same Motion prop surface, inferring style from `C`.
 - `buildReleaseAnimation(transition, toValue)` — worklet-safe single-step animation builder (spring / timing / decay / no-animation). For assigning Inertia-resolved animations to shared values from inside a gesture worklet. Used internally by `@rootnative/inertia-gestures`'s `useDrag({ onRelease })`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootnative/inertia",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Declarative animation primitives for React Native, built on react-native-reanimated.",
   "license": "MIT",
   "author": "RootNative",

package/src/index.ts

@@ -41,9 +41,12 @@ export {
 } from './transitions'
 export {
   useAnimation,
+  useAnimator,
   useBooleanSpring,
+  useColorCascade,
   useColorTransition,
   useGesture,
+  useInterpolatedStyle,
   useMotionValue,
   useScroll,
   useShadow,
@@ -57,13 +60,20 @@ export {
 // Runtime render-layer interop lives in `@rootnative/inertia/reanimated`.
 export type { SharedValue } from 'react-native-reanimated'
 export type {
+  Animator,
   BoxShadowLayer,
+  ColorCascadeLayer,
   ColorStyleKey,
   ExtrapolationMode,
+  InterpolatedStyleMap,
+  NumericStyleKey,
   ShadowConfig,
+  TransformKey,
+  UseColorCascadeOptions,
   UseColorTransitionOptions,
   UseGestureHandlers,
   UseGestureResult,
+  UseInterpolatedStyleOptions,
   UseScrollResult,
   UseShadowOptions,
   UseTransformOptions,

package/src/layout/index.ts

@@ -7,6 +7,7 @@ export {
   releaseLayout,
   SHARED_LAYOUT_TTL_MS,
   __setSharedLayoutClock,
+  __sharedRegistrySize,
   type SharedRect,
 } from './sharedRegistry'
 export {

package/src/layout/sharedRegistry.ts

@@ -51,6 +51,37 @@ export const SHARED_LAYOUT_TTL_MS = 1000
  */
 let now = (): number => Date.now()
 
+/**
+ * When the last expiry sweep ran, so the scan is amortized to at most once per
+ * TTL window rather than running on every write.
+ */
+let lastSweep = 0
+
+/**
+ * Drop every entry whose TTL has passed.
+ *
+ * Without this the map only ever shrank via `consumeLayout` / `peekSharedLayout`,
+ * so a `layoutId` that unmounted and was never remounted left its rect behind
+ * for the lifetime of the process. Bounded by distinct-id count, which is small
+ * for a handful of hero images but not for per-item ids in a long-lived list
+ * (`layoutId={`photo-${item.id}`}`).
+ *
+ * Sweeping a *live* element's entry is harmless: while mounted it re-registers
+ * on every `onLayout`, and on unmount `releaseLayout` re-adds it with a fresh
+ * TTL. So the only thing an over-eager sweep can cost is a FLIP source that was
+ * already too old to be used.
+ *
+ * Time-gated so a burst of layout events doesn't turn into a burst of full
+ * scans — worst case an expired entry survives one extra TTL window.
+ */
+function sweepExpired(at: number): void {
+  if (at - lastSweep < SHARED_LAYOUT_TTL_MS) return
+  lastSweep = at
+  for (const [id, entry] of REGISTRY) {
+    if (entry.expiresAt < at) REGISTRY.delete(id)
+  }
+}
+
 /**
  * Update the latest known rect for `id`. Called on every `onLayout` of a
  * Motion primitive with `layoutId` set so the registry always holds a
@@ -58,7 +89,9 @@ let now = (): number => Date.now()
  * transition. Resets the TTL each call.
  */
 export function registerLayout(id: string, rect: SharedRect): void {
-  REGISTRY.set(id, { rect, expiresAt: now() + SHARED_LAYOUT_TTL_MS })
+  const at = now()
+  sweepExpired(at)
+  REGISTRY.set(id, { rect, expiresAt: at + SHARED_LAYOUT_TTL_MS })
 }
 
 /**
@@ -67,7 +100,9 @@ export function registerLayout(id: string, rect: SharedRect): void {
  * is purely intent-documenting at the call site.
  */
 export function releaseLayout(id: string, rect: SharedRect): void {
-  REGISTRY.set(id, { rect, expiresAt: now() + SHARED_LAYOUT_TTL_MS })
+  const at = now()
+  sweepExpired(at)
+  REGISTRY.set(id, { rect, expiresAt: at + SHARED_LAYOUT_TTL_MS })
 }
 
 /**
@@ -88,6 +123,7 @@ export function consumeLayout(id: string): SharedRect | undefined {
 /** Drop all entries. Tests use this to isolate between cases. */
 export function clearSharedRegistry(): void {
   REGISTRY.clear()
+  lastSweep = 0
 }
 
 /**
@@ -108,4 +144,17 @@ export function peekSharedLayout(id: string): SharedRect | undefined {
  */
 export function __setSharedLayoutClock(fn: (() => number) | undefined): void {
   now = fn ?? Date.now
+  // Swapping the clock makes the previous sweep timestamp meaningless — a
+  // stubbed clock usually starts near 0, which would otherwise suppress every
+  // sweep until it caught up past the real-time value recorded earlier.
+  lastSweep = 0
+}
+
+/**
+ * Test hook: how many entries the registry is holding, expired or not. Used to
+ * assert that released-but-never-consumed rects are actually evicted. Not
+ * exported from the package root — reachable only from inside the workspace.
+ */
+export function __sharedRegistrySize(): number {
+  return REGISTRY.size
 }