@rootnative/inertia 0.0.0-alpha.5 → 0.0.0-alpha.7

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@rootnative/inertia` are documented here. The format fol
 
 ## [Unreleased]
 
+### Added
+
+- **`useShadow` now interpolates CSS `boxShadow`.** The classic `shadow*`/`elevation` keys never reach the web renderer, so a `useShadow` elevation crossfade silently dropped its shadow on web — the platform where hover, its most common driver, matters most (gap surfaced by the RootNative UI Card migration). `ShadowConfig` gains `boxShadow?: string | BoxShadowLayer[]`: pass the CSS string form design systems store elevation tokens in (px lengths only; parsed once on the JS thread, `cubicBezier`-style — malformed tokens throw at setup rather than warning) or structured layers mirroring RN's `BoxShadowValue`. Multi-layer shadows interpolate per layer with CSS-transition padding semantics (shorter side padded with invisible layers; a genuine `inset` mismatch throws); blur clamps at 0 under springy overshoot. Emitted as a `boxShadow` style string — passed through as CSS by react-native-web and rendered natively on RN 0.76+ new architecture; keep `shadow*`/`elevation` alongside it for old-arch native. New `BoxShadowLayer` type exported from the root.
+
+## [0.0.0-alpha.5] - 2026-07-21
+
 ### Changed
 
 - **Non-worklet transformers and easings now dev-warn.** `useTransform`'s transformer overload and custom `timing.easing` functions must be worklets (`'worklet'` directive as the first statement). The previous "plain functions are auto-wrapped" promise was unfulfillable: the directive-wrapped fallback closes over the opaque function reference, not the shared values read inside it, so Reanimated cannot extract dependencies (a `useTransform` derived value silently only refreshed on React re-renders — found via a frozen TextField label float in the UI library) and native builds reject the plain function when the closure is serialized to the UI thread. The fallback wrapper remains as a web-only best effort, but both sites now `console.warn` once in dev (suppressed under Jest, where the shared stubs report every function as non-worklet). Docs (`transitions.md`, `layout.md`, `api/hooks.md`) and docstrings corrected to state the real contract.

package/dist/gestureLayer/index.d.mts

@@ -1,6 +1,6 @@
 import { SharedValue, AnimatedStyle } from 'react-native-reanimated';
-import { U as UseGestureHandlers } from '../useGesture-C0GBS7d2.mjs';
-import { T as TransitionInput, n as GestureLayerTransitions } from '../types-BzEgiUdJ.mjs';
+import { U as UseGestureHandlers } from '../useGesture-RFY6kTL3.mjs';
+import { a as TransitionInput, G as GestureLayerTransitions } from '../types-G1dBU2IQ.mjs';
 import 'react';
 import 'react-native';
 

package/dist/gestureLayer/index.d.ts

@@ -1,6 +1,6 @@
 import { SharedValue, AnimatedStyle } from 'react-native-reanimated';
-import { U as UseGestureHandlers } from '../useGesture-BRLgiNOC.js';
-import { T as TransitionInput, n as GestureLayerTransitions } from '../types-BzEgiUdJ.js';
+import { U as UseGestureHandlers } from '../useGesture-D1e4ixJo.js';
+import { a as TransitionInput, G as GestureLayerTransitions } from '../types-G1dBU2IQ.js';
 import 'react';
 import 'react-native';
 

package/dist/index.d.mts

@@ -2,10 +2,11 @@ import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
 import * as react_native from 'react-native';
 import { NativeSyntheticEvent, NativeScrollEvent } from 'react-native';
-import { M as MotionComponent, N as NamedTransitions, T as TransitionInput, a as TransitionConfig, A as AnimatableValue, E as EasingInput, S as SpringTransition, b as TransitionName, V as VariantController } from './types-BzEgiUdJ.mjs';
-export { c as AnimateStyle, d as AnimationCallbackInfo, D as DecayTransition, e as EasingFunction, f as EasingFunctionFactory, G as GestureSubStates, g as MotionProps, h as NoAnimationTransition, P as PerPropertyTransition, R as RegisteredTransitions, i as RepeatConfig, j as SequenceStep, k as TimingTransition, l as Transition, m as VariantsMap } from './types-BzEgiUdJ.mjs';
+import { M as MotionComponent, N as NamedTransitions, a as TransitionInput, T as TransitionConfig, A as AnimatableValue, E as EasingInput, S as SpringTransition, b as TransitionName, V as VariantController } from './types-G1dBU2IQ.mjs';
+export { c as AnimateStyle, d as AnimationCallbackInfo, D as DecayTransition, e as EasingFunction, f as EasingFunctionFactory, g as GestureSubStates, h as MotionProps, i as NoAnimationTransition, P as PerPropertyTransition, R as RegisteredTransitions, j as RepeatConfig, k as SequenceStep, l as TimingTransition, m as Transition, n as VariantsMap } from './types-G1dBU2IQ.mjs';
 import { SharedValue, useAnimatedStyle } from 'react-native-reanimated';
-export { U as UseGestureHandlers, a as UseGestureResult, u as useGesture } from './useGesture-C0GBS7d2.mjs';
+export { SharedValue } from 'react-native-reanimated';
+export { U as UseGestureHandlers, a as UseGestureResult, u as useGesture } from './useGesture-RFY6kTL3.mjs';
 export { MotionImage } from './motion/Image.mjs';
 export { MotionPressable } from './motion/Pressable.mjs';
 export { MotionScrollView } from './motion/ScrollView.mjs';
@@ -555,11 +556,42 @@ interface UseScrollResult {
  */
 declare function useScroll(): UseScrollResult;
 
+/**
+ * CSS `box-shadow` parsing + pairing for `useShadow`.
+ *
+ * Design systems store web elevation tokens as CSS `box-shadow` strings
+ * (`'0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'`).
+ * Like `cubicBezier`, this module makes those tokens directly consumable:
+ * strings are parsed once on the JS thread into flat layer records the
+ * `useShadow` worklet can interpolate without any frame-time string work.
+ *
+ * Invalid input **throws** rather than warning — shadow tokens are
+ * constructed at theme/module setup, and a malformed token should fail
+ * loudly there, not silently render the wrong elevation.
+ */
+/**
+ * One layer of a `box-shadow`, structurally mirroring React Native's
+ * `BoxShadowValue` (RN 0.76+ `boxShadow` style). Lengths are px numbers.
+ */
+interface BoxShadowLayer {
+    offsetX: number;
+    offsetY: number;
+    /** Must be >= 0, per CSS. @default 0 */
+    blurRadius?: number;
+    /** @default 0 */
+    spreadDistance?: number;
+    /** Any color string Reanimated's `interpolateColor` accepts. @default 'black' */
+    color?: string;
+    /** @default false */
+    inset?: boolean;
+}
+
 /**
  * Shape accepted on either end of a `useShadow` tween. Every field is
  * optional — only keys present on at least one side participate in the
  * output style. Mirrors the flat shadow keys on `Motion.View`'s `animate`
- * surface, plus the nested `shadowOffset` source.
+ * surface, plus the nested `shadowOffset` source and the CSS `boxShadow`
+ * surface.
  */
 interface ShadowConfig {
     shadowOpacity?: number;
@@ -571,6 +603,19 @@ interface ShadowConfig {
     /** Android elevation. iOS shadow consumers can leave this off. */
     elevation?: number;
     shadowColor?: string;
+    /**
+     * CSS `box-shadow` — the shadow surface on web (react-native-web passes
+     * it through as CSS) and on React Native 0.76+ new-architecture native.
+     * Accepts the CSS string form design systems store elevation tokens in
+     * (`'0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'`;
+     * px lengths only) or structured layers. Multi-layer shadows interpolate
+     * per layer; when one side has fewer layers, it is padded with invisible
+     * layers, CSS-transition style. A malformed string **throws** at render
+     * (like `cubicBezier` — token mistakes should fail loudly at setup).
+     * The classic `shadow*`/`elevation` keys don't reach the web renderer —
+     * provide `boxShadow` alongside them when the tween must show up there.
+     */
+    boxShadow?: string | readonly BoxShadowLayer[];
 }
 interface UseShadowOptions {
     /** Shadow state at `progress === 0`. */
@@ -607,6 +652,19 @@ interface UseShadowOptions {
  * `shadowColor`, `{ width: 0, height: 0 }` for `shadowOffset`). This is a
  * pure interpolator — to "animate" the shadow, drive `progress` with a
  * spring, timing, or gesture upstream.
+ *
+ * The classic `shadow*`/`elevation` keys don't render on web. When the
+ * tween must show up there (or on RN 0.76+ new-arch native via the CSS
+ * shadow model), provide `boxShadow` on both ends — CSS string tokens or
+ * structured layers; multi-layer shadows interpolate per layer:
+ *
+ * ```tsx
+ * const shadowStyle = useShadow({
+ *   from: { boxShadow: theme.elevation.level1 }, // '0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'
+ *   to:   { boxShadow: theme.elevation.level2 },
+ *   progress,
+ * })
+ * ```
  */
 declare function useShadow({ from, to, progress, }: UseShadowOptions): ReturnType<typeof useAnimatedStyle>;
 
@@ -623,4 +681,4 @@ declare function useShadow({ from, to, progress, }: UseShadowOptions): ReturnTyp
  */
 declare function useVariants<V extends Readonly<Record<string, object>>>(variants: V, initial?: keyof V & string): VariantController<keyof V & string>;
 
-export { AnimatableValue, type ColorStyleKey, EasingInput, type ExtrapolationMode, Motion, MotionComponent, MotionConfig, type MotionConfigProps, type MotionConfigValue, NamedTransitions, Presence, type PresenceContextValue, type ReducedMotion, type ShadowConfig, SpringTransition, TransitionConfig, TransitionInput, TransitionName, type UseColorTransitionOptions, type UseScrollResult, type UseShadowOptions, type UseTransformOptions, VariantController, buildReleaseAnimation, createMotionComponent, cubicBezier, ensureWorkletEasing, resolveAnimatableValue, resolveNamedTransition, resolveTransition, useAnimation, useBooleanSpring, useColorTransition, useMotionConfig, useMotionValue, useNamedTransitions, usePresence, useScroll, useShadow, useShouldReduceMotion, useSpring, useTransform, useVariants };
+export { AnimatableValue, type BoxShadowLayer, type ColorStyleKey, EasingInput, type ExtrapolationMode, Motion, MotionComponent, MotionConfig, type MotionConfigProps, type MotionConfigValue, NamedTransitions, Presence, type PresenceContextValue, type ReducedMotion, type ShadowConfig, SpringTransition, TransitionConfig, TransitionInput, TransitionName, type UseColorTransitionOptions, type UseScrollResult, type UseShadowOptions, type UseTransformOptions, VariantController, buildReleaseAnimation, createMotionComponent, cubicBezier, ensureWorkletEasing, resolveAnimatableValue, resolveNamedTransition, resolveTransition, useAnimation, useBooleanSpring, useColorTransition, useMotionConfig, useMotionValue, useNamedTransitions, usePresence, useScroll, useShadow, useShouldReduceMotion, useSpring, useTransform, useVariants };

package/dist/index.d.ts

@@ -2,10 +2,11 @@ import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
 import * as react_native from 'react-native';
 import { NativeSyntheticEvent, NativeScrollEvent } from 'react-native';
-import { M as MotionComponent, N as NamedTransitions, T as TransitionInput, a as TransitionConfig, A as AnimatableValue, E as EasingInput, S as SpringTransition, b as TransitionName, V as VariantController } from './types-BzEgiUdJ.js';
-export { c as AnimateStyle, d as AnimationCallbackInfo, D as DecayTransition, e as EasingFunction, f as EasingFunctionFactory, G as GestureSubStates, g as MotionProps, h as NoAnimationTransition, P as PerPropertyTransition, R as RegisteredTransitions, i as RepeatConfig, j as SequenceStep, k as TimingTransition, l as Transition, m as VariantsMap } from './types-BzEgiUdJ.js';
+import { M as MotionComponent, N as NamedTransitions, a as TransitionInput, T as TransitionConfig, A as AnimatableValue, E as EasingInput, S as SpringTransition, b as TransitionName, V as VariantController } from './types-G1dBU2IQ.js';
+export { c as AnimateStyle, d as AnimationCallbackInfo, D as DecayTransition, e as EasingFunction, f as EasingFunctionFactory, g as GestureSubStates, h as MotionProps, i as NoAnimationTransition, P as PerPropertyTransition, R as RegisteredTransitions, j as RepeatConfig, k as SequenceStep, l as TimingTransition, m as Transition, n as VariantsMap } from './types-G1dBU2IQ.js';
 import { SharedValue, useAnimatedStyle } from 'react-native-reanimated';
-export { U as UseGestureHandlers, a as UseGestureResult, u as useGesture } from './useGesture-BRLgiNOC.js';
+export { SharedValue } from 'react-native-reanimated';
+export { U as UseGestureHandlers, a as UseGestureResult, u as useGesture } from './useGesture-D1e4ixJo.js';
 export { MotionImage } from './motion/Image.js';
 export { MotionPressable } from './motion/Pressable.js';
 export { MotionScrollView } from './motion/ScrollView.js';
@@ -555,11 +556,42 @@ interface UseScrollResult {
  */
 declare function useScroll(): UseScrollResult;
 
+/**
+ * CSS `box-shadow` parsing + pairing for `useShadow`.
+ *
+ * Design systems store web elevation tokens as CSS `box-shadow` strings
+ * (`'0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'`).
+ * Like `cubicBezier`, this module makes those tokens directly consumable:
+ * strings are parsed once on the JS thread into flat layer records the
+ * `useShadow` worklet can interpolate without any frame-time string work.
+ *
+ * Invalid input **throws** rather than warning — shadow tokens are
+ * constructed at theme/module setup, and a malformed token should fail
+ * loudly there, not silently render the wrong elevation.
+ */
+/**
+ * One layer of a `box-shadow`, structurally mirroring React Native's
+ * `BoxShadowValue` (RN 0.76+ `boxShadow` style). Lengths are px numbers.
+ */
+interface BoxShadowLayer {
+    offsetX: number;
+    offsetY: number;
+    /** Must be >= 0, per CSS. @default 0 */
+    blurRadius?: number;
+    /** @default 0 */
+    spreadDistance?: number;
+    /** Any color string Reanimated's `interpolateColor` accepts. @default 'black' */
+    color?: string;
+    /** @default false */
+    inset?: boolean;
+}
+
 /**
  * Shape accepted on either end of a `useShadow` tween. Every field is
  * optional — only keys present on at least one side participate in the
  * output style. Mirrors the flat shadow keys on `Motion.View`'s `animate`
- * surface, plus the nested `shadowOffset` source.
+ * surface, plus the nested `shadowOffset` source and the CSS `boxShadow`
+ * surface.
  */
 interface ShadowConfig {
     shadowOpacity?: number;
@@ -571,6 +603,19 @@ interface ShadowConfig {
     /** Android elevation. iOS shadow consumers can leave this off. */
     elevation?: number;
     shadowColor?: string;
+    /**
+     * CSS `box-shadow` — the shadow surface on web (react-native-web passes
+     * it through as CSS) and on React Native 0.76+ new-architecture native.
+     * Accepts the CSS string form design systems store elevation tokens in
+     * (`'0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'`;
+     * px lengths only) or structured layers. Multi-layer shadows interpolate
+     * per layer; when one side has fewer layers, it is padded with invisible
+     * layers, CSS-transition style. A malformed string **throws** at render
+     * (like `cubicBezier` — token mistakes should fail loudly at setup).
+     * The classic `shadow*`/`elevation` keys don't reach the web renderer —
+     * provide `boxShadow` alongside them when the tween must show up there.
+     */
+    boxShadow?: string | readonly BoxShadowLayer[];
 }
 interface UseShadowOptions {
     /** Shadow state at `progress === 0`. */
@@ -607,6 +652,19 @@ interface UseShadowOptions {
  * `shadowColor`, `{ width: 0, height: 0 }` for `shadowOffset`). This is a
  * pure interpolator — to "animate" the shadow, drive `progress` with a
  * spring, timing, or gesture upstream.
+ *
+ * The classic `shadow*`/`elevation` keys don't render on web. When the
+ * tween must show up there (or on RN 0.76+ new-arch native via the CSS
+ * shadow model), provide `boxShadow` on both ends — CSS string tokens or
+ * structured layers; multi-layer shadows interpolate per layer:
+ *
+ * ```tsx
+ * const shadowStyle = useShadow({
+ *   from: { boxShadow: theme.elevation.level1 }, // '0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'
+ *   to:   { boxShadow: theme.elevation.level2 },
+ *   progress,
+ * })
+ * ```
  */
 declare function useShadow({ from, to, progress, }: UseShadowOptions): ReturnType<typeof useAnimatedStyle>;
 
@@ -623,4 +681,4 @@ declare function useShadow({ from, to, progress, }: UseShadowOptions): ReturnTyp
  */
 declare function useVariants<V extends Readonly<Record<string, object>>>(variants: V, initial?: keyof V & string): VariantController<keyof V & string>;
 
-export { AnimatableValue, type ColorStyleKey, EasingInput, type ExtrapolationMode, Motion, MotionComponent, MotionConfig, type MotionConfigProps, type MotionConfigValue, NamedTransitions, Presence, type PresenceContextValue, type ReducedMotion, type ShadowConfig, SpringTransition, TransitionConfig, TransitionInput, TransitionName, type UseColorTransitionOptions, type UseScrollResult, type UseShadowOptions, type UseTransformOptions, VariantController, buildReleaseAnimation, createMotionComponent, cubicBezier, ensureWorkletEasing, resolveAnimatableValue, resolveNamedTransition, resolveTransition, useAnimation, useBooleanSpring, useColorTransition, useMotionConfig, useMotionValue, useNamedTransitions, usePresence, useScroll, useShadow, useShouldReduceMotion, useSpring, useTransform, useVariants };
+export { AnimatableValue, type BoxShadowLayer, type ColorStyleKey, EasingInput, type ExtrapolationMode, Motion, MotionComponent, MotionConfig, type MotionConfigProps, type MotionConfigValue, NamedTransitions, Presence, type PresenceContextValue, type ReducedMotion, type ShadowConfig, SpringTransition, TransitionConfig, TransitionInput, TransitionName, type UseColorTransitionOptions, type UseScrollResult, type UseShadowOptions, type UseTransformOptions, VariantController, buildReleaseAnimation, createMotionComponent, cubicBezier, ensureWorkletEasing, resolveAnimatableValue, resolveNamedTransition, resolveTransition, useAnimation, useBooleanSpring, useColorTransition, useMotionConfig, useMotionValue, useNamedTransitions, usePresence, useScroll, useShadow, useShouldReduceMotion, useSpring, useTransform, useVariants };

package/dist/index.js

@@ -166,6 +166,127 @@ function useScroll() {
     onScroll: handler
   };
 }
+
+// src/internal/boxShadow.ts
+var LENGTH = /^[+-]?(\d+\.?\d*|\.\d+)(px)?$/i;
+var UNIT_LIKE = /^[+-]?(\d+\.?\d*|\.\d+)[a-z%]+$/i;
+function invalid(input, reason) {
+  return new Error(
+    `[inertia] parseBoxShadow: ${reason} in ${JSON.stringify(input)}. Expected CSS box-shadow syntax with px lengths: '[inset] <offset-x> <offset-y> [blur] [spread] [color], ...'`
+  );
+}
+function splitLayers(input) {
+  const layers = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i];
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    else if (ch === "," && depth === 0) {
+      layers.push(input.slice(start, i));
+      start = i + 1;
+    }
+  }
+  layers.push(input.slice(start));
+  return layers;
+}
+function tokenize(layer) {
+  const tokens = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of layer) {
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    if (depth === 0 && /\s/.test(ch)) {
+      if (current) tokens.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
+function parseBoxShadow(input) {
+  const trimmed = input.trim();
+  if (trimmed === "") throw invalid(input, "empty string");
+  if (trimmed.toLowerCase() === "none") return [];
+  return splitLayers(trimmed).map((layerString) => {
+    const tokens = tokenize(layerString.trim());
+    if (tokens.length === 0) throw invalid(input, "empty layer");
+    const lengths = [];
+    let color;
+    let inset = false;
+    for (const token of tokens) {
+      if (token.toLowerCase() === "inset") {
+        if (inset) throw invalid(input, "duplicate 'inset'");
+        inset = true;
+      } else if (LENGTH.test(token)) {
+        lengths.push(parseFloat(token));
+      } else if (UNIT_LIKE.test(token)) {
+        throw invalid(input, `unsupported unit in ${JSON.stringify(token)}`);
+      } else {
+        if (color !== void 0) throw invalid(input, "multiple colors");
+        color = token;
+      }
+    }
+    if (lengths.length < 2 || lengths.length > 4) {
+      throw invalid(input, `expected 2-4 lengths, got ${lengths.length}`);
+    }
+    const [offsetX = 0, offsetY = 0, blurRadius = 0, spreadDistance = 0] = lengths;
+    if (blurRadius < 0) throw invalid(input, "negative blur radius");
+    return {
+      offsetX,
+      offsetY,
+      blurRadius,
+      spreadDistance,
+      color: color ?? "black",
+      inset
+    };
+  });
+}
+function resolveBoxShadowInput(input) {
+  if (input === void 0) return [];
+  if (typeof input === "string") return parseBoxShadow(input);
+  return input.map((layer) => ({
+    offsetX: layer.offsetX,
+    offsetY: layer.offsetY,
+    blurRadius: layer.blurRadius ?? 0,
+    spreadDistance: layer.spreadDistance ?? 0,
+    color: layer.color ?? "black",
+    inset: layer.inset ?? false
+  }));
+}
+function pairBoxShadowLayers(from, to) {
+  const count = Math.max(from.length, to.length);
+  const pairs = [];
+  for (let i = 0; i < count; i++) {
+    const a = from[i];
+    const b = to[i];
+    const fromLayer = a ?? invisibleLayer(b.inset);
+    const toLayer = b ?? invisibleLayer(a.inset);
+    if (fromLayer.inset !== toLayer.inset) {
+      throw new Error(
+        `[inertia] useShadow: boxShadow layer ${i} is 'inset' on one side but not the other \u2014 inset cannot be interpolated. Give both sides the same inset-ness (pad with a transparent layer if needed).`
+      );
+    }
+    pairs.push({ from: fromLayer, to: toLayer });
+  }
+  return pairs;
+}
+function invisibleLayer(inset) {
+  return {
+    offsetX: 0,
+    offsetY: 0,
+    blurRadius: 0,
+    spreadDistance: 0,
+    color: "transparent",
+    inset
+  };
+}
+
+// src/values/useShadow.ts
 function useShadow({
   from,
   to,
@@ -176,6 +297,10 @@ function useShadow({
   const hasElevation = from.elevation !== void 0 || to.elevation !== void 0;
   const hasColor = from.shadowColor !== void 0 || to.shadowColor !== void 0;
   const hasOffset = from.shadowOffset !== void 0 || to.shadowOffset !== void 0;
+  const boxShadowPairs = from.boxShadow !== void 0 || to.boxShadow !== void 0 ? pairBoxShadowLayers(
+    resolveBoxShadowInput(from.boxShadow),
+    resolveBoxShadowInput(to.boxShadow)
+  ) : [];
   const opacityFrom = from.shadowOpacity ?? 0;
   const opacityTo = to.shadowOpacity ?? 0;
   const radiusFrom = from.shadowRadius ?? 0;
@@ -210,6 +335,31 @@ function useShadow({
         height: reactNativeReanimated.interpolate(t, [0, 1], [offsetHFrom, offsetHTo])
       };
     }
+    if (boxShadowPairs.length > 0) {
+      let css = "";
+      let first = true;
+      for (const pair of boxShadowPairs) {
+        const x = reactNativeReanimated.interpolate(t, [0, 1], [pair.from.offsetX, pair.to.offsetX]);
+        const y = reactNativeReanimated.interpolate(t, [0, 1], [pair.from.offsetY, pair.to.offsetY]);
+        const blur = Math.max(
+          0,
+          reactNativeReanimated.interpolate(t, [0, 1], [pair.from.blurRadius, pair.to.blurRadius])
+        );
+        const spread = reactNativeReanimated.interpolate(
+          t,
+          [0, 1],
+          [pair.from.spreadDistance, pair.to.spreadDistance]
+        );
+        const color = reactNativeReanimated.interpolateColor(
+          t,
+          [0, 1],
+          [pair.from.color, pair.to.color]
+        );
+        css += (first ? "" : ", ") + (pair.from.inset ? "inset " : "") + `${x}px ${y}px ${blur}px ${spread}px ${color}`;
+        first = false;
+      }
+      out.boxShadow = css;
+    }
     return out;
   });
 }

package/dist/index.mjs

@@ -171,6 +171,127 @@ function useScroll() {
     onScroll: handler
   };
 }
+
+// src/internal/boxShadow.ts
+var LENGTH = /^[+-]?(\d+\.?\d*|\.\d+)(px)?$/i;
+var UNIT_LIKE = /^[+-]?(\d+\.?\d*|\.\d+)[a-z%]+$/i;
+function invalid(input, reason) {
+  return new Error(
+    `[inertia] parseBoxShadow: ${reason} in ${JSON.stringify(input)}. Expected CSS box-shadow syntax with px lengths: '[inset] <offset-x> <offset-y> [blur] [spread] [color], ...'`
+  );
+}
+function splitLayers(input) {
+  const layers = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i];
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    else if (ch === "," && depth === 0) {
+      layers.push(input.slice(start, i));
+      start = i + 1;
+    }
+  }
+  layers.push(input.slice(start));
+  return layers;
+}
+function tokenize(layer) {
+  const tokens = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of layer) {
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    if (depth === 0 && /\s/.test(ch)) {
+      if (current) tokens.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
+function parseBoxShadow(input) {
+  const trimmed = input.trim();
+  if (trimmed === "") throw invalid(input, "empty string");
+  if (trimmed.toLowerCase() === "none") return [];
+  return splitLayers(trimmed).map((layerString) => {
+    const tokens = tokenize(layerString.trim());
+    if (tokens.length === 0) throw invalid(input, "empty layer");
+    const lengths = [];
+    let color;
+    let inset = false;
+    for (const token of tokens) {
+      if (token.toLowerCase() === "inset") {
+        if (inset) throw invalid(input, "duplicate 'inset'");
+        inset = true;
+      } else if (LENGTH.test(token)) {
+        lengths.push(parseFloat(token));
+      } else if (UNIT_LIKE.test(token)) {
+        throw invalid(input, `unsupported unit in ${JSON.stringify(token)}`);
+      } else {
+        if (color !== void 0) throw invalid(input, "multiple colors");
+        color = token;
+      }
+    }
+    if (lengths.length < 2 || lengths.length > 4) {
+      throw invalid(input, `expected 2-4 lengths, got ${lengths.length}`);
+    }
+    const [offsetX = 0, offsetY = 0, blurRadius = 0, spreadDistance = 0] = lengths;
+    if (blurRadius < 0) throw invalid(input, "negative blur radius");
+    return {
+      offsetX,
+      offsetY,
+      blurRadius,
+      spreadDistance,
+      color: color ?? "black",
+      inset
+    };
+  });
+}
+function resolveBoxShadowInput(input) {
+  if (input === void 0) return [];
+  if (typeof input === "string") return parseBoxShadow(input);
+  return input.map((layer) => ({
+    offsetX: layer.offsetX,
+    offsetY: layer.offsetY,
+    blurRadius: layer.blurRadius ?? 0,
+    spreadDistance: layer.spreadDistance ?? 0,
+    color: layer.color ?? "black",
+    inset: layer.inset ?? false
+  }));
+}
+function pairBoxShadowLayers(from, to) {
+  const count = Math.max(from.length, to.length);
+  const pairs = [];
+  for (let i = 0; i < count; i++) {
+    const a = from[i];
+    const b = to[i];
+    const fromLayer = a ?? invisibleLayer(b.inset);
+    const toLayer = b ?? invisibleLayer(a.inset);
+    if (fromLayer.inset !== toLayer.inset) {
+      throw new Error(
+        `[inertia] useShadow: boxShadow layer ${i} is 'inset' on one side but not the other \u2014 inset cannot be interpolated. Give both sides the same inset-ness (pad with a transparent layer if needed).`
+      );
+    }
+    pairs.push({ from: fromLayer, to: toLayer });
+  }
+  return pairs;
+}
+function invisibleLayer(inset) {
+  return {
+    offsetX: 0,
+    offsetY: 0,
+    blurRadius: 0,
+    spreadDistance: 0,
+    color: "transparent",
+    inset
+  };
+}
+
+// src/values/useShadow.ts
 function useShadow({
   from,
   to,
@@ -181,6 +302,10 @@ function useShadow({
   const hasElevation = from.elevation !== void 0 || to.elevation !== void 0;
   const hasColor = from.shadowColor !== void 0 || to.shadowColor !== void 0;
   const hasOffset = from.shadowOffset !== void 0 || to.shadowOffset !== void 0;
+  const boxShadowPairs = from.boxShadow !== void 0 || to.boxShadow !== void 0 ? pairBoxShadowLayers(
+    resolveBoxShadowInput(from.boxShadow),
+    resolveBoxShadowInput(to.boxShadow)
+  ) : [];
   const opacityFrom = from.shadowOpacity ?? 0;
   const opacityTo = to.shadowOpacity ?? 0;
   const radiusFrom = from.shadowRadius ?? 0;
@@ -215,6 +340,31 @@ function useShadow({
         height: interpolate(t, [0, 1], [offsetHFrom, offsetHTo])
       };
     }
+    if (boxShadowPairs.length > 0) {
+      let css = "";
+      let first = true;
+      for (const pair of boxShadowPairs) {
+        const x = interpolate(t, [0, 1], [pair.from.offsetX, pair.to.offsetX]);
+        const y = interpolate(t, [0, 1], [pair.from.offsetY, pair.to.offsetY]);
+        const blur = Math.max(
+          0,
+          interpolate(t, [0, 1], [pair.from.blurRadius, pair.to.blurRadius])
+        );
+        const spread = interpolate(
+          t,
+          [0, 1],
+          [pair.from.spreadDistance, pair.to.spreadDistance]
+        );
+        const color = interpolateColor(
+          t,
+          [0, 1],
+          [pair.from.color, pair.to.color]
+        );
+        css += (first ? "" : ", ") + (pair.from.inset ? "inset " : "") + `${x}px ${y}px ${blur}px ${spread}px ${color}`;
+        first = false;
+      }
+      out.boxShadow = css;
+    }
     return out;
   });
 }

package/dist/motion/Image.d.mts

@@ -1,5 +1,5 @@
 import { Image } from 'react-native';
-import { M as MotionComponent } from '../types-BzEgiUdJ.mjs';
+import { M as MotionComponent } from '../types-G1dBU2IQ.mjs';
 import 'react';
 
 /**

package/dist/motion/Image.d.ts

@@ -1,5 +1,5 @@
 import { Image } from 'react-native';
-import { M as MotionComponent } from '../types-BzEgiUdJ.js';
+import { M as MotionComponent } from '../types-G1dBU2IQ.js';
 import 'react';
 
 /**

package/dist/motion/Pressable.d.mts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import * as react_native from 'react-native';
-import { M as MotionComponent } from '../types-BzEgiUdJ.mjs';
+import { M as MotionComponent } from '../types-G1dBU2IQ.mjs';
 
 /**
  * Animatable `Pressable`. The `gesture` prop's `pressed` sub-state hooks into

package/dist/motion/Pressable.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import * as react_native from 'react-native';
-import { M as MotionComponent } from '../types-BzEgiUdJ.js';
+import { M as MotionComponent } from '../types-G1dBU2IQ.js';
 
 /**
  * Animatable `Pressable`. The `gesture` prop's `pressed` sub-state hooks into

package/dist/motion/ScrollView.d.mts

@@ -1,5 +1,5 @@
 import { ScrollView } from 'react-native';
-import { M as MotionComponent } from '../types-BzEgiUdJ.mjs';
+import { M as MotionComponent } from '../types-G1dBU2IQ.mjs';
 import 'react';
 
 /**

package/dist/motion/ScrollView.d.ts

@@ -1,5 +1,5 @@
 import { ScrollView } from 'react-native';
-import { M as MotionComponent } from '../types-BzEgiUdJ.js';
+import { M as MotionComponent } from '../types-G1dBU2IQ.js';
 import 'react';
 
 /**

package/dist/motion/Text.d.mts

@@ -1,5 +1,5 @@
 import { Text } from 'react-native';
-import { M as MotionComponent } from '../types-BzEgiUdJ.mjs';
+import { M as MotionComponent } from '../types-G1dBU2IQ.mjs';
 import 'react';
 
 /**

package/dist/motion/Text.d.ts

@@ -1,5 +1,5 @@
 import { Text } from 'react-native';
-import { M as MotionComponent } from '../types-BzEgiUdJ.js';
+import { M as MotionComponent } from '../types-G1dBU2IQ.js';
 import 'react';
 
 /**

package/dist/motion/View.d.mts

@@ -1,5 +1,5 @@
 import { View } from 'react-native';
-import { M as MotionComponent } from '../types-BzEgiUdJ.mjs';
+import { M as MotionComponent } from '../types-G1dBU2IQ.mjs';
 import 'react';
 
 /**

package/dist/motion/View.d.ts

@@ -1,5 +1,5 @@
 import { View } from 'react-native';
-import { M as MotionComponent } from '../types-BzEgiUdJ.js';
+import { M as MotionComponent } from '../types-G1dBU2IQ.js';
 import 'react';
 
 /**

package/dist/reanimated/index.d.mts

@@ -0,0 +1 @@
+export { default as Animated, AnimatedProps, AnimatedStyle, DerivedValue, Extrapolation, SharedValue, cancelAnimation, createAnimatedComponent, interpolate, interpolateColor, useAnimatedProps, useAnimatedStyle, useDerivedValue } from 'react-native-reanimated';

package/dist/reanimated/index.d.ts

@@ -0,0 +1 @@
+export { default as Animated, AnimatedProps, AnimatedStyle, DerivedValue, Extrapolation, SharedValue, cancelAnimation, createAnimatedComponent, interpolate, interpolateColor, useAnimatedProps, useAnimatedStyle, useDerivedValue } from 'react-native-reanimated';

package/dist/reanimated/index.js

@@ -0,0 +1,46 @@
+'use strict';
+
+var reactNativeReanimated = require('react-native-reanimated');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var reactNativeReanimated__default = /*#__PURE__*/_interopDefault(reactNativeReanimated);
+
+
+
+Object.defineProperty(exports, "Animated", {
+  enumerable: true,
+  get: function () { return reactNativeReanimated__default.default; }
+});
+Object.defineProperty(exports, "Extrapolation", {
+  enumerable: true,
+  get: function () { return reactNativeReanimated.Extrapolation; }
+});
+Object.defineProperty(exports, "cancelAnimation", {
+  enumerable: true,
+  get: function () { return reactNativeReanimated.cancelAnimation; }
+});
+Object.defineProperty(exports, "createAnimatedComponent", {
+  enumerable: true,
+  get: function () { return reactNativeReanimated.createAnimatedComponent; }
+});
+Object.defineProperty(exports, "interpolate", {
+  enumerable: true,
+  get: function () { return reactNativeReanimated.interpolate; }
+});
+Object.defineProperty(exports, "interpolateColor", {
+  enumerable: true,
+  get: function () { return reactNativeReanimated.interpolateColor; }
+});
+Object.defineProperty(exports, "useAnimatedProps", {
+  enumerable: true,
+  get: function () { return reactNativeReanimated.useAnimatedProps; }
+});
+Object.defineProperty(exports, "useAnimatedStyle", {
+  enumerable: true,
+  get: function () { return reactNativeReanimated.useAnimatedStyle; }
+});
+Object.defineProperty(exports, "useDerivedValue", {
+  enumerable: true,
+  get: function () { return reactNativeReanimated.useDerivedValue; }
+});

package/dist/reanimated/index.mjs

@@ -0,0 +1 @@
+export { default as Animated, Extrapolation, cancelAnimation, createAnimatedComponent, interpolate, interpolateColor, useAnimatedProps, useAnimatedStyle, useDerivedValue } from 'react-native-reanimated';

package/dist/touch/index.d.mts

@@ -1,6 +1,6 @@
 import { PanResponderInstance } from 'react-native';
 import { useAnimatedStyle, SharedValue } from 'react-native-reanimated';
-import { a as TransitionConfig } from '../types-BzEgiUdJ.mjs';
+import { T as TransitionConfig } from '../types-G1dBU2IQ.mjs';
 import 'react';
 
 /**

package/dist/touch/index.d.ts

@@ -1,6 +1,6 @@
 import { PanResponderInstance } from 'react-native';
 import { useAnimatedStyle, SharedValue } from 'react-native-reanimated';
-import { a as TransitionConfig } from '../types-BzEgiUdJ.js';
+import { T as TransitionConfig } from '../types-G1dBU2IQ.js';
 import 'react';
 
 /**

package/dist/{types-BzEgiUdJ.d.mts → types-G1dBU2IQ.d.mts}

@@ -385,4 +385,4 @@ interface MotionComponent<C extends ComponentType<any>> {
     displayName?: string;
 }
 
-export type { AnimatableValue as A, DecayTransition as D, EasingInput as E, GestureSubStates as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionInput as T, VariantController as V, TransitionConfig as a, TransitionName as b, AnimateStyle as c, AnimationCallbackInfo as d, EasingFunction as e, EasingFunctionFactory as f, MotionProps as g, NoAnimationTransition as h, RepeatConfig as i, SequenceStep as j, TimingTransition as k, Transition as l, VariantsMap as m, GestureLayerTransitions as n };
+export type { AnimatableValue as A, DecayTransition as D, EasingInput as E, GestureLayerTransitions as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionConfig as T, VariantController as V, TransitionInput as a, TransitionName as b, AnimateStyle as c, AnimationCallbackInfo as d, EasingFunction as e, EasingFunctionFactory as f, GestureSubStates as g, MotionProps as h, NoAnimationTransition as i, RepeatConfig as j, SequenceStep as k, TimingTransition as l, Transition as m, VariantsMap as n };

package/dist/{types-BzEgiUdJ.d.ts → types-G1dBU2IQ.d.ts}

@@ -385,4 +385,4 @@ interface MotionComponent<C extends ComponentType<any>> {
     displayName?: string;
 }
 
-export type { AnimatableValue as A, DecayTransition as D, EasingInput as E, GestureSubStates as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionInput as T, VariantController as V, TransitionConfig as a, TransitionName as b, AnimateStyle as c, AnimationCallbackInfo as d, EasingFunction as e, EasingFunctionFactory as f, MotionProps as g, NoAnimationTransition as h, RepeatConfig as i, SequenceStep as j, TimingTransition as k, Transition as l, VariantsMap as m, GestureLayerTransitions as n };
+export type { AnimatableValue as A, DecayTransition as D, EasingInput as E, GestureLayerTransitions as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionConfig as T, VariantController as V, TransitionInput as a, TransitionName as b, AnimateStyle as c, AnimationCallbackInfo as d, EasingFunction as e, EasingFunctionFactory as f, GestureSubStates as g, MotionProps as h, NoAnimationTransition as i, RepeatConfig as j, SequenceStep as k, TimingTransition as l, Transition as m, VariantsMap as n };

package/dist/{useGesture-BRLgiNOC.d.ts → useGesture-D1e4ixJo.d.ts}

@@ -1,5 +1,5 @@
 import { SharedValue } from 'react-native-reanimated';
-import { T as TransitionInput, n as GestureLayerTransitions } from './types-BzEgiUdJ.js';
+import { a as TransitionInput, G as GestureLayerTransitions } from './types-G1dBU2IQ.js';
 
 /**
  * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the

package/dist/{useGesture-C0GBS7d2.d.mts → useGesture-RFY6kTL3.d.mts}

@@ -1,5 +1,5 @@
 import { SharedValue } from 'react-native-reanimated';
-import { T as TransitionInput, n as GestureLayerTransitions } from './types-BzEgiUdJ.mjs';
+import { a as TransitionInput, G as GestureLayerTransitions } from './types-G1dBU2IQ.mjs';
 
 /**
  * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the

package/llms.txt

@@ -30,6 +30,8 @@ import {
 } from '@rootnative/inertia'
 // Opt-in MD3 / iOS state-layer overlay helper:
 import { useGestureLayer } from '@rootnative/inertia/gesture-layer'
+// Render-layer Reanimated interop for custom animated components:
+import { Animated, useAnimatedStyle } from '@rootnative/inertia/reanimated'
 // or for tree-shaking the primitives:
 import { MotionView } from '@rootnative/inertia/view'
 import { MotionText } from '@rootnative/inertia/text'
@@ -51,7 +53,7 @@ import { MotionScrollView } from '@rootnative/inertia/scroll-view'
 - `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`) 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.
+- `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.
 - `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`.
@@ -60,6 +62,8 @@ import { MotionScrollView } from '@rootnative/inertia/scroll-view'
 - `resolveAnimatableValue(value, base, factory?)` — one level up: resolves a full per-property `animate` value (plain target, `{ to, ...override }` step, or keyframe array → `withSequence` with sequence-level `repeat`) into one animation. Gives custom components the complete `animate` grammar.
 - `cubicBezier(x1, y1, x2, y2)` / `cubicBezier(css)` — builds a `timing.easing` value from cubic-bezier control points: four numbers, a W3C CSS `cubic-bezier(0.2, 0, 0, 1)` string (design-token form), or a CSS keyword (`'linear'` | `'ease'` | `'ease-in'` | `'ease-out'` | `'ease-in-out'`). Makes CSS-format easing tokens directly consumable — pair with named transitions to feed a theme's motion tokens into the registry. Invalid input throws (`x1`/`x2` must be within [0, 1]; `step-*` and `linear(...)` unsupported).
 - `ensureWorkletEasing(easing)` — normalizes any accepted easing input (plain function, worklet, or Reanimated 4 `EasingFunctionFactory`) into a worklet `withTiming` can consume. Only needed for manual `withTiming` calls — the resolvers and primitives apply it automatically.
+- `SharedValue<T>` (type) — re-exported from the root entry so props/refs that carry a value-layer hook result can be typed without importing from `react-native-reanimated`.
+- `@rootnative/inertia/reanimated` — render-layer interop subpath: pure re-exports of `Animated`, `createAnimatedComponent`, `useAnimatedStyle`, `useAnimatedProps`, `useDerivedValue`, `interpolate`, `interpolateColor`, `Extrapolation`, `cancelAnimation` (plus `SharedValue` / `DerivedValue` / `AnimatedStyle` / `AnimatedProps` types) under their original Reanimated names, for components that own their own `useAnimatedStyle` worklet over Inertia-driven shared values. Names must stay original — the Reanimated Babel plugin auto-workletizes callbacks by callee name. The `with*` animation factories are deliberately not re-exported; start animations with `useAnimation` / `resolveTransition` / `buildReleaseAnimation`.
 
 ## Motion props
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootnative/inertia",
-  "version": "0.0.0-alpha.5",
+  "version": "0.0.0-alpha.7",
   "description": "Declarative animation primitives for React Native, built on react-native-reanimated.",
   "license": "MIT",
   "author": "RootNative",
@@ -93,6 +93,13 @@
       "import": "./dist/gestureLayer/index.mjs",
       "require": "./dist/gestureLayer/index.js"
     },
+    "./reanimated": {
+      "types": "./dist/reanimated/index.d.ts",
+      "react-native": "./src/reanimated/index.ts",
+      "source": "./src/reanimated/index.ts",
+      "import": "./dist/reanimated/index.mjs",
+      "require": "./dist/reanimated/index.js"
+    },
     "./jest-preset": "./jest-preset.js",
     "./jest-setup": "./jest-setup.js",
     "./package.json": "./package.json"

package/src/index.ts

@@ -51,7 +51,13 @@ export {
   useTransform,
   useVariants,
 } from './values'
+// The value-layer hooks above all return Reanimated `SharedValue`s — export
+// the type so consumers can annotate props/refs that carry one (e.g. a
+// scroll-offset prop) without importing from `react-native-reanimated`.
+// Runtime render-layer interop lives in `@rootnative/inertia/reanimated`.
+export type { SharedValue } from 'react-native-reanimated'
 export type {
+  BoxShadowLayer,
   ColorStyleKey,
   ExtrapolationMode,
   ShadowConfig,

package/src/internal/boxShadow.ts

@@ -0,0 +1,204 @@
+/**
+ * CSS `box-shadow` parsing + pairing for `useShadow`.
+ *
+ * Design systems store web elevation tokens as CSS `box-shadow` strings
+ * (`'0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'`).
+ * Like `cubicBezier`, this module makes those tokens directly consumable:
+ * strings are parsed once on the JS thread into flat layer records the
+ * `useShadow` worklet can interpolate without any frame-time string work.
+ *
+ * Invalid input **throws** rather than warning — shadow tokens are
+ * constructed at theme/module setup, and a malformed token should fail
+ * loudly there, not silently render the wrong elevation.
+ */
+
+/**
+ * One layer of a `box-shadow`, structurally mirroring React Native's
+ * `BoxShadowValue` (RN 0.76+ `boxShadow` style). Lengths are px numbers.
+ */
+export interface BoxShadowLayer {
+  offsetX: number
+  offsetY: number
+  /** Must be >= 0, per CSS. @default 0 */
+  blurRadius?: number
+  /** @default 0 */
+  spreadDistance?: number
+  /** Any color string Reanimated's `interpolateColor` accepts. @default 'black' */
+  color?: string
+  /** @default false */
+  inset?: boolean
+}
+
+/** A layer with every field resolved to a concrete value. */
+export interface ResolvedBoxShadowLayer {
+  offsetX: number
+  offsetY: number
+  blurRadius: number
+  spreadDistance: number
+  color: string
+  inset: boolean
+}
+
+const LENGTH = /^[+-]?(\d+\.?\d*|\.\d+)(px)?$/i
+const UNIT_LIKE = /^[+-]?(\d+\.?\d*|\.\d+)[a-z%]+$/i
+
+function invalid(input: string, reason: string): Error {
+  return new Error(
+    `[inertia] parseBoxShadow: ${reason} in ${JSON.stringify(input)}. ` +
+      'Expected CSS box-shadow syntax with px lengths: ' +
+      "'[inset] <offset-x> <offset-y> [blur] [spread] [color], ...'",
+  )
+}
+
+/**
+ * Split a box-shadow string into layer strings on top-level commas —
+ * commas inside color functions (`rgba(0, 0, 0, 0.3)`) don't split.
+ */
+function splitLayers(input: string): string[] {
+  const layers: string[] = []
+  let depth = 0
+  let start = 0
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i]
+    if (ch === '(') depth++
+    else if (ch === ')') depth--
+    else if (ch === ',' && depth === 0) {
+      layers.push(input.slice(start, i))
+      start = i + 1
+    }
+  }
+  layers.push(input.slice(start))
+  return layers
+}
+
+/**
+ * Split one layer into whitespace-separated tokens, keeping color
+ * functions (which may contain spaces: `rgb(0 0 0 / 40%)`) as one token.
+ */
+function tokenize(layer: string): string[] {
+  const tokens: string[] = []
+  let depth = 0
+  let current = ''
+  for (const ch of layer) {
+    if (ch === '(') depth++
+    else if (ch === ')') depth--
+    if (depth === 0 && /\s/.test(ch)) {
+      if (current) tokens.push(current)
+      current = ''
+    } else {
+      current += ch
+    }
+  }
+  if (current) tokens.push(current)
+  return tokens
+}
+
+/**
+ * Parse a CSS `box-shadow` string into resolved layers. `'none'` parses to
+ * an empty list. Only px (and unitless) lengths are supported — other units
+ * depend on font/viewport context that a style value can't resolve.
+ */
+export function parseBoxShadow(input: string): ResolvedBoxShadowLayer[] {
+  const trimmed = input.trim()
+  if (trimmed === '') throw invalid(input, 'empty string')
+  if (trimmed.toLowerCase() === 'none') return []
+
+  return splitLayers(trimmed).map((layerString) => {
+    const tokens = tokenize(layerString.trim())
+    if (tokens.length === 0) throw invalid(input, 'empty layer')
+
+    const lengths: number[] = []
+    let color: string | undefined
+    let inset = false
+    for (const token of tokens) {
+      if (token.toLowerCase() === 'inset') {
+        if (inset) throw invalid(input, "duplicate 'inset'")
+        inset = true
+      } else if (LENGTH.test(token)) {
+        lengths.push(parseFloat(token))
+      } else if (UNIT_LIKE.test(token)) {
+        throw invalid(input, `unsupported unit in ${JSON.stringify(token)}`)
+      } else {
+        if (color !== undefined) throw invalid(input, 'multiple colors')
+        color = token
+      }
+    }
+
+    if (lengths.length < 2 || lengths.length > 4) {
+      throw invalid(input, `expected 2-4 lengths, got ${lengths.length}`)
+    }
+    // The `= 0` on the offsets never fires (length >= 2 is validated
+    // above); it's here for noUncheckedIndexedAccess.
+    const [offsetX = 0, offsetY = 0, blurRadius = 0, spreadDistance = 0] =
+      lengths
+    if (blurRadius < 0) throw invalid(input, 'negative blur radius')
+
+    return {
+      offsetX,
+      offsetY,
+      blurRadius,
+      spreadDistance,
+      color: color ?? 'black',
+      inset,
+    }
+  })
+}
+
+/** Resolve either input form (CSS string or structured layers) to layers. */
+export function resolveBoxShadowInput(
+  input: string | readonly BoxShadowLayer[] | undefined,
+): ResolvedBoxShadowLayer[] {
+  if (input === undefined) return []
+  if (typeof input === 'string') return parseBoxShadow(input)
+  return input.map((layer) => ({
+    offsetX: layer.offsetX,
+    offsetY: layer.offsetY,
+    blurRadius: layer.blurRadius ?? 0,
+    spreadDistance: layer.spreadDistance ?? 0,
+    color: layer.color ?? 'black',
+    inset: layer.inset ?? false,
+  }))
+}
+
+/**
+ * Pair up `from`/`to` layer lists for interpolation, CSS-transition style:
+ * the shorter list is padded with an invisible layer (all lengths 0,
+ * transparent color) matching the counterpart's `inset` flag. A genuine
+ * `inset` mismatch between paired layers is not interpolable and throws.
+ */
+export function pairBoxShadowLayers(
+  from: ResolvedBoxShadowLayer[],
+  to: ResolvedBoxShadowLayer[],
+): Array<{ from: ResolvedBoxShadowLayer; to: ResolvedBoxShadowLayer }> {
+  const count = Math.max(from.length, to.length)
+  const pairs: Array<{
+    from: ResolvedBoxShadowLayer
+    to: ResolvedBoxShadowLayer
+  }> = []
+  for (let i = 0; i < count; i++) {
+    const a = from[i]
+    const b = to[i]
+    const fromLayer = a ?? invisibleLayer(b!.inset)
+    const toLayer = b ?? invisibleLayer(a!.inset)
+    if (fromLayer.inset !== toLayer.inset) {
+      throw new Error(
+        `[inertia] useShadow: boxShadow layer ${i} is 'inset' on one side ` +
+          'but not the other — inset cannot be interpolated. Give both ' +
+          'sides the same inset-ness (pad with a transparent layer if needed).',
+      )
+    }
+    pairs.push({ from: fromLayer, to: toLayer })
+  }
+  return pairs
+}
+
+function invisibleLayer(inset: boolean): ResolvedBoxShadowLayer {
+  return {
+    offsetX: 0,
+    offsetY: 0,
+    blurRadius: 0,
+    spreadDistance: 0,
+    color: 'transparent',
+    inset,
+  }
+}

package/src/reanimated/index.ts

@@ -0,0 +1,43 @@
+/**
+ * `@rootnative/inertia/reanimated` — the render-layer interop surface for
+ * building custom animated components on top of Inertia's value layer
+ * (`useMotionValue` / `useSpring` / `useGesture` / `useScroll` / …).
+ *
+ * Inertia's contract is that consumers should not need to import from
+ * `react-native-reanimated` directly. Most of the time the declarative
+ * `Motion.*` primitives cover that; when they don't — a component that owns
+ * its own `useAnimatedStyle` worklet over Inertia-driven shared values —
+ * this subpath provides the remaining rendering primitives so the consumer's
+ * animation dependency stays `@rootnative/inertia` alone.
+ *
+ * Scope is deliberately render-layer only: animated host components, the
+ * animated style/props hooks, worklet-safe interpolators, and cancellation.
+ * Starting animations stays in Inertia's transition vocabulary —
+ * `useAnimation` / `useSpring` declaratively, `resolveTransition` /
+ * `buildReleaseAnimation` imperatively — so the `with*` animation factories
+ * are intentionally not re-exported here.
+ *
+ * Everything is re-exported under its original Reanimated name. That is a
+ * hard constraint, not a style choice: the Reanimated Babel plugin
+ * auto-workletizes the callbacks passed to `useAnimatedStyle` /
+ * `useAnimatedProps` / `useDerivedValue` by callee *name*, so a renamed
+ * wrapper would silently stop workletizing consumer callbacks. Re-exports
+ * keep the name and the behavior from any import path.
+ */
+export {
+  default as Animated,
+  Extrapolation,
+  cancelAnimation,
+  createAnimatedComponent,
+  interpolate,
+  interpolateColor,
+  useAnimatedProps,
+  useAnimatedStyle,
+  useDerivedValue,
+} from 'react-native-reanimated'
+export type {
+  AnimatedProps,
+  AnimatedStyle,
+  DerivedValue,
+  SharedValue,
+} from 'react-native-reanimated'

package/src/values/index.ts

@@ -20,6 +20,7 @@ export {
 export { useScroll, type UseScrollResult } from './useScroll'
 export {
   useShadow,
+  type BoxShadowLayer,
   type ShadowConfig,
   type UseShadowOptions,
 } from './useShadow'

package/src/values/useShadow.ts

@@ -4,12 +4,20 @@ import {
   useAnimatedStyle,
   type SharedValue,
 } from 'react-native-reanimated'
+import {
+  pairBoxShadowLayers,
+  resolveBoxShadowInput,
+  type BoxShadowLayer,
+} from '../internal/boxShadow'
+
+export type { BoxShadowLayer }
 
 /**
  * Shape accepted on either end of a `useShadow` tween. Every field is
  * optional — only keys present on at least one side participate in the
  * output style. Mirrors the flat shadow keys on `Motion.View`'s `animate`
- * surface, plus the nested `shadowOffset` source.
+ * surface, plus the nested `shadowOffset` source and the CSS `boxShadow`
+ * surface.
  */
 export interface ShadowConfig {
   shadowOpacity?: number
@@ -18,6 +26,19 @@ export interface ShadowConfig {
   /** Android elevation. iOS shadow consumers can leave this off. */
   elevation?: number
   shadowColor?: string
+  /**
+   * CSS `box-shadow` — the shadow surface on web (react-native-web passes
+   * it through as CSS) and on React Native 0.76+ new-architecture native.
+   * Accepts the CSS string form design systems store elevation tokens in
+   * (`'0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'`;
+   * px lengths only) or structured layers. Multi-layer shadows interpolate
+   * per layer; when one side has fewer layers, it is padded with invisible
+   * layers, CSS-transition style. A malformed string **throws** at render
+   * (like `cubicBezier` — token mistakes should fail loudly at setup).
+   * The classic `shadow*`/`elevation` keys don't reach the web renderer —
+   * provide `boxShadow` alongside them when the tween must show up there.
+   */
+  boxShadow?: string | readonly BoxShadowLayer[]
 }
 
 export interface UseShadowOptions {
@@ -56,6 +77,19 @@ export interface UseShadowOptions {
  * `shadowColor`, `{ width: 0, height: 0 }` for `shadowOffset`). This is a
  * pure interpolator — to "animate" the shadow, drive `progress` with a
  * spring, timing, or gesture upstream.
+ *
+ * The classic `shadow*`/`elevation` keys don't render on web. When the
+ * tween must show up there (or on RN 0.76+ new-arch native via the CSS
+ * shadow model), provide `boxShadow` on both ends — CSS string tokens or
+ * structured layers; multi-layer shadows interpolate per layer:
+ *
+ * ```tsx
+ * const shadowStyle = useShadow({
+ *   from: { boxShadow: theme.elevation.level1 }, // '0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'
+ *   to:   { boxShadow: theme.elevation.level2 },
+ *   progress,
+ * })
+ * ```
  */
 export function useShadow({
   from,
@@ -76,6 +110,17 @@ export function useShadow({
   const hasOffset =
     from.shadowOffset !== undefined || to.shadowOffset !== undefined
 
+  // boxShadow layers: parse/pair once on the JS thread into flat records so
+  // the worklet only interpolates numbers/colors and concatenates — no
+  // frame-time parsing. `[]` when neither side provides the key.
+  const boxShadowPairs =
+    from.boxShadow !== undefined || to.boxShadow !== undefined
+      ? pairBoxShadowLayers(
+          resolveBoxShadowInput(from.boxShadow),
+          resolveBoxShadowInput(to.boxShadow),
+        )
+      : []
+
   const opacityFrom = from.shadowOpacity ?? 0
   const opacityTo = to.shadowOpacity ?? 0
   const radiusFrom = from.shadowRadius ?? 0
@@ -111,6 +156,36 @@ export function useShadow({
         height: interpolate(t, [0, 1], [offsetHFrom, offsetHTo]),
       }
     }
+    if (boxShadowPairs.length > 0) {
+      let css = ''
+      let first = true
+      for (const pair of boxShadowPairs) {
+        const x = interpolate(t, [0, 1], [pair.from.offsetX, pair.to.offsetX])
+        const y = interpolate(t, [0, 1], [pair.from.offsetY, pair.to.offsetY])
+        // Blur can't go negative (invalid CSS) even if a springy driver
+        // overshoots below 0.
+        const blur = Math.max(
+          0,
+          interpolate(t, [0, 1], [pair.from.blurRadius, pair.to.blurRadius]),
+        )
+        const spread = interpolate(
+          t,
+          [0, 1],
+          [pair.from.spreadDistance, pair.to.spreadDistance],
+        )
+        const color = interpolateColor(
+          t,
+          [0, 1],
+          [pair.from.color, pair.to.color],
+        )
+        css +=
+          (first ? '' : ', ') +
+          (pair.from.inset ? 'inset ' : '') +
+          `${x}px ${y}px ${blur}px ${spread}px ${color}`
+        first = false
+      }
+      out.boxShadow = css
+    }
     return out
   })
 }