@humanspeak/svelte-motion 0.5.0 → 0.5.2

package/dist/html/_MotionContainer.svelte

@@ -17,17 +17,21 @@
         DragControls,
         DragTransition,
         MotionWhileDrag,
-        DragInfo
+        DragInfo,
+        MotionOnPan,
+        MotionOnPanEnd,
+        MotionOnPanSessionStart,
+        MotionOnPanStart
     } from '../types'
     import { isNotEmpty } from '../utils/objects'
     import { sleep } from '../utils/testing'
     import { animate, type AnimationOptions, type DOMKeyframesDefinition } from 'motion'
     import { isPlaywrightEnv, pwLog } from '../utils/log'
-    import { onDestroy, type Snippet } from 'svelte'
+    import { onDestroy, untrack, type Snippet } from 'svelte'
     import { VOID_TAGS } from '../utils/constants'
     import { mergeTransitions, animateWithLifecycle } from '../utils/animation'
     import { attachWhileTap } from '../utils/interaction'
-    import { attachWhileHover } from '../utils/hover'
+    import { attachWhileHover, computeHoverBaseline, splitHoverDefinition } from '../utils/hover'
     import { attachWhileFocus } from '../utils/focus'
     import { attachWhileInView } from '../utils/inView.svelte'
     import {
@@ -48,6 +52,7 @@
     } from '../utils/presence'
     import { getInitialKeyframes } from '../utils/initial'
     import { attachDrag } from '../utils/drag'
+    import { attachPan, type AttachPanCleanup } from '../utils/pan'
     import { resolveInitial, resolveAnimate, resolveExit, resolveWhile } from '../utils/variants'
     import {
         setVariantContext,
@@ -97,6 +102,11 @@
         whileInView: whileInViewProp,
         viewport: viewportProp,
         whileDrag: whileDragProp,
+        whilePan: whilePanProp,
+        onPanSessionStart: onPanSessionStartProp,
+        onPanStart: onPanStartProp,
+        onPan: onPanProp,
+        onPanEnd: onPanEndProp,
         onHoverStart: onHoverStartProp,
         onHoverEnd: onHoverEndProp,
         onFocusStart: onFocusStartProp,
@@ -455,6 +465,7 @@
     const resolvedWhileHover = $derived(resolveWhile(whileHoverProp, variantsProp, effectiveCustom))
     const resolvedWhileFocus = $derived(resolveWhile(whileFocusProp, variantsProp, effectiveCustom))
     const resolvedWhileDrag = $derived(resolveWhile(whileDragProp, variantsProp, effectiveCustom))
+    const resolvedWhilePan = $derived(resolveWhile(whilePanProp, variantsProp, effectiveCustom))
     const resolvedWhileInView = $derived(
         resolveWhile(whileInViewProp, variantsProp, effectiveCustom)
     )
@@ -594,6 +605,172 @@
         }
     })
 
+    /**
+     * Pan-gesture wiring. Active whenever any of `onPanSessionStart`,
+     * `onPanStart`, `onPan`, `onPanEnd`, or `whilePan` is set. Unlike
+     * `drag`, Pan has no constraints / momentum / origin-snap — it's a
+     * pure pointer offset+velocity reporter, useful for swipe-to-dismiss
+     * sheets, custom carousels, and any "tell me what the gesture is
+     * doing right now" interaction. Mirrors framer-motion's `PanGesture`
+     * (packages/framer-motion/src/gestures/pan/index.ts).
+     *
+     * Split into TWO effects:
+     *
+     * 1. `attach` — keyed on `element`, `isLoaded === 'ready'`, presence
+     *    of any pan handler/whilePan, and absence of `drag` (drag takes
+     *    precedence — upstream framer-motion routes drag THROUGH the pan
+     *    gesture internally, so co-attaching pan when drag is on would
+     *    fight transforms). Creates / tears down the underlying
+     *    `attachPan` lifetime once per element-bound interval.
+     *
+     * 2. `swap` — keyed on the user's handler/whilePan props. Calls
+     *    `teardownPan.update(next)` to hot-swap the live handler set
+     *    without destroying the in-flight `PanSession`. Without this
+     *    split, every parent re-render that produces a fresh inline
+     *    arrow handler would tear down the live gesture mid-pan —
+     *    pointer listeners removed, no `onPanEnd` ever fires, whilePan
+     *    keyframes leak.
+     */
+    let teardownPan: AttachPanCleanup | null = null
+    let activeWhilePanKeyframes: Record<string, unknown> | null = null
+    let whilePanBaseline: Record<string, unknown> | null = null
+
+    /**
+     * Boolean presence-check for "is any pan surface active?". Derived
+     * so the attach effect below tracks the *boolean value*, not the
+     * individual handler/whilePan reference identities. A consumer
+     * passing `onPan={(e, i) => ...}` (inline arrow — fresh ref every
+     * render) used to re-trigger the attach effect on every parent
+     * render; with this derived in place, the attach effect only
+     * re-runs when overall presence flips (none → some, some → none).
+     * Per-ref changes flow through the hot-swap effect instead.
+     */
+    const hasAnyPanHandler = $derived(
+        !!onPanProp ||
+            !!onPanStartProp ||
+            !!onPanEndProp ||
+            !!onPanSessionStartProp ||
+            !!resolvedWhilePan
+    )
+
+    const buildPanHandlers = (): {
+        onSessionStart?: MotionOnPanSessionStart
+        onStart: NonNullable<MotionOnPanStart>
+        onMove?: MotionOnPan
+        onEnd: NonNullable<MotionOnPanEnd>
+    } => ({
+        onSessionStart: onPanSessionStartProp,
+        onStart: (event, info) => {
+            if (resolvedWhilePan && element) {
+                // Snapshot the values we'll revert to BEFORE applying — same
+                // `computeHoverBaseline` path the other while-* gestures
+                // (whileHover/whileFocus/drag) use. Covers animatable transform
+                // shorthands (scale, rotate, x, y) AND restores non-animatable
+                // inline writes (cursor, pointer-events) since the baseline
+                // sniffs `animate` → `initial` → computed style → inline style.
+                whilePanBaseline = computeHoverBaseline(element, {
+                    initial: (initialKeyframes ?? {}) as Record<string, unknown>,
+                    animate: (resolvedAnimate ?? {}) as Record<string, unknown>,
+                    whileHover: (resolvedWhilePan ?? {}) as Record<string, unknown>
+                })
+                const { keyframes, transition } = splitHoverDefinition(
+                    resolvedWhilePan as Record<string, unknown>
+                )
+                activeWhilePanKeyframes = keyframes
+                animateWithLifecycle(
+                    element,
+                    keyframes as unknown as DOMKeyframesDefinition,
+                    (transition ?? mergedTransition ?? {}) as unknown as AnimationOptions
+                )
+            }
+            onPanStartProp?.(event, info)
+        },
+        onMove: onPanProp,
+        onEnd: (event, info) => {
+            if (activeWhilePanKeyframes && whilePanBaseline && element) {
+                animateWithLifecycle(
+                    element,
+                    whilePanBaseline as unknown as DOMKeyframesDefinition,
+                    (mergedTransition ?? {}) as unknown as AnimationOptions
+                )
+            }
+            activeWhilePanKeyframes = null
+            whilePanBaseline = null
+            onPanEndProp?.(event, info)
+        }
+    })
+
+    $effect(() => {
+        if (isPlaywright) {
+            pwLog('[motion] pan attach effect run', {
+                hasAnyPanHandler,
+                isLoaded
+            })
+        }
+        if (!element) return
+        // Defer attachment until the element has settled out of the enter
+        // animation phase — matches the gate every other gesture effect
+        // in this file uses (drag, whileTap, whileHover, whileFocus,
+        // whileInView). Without this, a pointerdown during the
+        // initial / mounting phase would attach pan listeners against an
+        // element whose enter animation hasn't committed its baseline.
+        if (isLoaded !== 'ready') return
+        // Drag takes precedence — upstream framer-motion's drag gesture is
+        // implemented ON TOP of Pan, not alongside it. Co-attaching here
+        // would create two competing pointer pipelines fighting for the
+        // same transforms.
+        if (dragProp) return
+        if (!hasAnyPanHandler) return
+
+        // `untrack` so the reactive reads inside `buildPanHandlers`
+        // (onPan*Prop, resolvedWhilePan, initialKeyframes, resolvedAnimate,
+        // mergedTransition) don't register as dependencies of this attach
+        // effect. Otherwise every parent re-render that passes a fresh
+        // inline arrow handler would re-run this effect and call
+        // `teardownPan?.()`, killing the live PanSession mid-gesture.
+        // Handler-ref changes flow exclusively through the hot-swap
+        // effect below, which calls `teardownPan.update(next)` — that's
+        // the path that keeps an in-flight gesture alive across re-renders.
+        teardownPan = attachPan(
+            element,
+            untrack(() => buildPanHandlers())
+        )
+
+        return () => {
+            // Synchronous revert of whilePan + lifecycle dispatch lives in
+            // attachPan.teardown() — the cleanup chain there calls
+            // session.dispatchTerminal(rawHandlers) BEFORE flipping isAlive,
+            // so onPanEnd fires (which runs the revert above) before the
+            // listeners go. dispatchTerminal is idempotent (PanSession's
+            // terminalDispatched flag) so a host that tears down after a
+            // natural release won't replay the lifecycle pair.
+            teardownPan?.()
+            teardownPan = null
+            activeWhilePanKeyframes = null
+            whilePanBaseline = null
+        }
+    })
+
+    /**
+     * Hot-swap effect — propagates handler / whilePan changes onto the
+     * existing PanSession via `teardownPan.update(next)`. Tracked
+     * separately from the attach effect so a fresh inline-arrow handler
+     * reference does NOT trigger teardown + re-attach. Without this
+     * split, every parent re-render mid-gesture would silently kill the
+     * live pan session.
+     */
+    $effect(() => {
+        // Track every prop the handler set depends on so this effect
+        // re-runs when any of them change.
+        void onPanSessionStartProp
+        void onPanStartProp
+        void onPanProp
+        void onPanEndProp
+        void resolvedWhilePan
+        if (!teardownPan) return
+        teardownPan.update(buildPanHandlers())
+    })
+
     /**
      * Execute the actual animation without wait mode checks.
      */

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export type { AugmentedMotionValue } from './utils/augmentMotionValue.svelte';
 export { useCycle } from './utils/cycle.svelte';
 export type { Cycle, CycleState } from './utils/cycle.svelte';
 export { createDragControls } from './utils/dragControls';
+export { useFollowValue } from './utils/followValue.svelte';
+export type { FollowMotionValue, UseFollowValueOptions } from './utils/followValue.svelte';
 export { useInView } from './utils/inView.svelte';
 export type { InViewState, UseInViewOptions } from './utils/inView.svelte';
 export { useMotionTemplate } from './utils/motionTemplate.svelte';

package/dist/index.js

@@ -13,6 +13,7 @@ export { useAnimate } from './utils/animate.svelte';
 export { useAnimationFrame } from './utils/animationFrame';
 export { useCycle } from './utils/cycle.svelte';
 export { createDragControls } from './utils/dragControls';
+export { useFollowValue } from './utils/followValue.svelte';
 export { useInView } from './utils/inView.svelte';
 export { useMotionTemplate } from './utils/motionTemplate.svelte';
 export { useMotionValue } from './utils/motionValue.svelte';

package/dist/types.d.ts

@@ -246,6 +246,15 @@ export type MotionOnDrag = ((event: PointerEvent, info: DragInfo) => void) | und
 export type MotionOnDragEnd = ((event: PointerEvent, info: DragInfo) => void) | undefined;
 export type MotionOnDirectionLock = ((axis: 'x' | 'y') => void) | undefined;
 export type MotionOnDragTransitionEnd = (() => void) | undefined;
+/**
+ * Pan-gesture callbacks. PanInfo is structurally identical to DragInfo
+ * (`{ point, delta, offset, velocity }`), so we re-use the type rather
+ * than ship a parallel alias.
+ */
+export type MotionOnPanSessionStart = ((event: PointerEvent, info: DragInfo) => void) | undefined;
+export type MotionOnPanStart = ((event: PointerEvent, info: DragInfo) => void) | undefined;
+export type MotionOnPan = ((event: PointerEvent, info: DragInfo) => void) | undefined;
+export type MotionOnPanEnd = ((event: PointerEvent, info: DragInfo) => void) | undefined;
 export type DragAxis = boolean | 'x' | 'y';
 export type DragConstraints = {
     top?: number;
@@ -319,6 +328,8 @@ export type MotionProps = {
     whileFocus?: MotionWhileFocus;
     /** Drag interaction animation */
     whileDrag?: MotionWhileDrag;
+    /** Pan interaction animation — applied while a pan gesture is active */
+    whilePan?: MotionWhileDrag;
     /** In-view interaction animation - animates when element enters viewport */
     whileInView?: MotionWhileInView;
     /** IntersectionObserver options for `whileInView` (once / root / margin / amount) */
@@ -355,6 +366,14 @@ export type MotionProps = {
     onDirectionLock?: MotionOnDirectionLock;
     /** Called when the post-drag transition finishes on all axes */
     onDragTransitionEnd?: MotionOnDragTransitionEnd;
+    /** Pan gesture: fires once per pointerdown, before threshold */
+    onPanSessionStart?: MotionOnPanSessionStart;
+    /** Pan gesture: fires the first frame after offset crosses threshold */
+    onPanStart?: MotionOnPanStart;
+    /** Pan gesture: fires once per frame while panning */
+    onPan?: MotionOnPan;
+    /** Pan gesture: fires on pointerup if onPanStart ever fired */
+    onPanEnd?: MotionOnPanEnd;
     /** Inline styles */
     style?: string;
     /** CSS classes */

package/dist/utils/followValue.svelte.d.ts

@@ -0,0 +1,84 @@
+import { type FollowValueOptions, type MotionValue } from 'motion-dom';
+import { type Readable } from 'svelte/store';
+import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
+/**
+ * Options accepted by {@link useFollowValue}. Mirrors framer-motion's
+ * `FollowValueOptions` 1:1 — any `ValueAnimationTransition` shape (spring /
+ * tween / inertia / keyframes) plus `skipInitialAnimation` for
+ * scroll-restoration scenarios.
+ *
+ * The shape is re-exported from motion-dom so consumers don't have to
+ * cross-import.
+ *
+ * @see https://motion.dev/docs/react-use-follow-value
+ */
+export type UseFollowValueOptions = FollowValueOptions;
+/**
+ * The augmented `MotionValue` returned by {@link useFollowValue} (and, since
+ * `useSpring` now delegates here, by `useSpring` too).
+ */
+export type FollowMotionValue<T extends number | string> = AugmentedMotionValue<T>;
+/**
+ * Creates an animated `MotionValue` that, when `.set(v)` is called, animates
+ * toward `v` using **any** transition type — spring, tween, inertia, or
+ * keyframes. Pass another `MotionValue` (or Svelte readable) as the source
+ * and the result follows it: every source emit kicks off a new animation
+ * toward the latest value.
+ *
+ * Mirrors React framer-motion's `useFollowValue` 1:1. `useSpring` in this
+ * library is now a thin wrapper that delegates here with the default
+ * `{ type: 'spring' }`.
+ *
+ * Returned object is a real motion-dom `MotionValue` (composes with
+ * `useTransform`, `useVelocity`, `animate()`, etc.) augmented with a
+ * `$state`-backed `.current` getter and a Svelte readable `.subscribe`
+ * shim.
+ *
+ * Lifecycle: must be called during component initialization. Cleanup is
+ * registered via `$effect`; the follow animation stops, the source bridge
+ * (if any) tears down, and `value.destroy()` runs when the surrounding
+ * `$effect` scope unmounts.
+ *
+ * SSR-safe: returns a static augmented `MotionValue` with no animation on
+ * the server. `.set` and `.jump` become no-ops to avoid drifting away from
+ * the server-rendered snapshot.
+ *
+ * @template T The value type — `number` or `string` (unit strings preserved).
+ * @param source Initial value, a `MotionValue` to follow, or a Svelte readable.
+ * @param options Transition + follow configuration (`type: 'spring' | 'tween' | 'inertia' | 'keyframes'`, plus the corresponding per-type options).
+ * @returns A `MotionValue<T>` with `.current` and `.subscribe`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useFollowValue, useMotionValue } from '@humanspeak/svelte-motion'
+ *
+ *   const target = useMotionValue(0)
+ *
+ *   // Spring follow (default — same as `useSpring(target)`).
+ *   const spring = useFollowValue(target, { stiffness: 300, damping: 30 })
+ *
+ *   // Tween follow — eased linear interpolation.
+ *   const eased = useFollowValue(target, {
+ *     type: 'tween',
+ *     duration: 0.4,
+ *     ease: 'easeInOut'
+ *   })
+ *
+ *   // Inertia — decays from initial velocity.
+ *   const drifting = useFollowValue(0, { type: 'inertia', velocity: 800, power: 0.6 })
+ * </script>
+ *
+ * <button onclick={() => target.set(target.get() === 0 ? 200 : 0)}>Toggle</button>
+ * <div style="transform: translateX({spring.current}px)">spring</div>
+ * <div style="transform: translateX({eased.current}px)">tween</div>
+ * <div style="transform: translateX({drifting.current}px)">inertia</div>
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-follow-value
+ */
+export declare function useFollowValue(source: number, options?: UseFollowValueOptions): FollowMotionValue<number>;
+export declare function useFollowValue(source: string, options?: UseFollowValueOptions): FollowMotionValue<string>;
+export declare function useFollowValue(source: MotionValue<number>, options?: UseFollowValueOptions): FollowMotionValue<number>;
+export declare function useFollowValue(source: MotionValue<string>, options?: UseFollowValueOptions): FollowMotionValue<string>;
+export declare function useFollowValue<T extends number | string>(source: Readable<T>, options?: UseFollowValueOptions): FollowMotionValue<T>;

package/dist/utils/followValue.svelte.js

@@ -0,0 +1,51 @@
+import { attachFollow, isMotionValue, motionValue } from 'motion-dom';
+import {} from 'svelte/store';
+import { augmentMotionValue, isSvelteReadable, sampleSource } from './augmentMotionValue.svelte.js';
+export function useFollowValue(source, options = {}) {
+    // SSR: return a static MotionValue with no animation. Reads return the
+    // best-effort initial value; .set / .jump become no-ops to avoid drifting
+    // away from the server-rendered snapshot.
+    if (typeof window === 'undefined') {
+        const initial = sampleSource(source);
+        const ssrValue = motionValue(initial);
+        ssrValue.set = () => undefined;
+        ssrValue.jump = () => undefined;
+        return augmentMotionValue(ssrValue);
+    }
+    // Resolve initial + follow source. Svelte readables get bridged into a
+    // motion-dom MotionValue so `attachFollow` can subscribe to their emits.
+    let followSource;
+    let cleanupReadableBridge;
+    let svelteBridge;
+    if (isMotionValue(source)) {
+        followSource = source;
+    }
+    else if (isSvelteReadable(source)) {
+        const initialFromReadable = sampleSource(source);
+        svelteBridge = motionValue(initialFromReadable);
+        cleanupReadableBridge = source.subscribe((v) => {
+            // Svelte readable contract emits synchronously on subscribe. Skip
+            // the initial emit (already seeded above) so attachFollow doesn't
+            // fire an animation on attach.
+            if (svelteBridge.get() === v)
+                return;
+            svelteBridge.set(v);
+        });
+        followSource = svelteBridge;
+    }
+    else {
+        followSource = source;
+    }
+    const initial = isMotionValue(followSource) ? followSource.get() : followSource;
+    const value = motionValue(initial);
+    // Default transition is `spring` — matches React framer-motion's
+    // `useFollowValue` default. Caller's `type` (if set) overrides.
+    const stopFollow = attachFollow(value, followSource, { type: 'spring', ...options });
+    const dispose = () => {
+        stopFollow?.();
+        cleanupReadableBridge?.();
+        svelteBridge?.destroy();
+    };
+    $effect(() => () => value.destroy());
+    return augmentMotionValue(value, dispose);
+}

package/dist/utils/pan.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Pan gesture session.
+ *
+ * Direct port of framer-motion's `PanSession`
+ * (`packages/framer-motion/src/gestures/pan/PanSession.ts`) and `PanGesture`
+ * (`packages/framer-motion/src/gestures/pan/index.ts`). Pan is the
+ * primitive that powers swipe-to-dismiss drawers, swipe-to-delete rows,
+ * carousels, and any gesture that tracks pointer offset/velocity without
+ * the constraint/momentum/snap-to-origin baggage of `drag`.
+ *
+ * Critical design notes (mirrors upstream):
+ *
+ * - `pointermove`, `pointerup`, `pointercancel` subscribe on the
+ *   `contextWindow` (defaults to `window`), NOT the source element. This
+ *   keeps the gesture alive even when the pointer leaves the element's
+ *   bounds during a fast swipe — the original element is only used for
+ *   the initial `pointerdown` and for scroll-compensation tracking.
+ *
+ * - `distanceThreshold` (default `3`px) gates the `onStart` callback so
+ *   a steady press without movement doesn't fire a pan. `onSessionStart`
+ *   fires immediately on pointerdown for setup work.
+ *
+ * - Per-frame throttling via `frame.update(updatePoint, true)` so a flood
+ *   of pointermove events doesn't run handlers more than once per render
+ *   frame. On top of that, individual handlers are routed onto motion-dom's
+ *   step lanes (see `wrapUpdate` / `wrapPostRender` above):
+ *   `onSessionStart` / `onStart` / `onMove` land on `update`,
+ *   `onEnd` / `onSessionEnd` on `postRender`. Matches upstream's
+ *   `asyncHandler` + `frame.postRender` split byte-for-byte.
+ *
+ * - `getPanInfo` returns `{ point, delta, offset, velocity }` — identical
+ *   shape to motion-dom's `DragInfo` / framer-motion's `PanInfo`.
+ *
+ * - Velocity uses a 100ms history window with the "skip the pointer-down
+ *   origin if it's too stale" tweak upstream added for hold-then-flick
+ *   gestures.
+ */
+import type { DragInfo } from '../types';
+export interface PanHandlers {
+    /** Fires on `pointerdown` regardless of whether movement follows. */
+    onSessionStart?: (event: PointerEvent, info: DragInfo) => void;
+    /** Fires the first time pointer offset crosses `distanceThreshold`. */
+    onStart?: (event: PointerEvent, info: DragInfo) => void;
+    /** Fires on every per-frame-throttled pointermove past threshold. */
+    onMove?: (event: PointerEvent, info: DragInfo) => void;
+    /** Fires on `pointerup` / `pointercancel` if `onStart` ever fired. */
+    onEnd?: (event: PointerEvent, info: DragInfo) => void;
+    /** Fires on `pointerup` / `pointercancel` always (paired with `onSessionStart`). */
+    onSessionEnd?: (event: PointerEvent, info: DragInfo) => void;
+}
+export interface AttachPanOptions {
+    /**
+     * Movement distance (in pixels) required before `onStart`/`onMove`
+     * fire. Default `3` — same as framer-motion. A steady press with
+     * sub-threshold drift is reported via `onSessionStart` / `onSessionEnd`
+     * only.
+     */
+    distanceThreshold?: number;
+    /**
+     * Window to attach the move/up/cancel listeners to. Defaults to the
+     * source element's owner window. Override for iframe / shadow-root
+     * scenarios.
+     */
+    contextWindow?: Window | null;
+}
+/**
+ * Cleanup function returned by `attachPan`. Carries an `update` method
+ * that hot-swaps the live handler set without tearing down the active
+ * `PanSession` — call this when a consumer's `onPan` reference changes
+ * mid-gesture (the canonical Svelte 5 pattern of inline arrow handlers
+ * passes a fresh closure every render). Without this, the host
+ * `$effect` would have to teardown + re-attach and the user's in-flight
+ * pan would silently die.
+ */
+export type AttachPanCleanup = (() => void) & {
+    update: (next: PanHandlers) => void;
+};
+/**
+ * Attach a pan gesture session to `el`. Returns a cleanup function that
+ * tears down the pointerdown listener and ends any in-flight session,
+ * with a `.update(next)` method for hot-swapping handlers mid-gesture.
+ *
+ * Internally a fresh `PanSession` spawns on each pointerdown — the
+ * outer attachment just keeps the pointerdown listener alive across the
+ * element's lifetime.
+ *
+ * SSR-safe: returns a no-op cleanup if `window` is undefined. The Svelte
+ * `$effect` consumer never fires on the server anyway, but defending the
+ * boundary lets the module load cleanly in node-only test runners.
+ *
+ * Lifecycle guarantee: when the returned cleanup runs mid-gesture, the
+ * session synthesizes `onEnd` + `onSessionEnd` against the raw handlers
+ * BEFORE removing listeners (see `PanSession.dispatchTerminal`). Hosts
+ * (e.g. `_MotionContainer`'s pan `$effect`) can put their `whilePan`
+ * revert logic inside the user-supplied `onEnd` and rely on it firing
+ * exactly once per gesture — whether the user released or the host
+ * forced teardown.
+ *
+ * @param el Target element to bind `pointerdown` on. Move/up/cancel
+ *   events are listened for on the element's owning window so a fast
+ *   swipe past the element's bounds keeps the gesture alive.
+ * @param handlers Pan lifecycle handlers. Any subset of
+ *   `onSessionStart` (fires on pointerdown), `onStart` (fires the first
+ *   time the cumulative offset crosses `distanceThreshold`), `onMove`
+ *   (per-frame-throttled on every pointermove past threshold), `onEnd`
+ *   (fires on pointerup/cancel if `onStart` ever fired), `onSessionEnd`
+ *   (fires on every pointerup/cancel where a pointermove occurred).
+ * @param options Per-session config. `distanceThreshold` (default 3px)
+ *   gates the start callback; `contextWindow` overrides the owning
+ *   window (use for shadow-root / iframe scenarios).
+ * @returns A cleanup function with an attached `.update(next)` method.
+ *   Calling the cleanup ends the session + removes the pointerdown
+ *   listener. Calling `.update(next)` swaps handlers in place on the
+ *   live session without rebuilding it — the canonical Svelte pattern
+ *   for inline arrow handlers that change identity each render.
+ *
+ * @example
+ * ```ts
+ * const cleanup = attachPan(node, {
+ *   onStart: (_event, info) => console.log('start', info.offset),
+ *   onMove: (_event, info) => x.set(info.offset.x),
+ *   onEnd: (_event, info) => {
+ *     if (Math.abs(info.velocity.x) > 600) commit()
+ *     else animate(x, 0, { type: 'spring' })
+ *   }
+ * })
+ *
+ * // Later, swap handlers without ending the live gesture:
+ * cleanup.update({ onMove: (_e, info) => x.set(info.offset.x * 2) })
+ *
+ * // On unmount:
+ * cleanup()
+ * ```
+ */
+export declare const attachPan: (el: HTMLElement, handlers: PanHandlers, options?: AttachPanOptions) => AttachPanCleanup;

package/dist/utils/pan.js

@@ -0,0 +1,426 @@
+import { cancelFrame, frame, frameData, isPrimaryPointer } from 'motion-dom';
+/**
+ * Brand we stamp on already-wrapped handlers so passing them back through
+ * `wrapHandlers` (e.g. by a future middleware layer) doesn't double-defer
+ * — that would compound frame latency invisibly per wrap depth. Symbol
+ * scoping keeps it private to this module.
+ */
+const WRAPPED_BRAND = Symbol('svelte-motion:pan:wrapped');
+const wrapUpdate = (handler, isAlive) => {
+    if (!handler)
+        return undefined;
+    if (handler[WRAPPED_BRAND])
+        return handler;
+    const wrapped = (event, info) => {
+        frame.update(() => {
+            // `isAlive` flips false on teardown; any frame.update closure
+            // queued before teardown but not yet flushed will see this and
+            // short-circuit — that's our cancellation path for the
+            // otherwise-uncancellable anonymous closures `frame.update`
+            // accepts.
+            if (!isAlive())
+                return;
+            handler(event, info);
+        }, false, true);
+    };
+    Object.defineProperty(wrapped, WRAPPED_BRAND, { value: true });
+    return wrapped;
+};
+const wrapPostRender = (handler, isAlive) => {
+    if (!handler)
+        return undefined;
+    if (handler[WRAPPED_BRAND])
+        return handler;
+    const wrapped = (event, info) => {
+        frame.postRender(() => {
+            if (!isAlive())
+                return;
+            handler(event, info);
+        });
+    };
+    Object.defineProperty(wrapped, WRAPPED_BRAND, { value: true });
+    return wrapped;
+};
+const wrapHandlers = (handlers, isAlive) => ({
+    onSessionStart: wrapUpdate(handlers.onSessionStart, isAlive),
+    onStart: wrapUpdate(handlers.onStart, isAlive),
+    onMove: wrapUpdate(handlers.onMove, isAlive),
+    onEnd: wrapPostRender(handlers.onEnd, isAlive),
+    onSessionEnd: wrapPostRender(handlers.onSessionEnd, isAlive)
+});
+const overflowStyles = new Set(['auto', 'scroll']);
+const millisecondsToSeconds = (ms) => ms / 1000;
+const secondsToMilliseconds = (s) => s * 1000;
+const subtractPoint = (a, b) => ({
+    x: a.x - b.x,
+    y: a.y - b.y
+});
+const distance2D = (a, b) => Math.sqrt((a.x - b.x) ** 2 + (a.y - b.y) ** 2);
+/**
+ * Compute velocity (px/s) from the history of timestamped points,
+ * looking back `timeDelta` seconds for stability. Matches upstream's
+ * `getVelocity` including the hold-then-flick safeguard (skip
+ * history[0] if it's > 2× timeDelta old AND there are alternatives).
+ */
+const getVelocity = (history, timeDelta) => {
+    if (history.length < 2)
+        return { x: 0, y: 0 };
+    let i = history.length - 1;
+    let timestampedPoint = null;
+    const lastPoint = history[history.length - 1];
+    while (i >= 0) {
+        timestampedPoint = history[i];
+        if (lastPoint.timestamp - timestampedPoint.timestamp > secondsToMilliseconds(timeDelta)) {
+            break;
+        }
+        i--;
+    }
+    if (!timestampedPoint)
+        return { x: 0, y: 0 };
+    if (timestampedPoint === history[0] &&
+        history.length > 2 &&
+        lastPoint.timestamp - timestampedPoint.timestamp > secondsToMilliseconds(timeDelta) * 2) {
+        timestampedPoint = history[1];
+    }
+    const time = millisecondsToSeconds(lastPoint.timestamp - timestampedPoint.timestamp);
+    if (time === 0)
+        return { x: 0, y: 0 };
+    const v = {
+        x: (lastPoint.x - timestampedPoint.x) / time,
+        y: (lastPoint.y - timestampedPoint.y) / time
+    };
+    if (v.x === Infinity)
+        v.x = 0;
+    if (v.y === Infinity)
+        v.y = 0;
+    return v;
+};
+const getPanInfo = (point, history) => ({
+    point,
+    delta: subtractPoint(point, history[history.length - 1]),
+    offset: subtractPoint(point, history[0]),
+    velocity: getVelocity(history, 0.1)
+});
+const extractEventPoint = (event) => ({
+    x: event.pageX,
+    y: event.pageY
+});
+/**
+ * Attach a pan gesture session to `el`. Returns a cleanup function that
+ * tears down the pointerdown listener and ends any in-flight session,
+ * with a `.update(next)` method for hot-swapping handlers mid-gesture.
+ *
+ * Internally a fresh `PanSession` spawns on each pointerdown — the
+ * outer attachment just keeps the pointerdown listener alive across the
+ * element's lifetime.
+ *
+ * SSR-safe: returns a no-op cleanup if `window` is undefined. The Svelte
+ * `$effect` consumer never fires on the server anyway, but defending the
+ * boundary lets the module load cleanly in node-only test runners.
+ *
+ * Lifecycle guarantee: when the returned cleanup runs mid-gesture, the
+ * session synthesizes `onEnd` + `onSessionEnd` against the raw handlers
+ * BEFORE removing listeners (see `PanSession.dispatchTerminal`). Hosts
+ * (e.g. `_MotionContainer`'s pan `$effect`) can put their `whilePan`
+ * revert logic inside the user-supplied `onEnd` and rely on it firing
+ * exactly once per gesture — whether the user released or the host
+ * forced teardown.
+ *
+ * @param el Target element to bind `pointerdown` on. Move/up/cancel
+ *   events are listened for on the element's owning window so a fast
+ *   swipe past the element's bounds keeps the gesture alive.
+ * @param handlers Pan lifecycle handlers. Any subset of
+ *   `onSessionStart` (fires on pointerdown), `onStart` (fires the first
+ *   time the cumulative offset crosses `distanceThreshold`), `onMove`
+ *   (per-frame-throttled on every pointermove past threshold), `onEnd`
+ *   (fires on pointerup/cancel if `onStart` ever fired), `onSessionEnd`
+ *   (fires on every pointerup/cancel where a pointermove occurred).
+ * @param options Per-session config. `distanceThreshold` (default 3px)
+ *   gates the start callback; `contextWindow` overrides the owning
+ *   window (use for shadow-root / iframe scenarios).
+ * @returns A cleanup function with an attached `.update(next)` method.
+ *   Calling the cleanup ends the session + removes the pointerdown
+ *   listener. Calling `.update(next)` swaps handlers in place on the
+ *   live session without rebuilding it — the canonical Svelte pattern
+ *   for inline arrow handlers that change identity each render.
+ *
+ * @example
+ * ```ts
+ * const cleanup = attachPan(node, {
+ *   onStart: (_event, info) => console.log('start', info.offset),
+ *   onMove: (_event, info) => x.set(info.offset.x),
+ *   onEnd: (_event, info) => {
+ *     if (Math.abs(info.velocity.x) > 600) commit()
+ *     else animate(x, 0, { type: 'spring' })
+ *   }
+ * })
+ *
+ * // Later, swap handlers without ending the live gesture:
+ * cleanup.update({ onMove: (_e, info) => x.set(info.offset.x * 2) })
+ *
+ * // On unmount:
+ * cleanup()
+ * ```
+ */
+export const attachPan = (el, handlers, options = {}) => {
+    if (typeof window === 'undefined') {
+        const noop = () => { };
+        return Object.assign(noop, { update: () => { } });
+    }
+    const contextWindow = options.contextWindow ?? el.ownerDocument?.defaultView ?? window;
+    const distanceThreshold = options.distanceThreshold ?? 3;
+    let session = null;
+    let rawHandlers = handlers;
+    // Liveness flag the wrapped handler closures consult before invoking
+    // the user callback. Flips false at teardown so any frame.update /
+    // frame.postRender callbacks queued before teardown — but not yet
+    // flushed — see the flag and skip dispatch. This is our only way to
+    // cancel the anonymous closures the wrappers schedule (frame.update
+    // doesn't return a handle we can store per call).
+    let isAlive = true;
+    const aliveGuard = () => isAlive;
+    // Frame-scheduled mirror of the live handlers — onSessionStart / onStart /
+    // onMove are queued onto motion-dom's `update` step, onEnd / onSessionEnd
+    // onto `postRender`. This is the wrap upstream applies via `asyncHandler`
+    // + `frame.postRender` in PanGesture.createPanHandlers; see the
+    // wrapUpdate / wrapPostRender helpers at the top of this file for the
+    // rationale. PanSession itself stays scheduler-unaware (and synchronous,
+    // for testability) — the scheduling lives at the `attachPan` boundary.
+    let liveHandlers = wrapHandlers(handlers, aliveGuard);
+    const onPointerDown = (event) => {
+        // Match upstream: ignore non-primary pointers (multi-touch, right-click).
+        if (!isPrimaryPointer(event))
+            return;
+        // Defensively end any prior session before overwriting the reference.
+        // Without this, a second primary pointerdown that arrives before the
+        // first pointerup orphans the prior session's contextWindow listeners.
+        session?.end();
+        session = new PanSession(event, liveHandlers, {
+            distanceThreshold,
+            contextWindow,
+            element: el
+        });
+    };
+    el.addEventListener('pointerdown', onPointerDown);
+    const update = (next) => {
+        rawHandlers = next;
+        liveHandlers = wrapHandlers(next, aliveGuard);
+        session?.updateHandlers(liveHandlers);
+    };
+    const teardown = () => {
+        // Synthesize the gesture's terminal lifecycle BEFORE flipping
+        // `isAlive`, so a host that tears us down mid-pan (effect re-run,
+        // component unmount) still sees a balanced onPanEnd / onPanSessionEnd
+        // pair. Dispatched against the *raw* (unwrapped) handlers so the
+        // delivery is synchronous — the wrapped lane would otherwise queue
+        // the callbacks onto frame.postRender just for them to be cancelled
+        // by the `isAlive = false` line immediately below.
+        if (session) {
+            session.dispatchTerminal(rawHandlers);
+            session.end();
+            session = null;
+        }
+        isAlive = false;
+        el.removeEventListener('pointerdown', onPointerDown);
+    };
+    return Object.assign(teardown, { update });
+};
+class PanSession {
+    history = [];
+    startEvent = null;
+    lastMoveEvent = null;
+    lastMovePoint = null;
+    handlers = {};
+    contextWindow = window;
+    distanceThreshold = 3;
+    element = null;
+    scrollPositions = new Map();
+    /**
+     * Idempotency flag — set the first time the gesture's terminal
+     * lifecycle pair (`onEnd` + `onSessionEnd`) fires. Both
+     * `handlePointerUp` (the natural release path) and
+     * `dispatchTerminal` (the forced-teardown path called by
+     * `attachPan.teardown`) check this and bail if already dispatched.
+     * Without it, a normal pointerup followed by a host-side teardown
+     * (e.g. `$effect` cleanup, component unmount) would replay
+     * `onEnd`/`onSessionEnd` against handlers that already saw them.
+     */
+    terminalDispatched = false;
+    removeScrollListeners = null;
+    removeListeners = null;
+    constructor(event, handlers, opts) {
+        // Bail on non-primary pointers. Properties keep their declared
+        // defaults so TypeScript sees them initialized regardless of which
+        // constructor branch ran.
+        if (!isPrimaryPointer(event))
+            return;
+        this.handlers = handlers;
+        this.contextWindow = opts.contextWindow;
+        this.distanceThreshold = opts.distanceThreshold;
+        this.element = opts.element;
+        const point = extractEventPoint(event);
+        this.history = [{ ...point, timestamp: frameData.timestamp }];
+        this.handlers.onSessionStart?.(event, getPanInfo(point, this.history));
+        const moveHandler = (e) => this.handlePointerMove(e);
+        const upHandler = (e) => this.handlePointerUp(e);
+        this.contextWindow.addEventListener('pointermove', moveHandler);
+        this.contextWindow.addEventListener('pointerup', upHandler);
+        this.contextWindow.addEventListener('pointercancel', upHandler);
+        this.removeListeners = () => {
+            this.contextWindow.removeEventListener('pointermove', moveHandler);
+            this.contextWindow.removeEventListener('pointerup', upHandler);
+            this.contextWindow.removeEventListener('pointercancel', upHandler);
+        };
+        if (this.element)
+            this.startScrollTracking(this.element);
+    }
+    updateHandlers(handlers) {
+        this.handlers = handlers;
+    }
+    end() {
+        this.removeListeners?.();
+        this.removeListeners = null;
+        this.removeScrollListeners?.();
+        this.removeScrollListeners = null;
+        this.scrollPositions.clear();
+        cancelFrame(this.updatePoint);
+    }
+    /**
+     * Synthesize the gesture's terminal lifecycle pair (`onEnd` then
+     * `onSessionEnd`) against the supplied *raw* (unwrapped) handlers,
+     * using the last observed event + point as the synthetic terminal
+     * sample. Called by `attachPan.teardown` when a host kills the
+     * session mid-gesture — without this, an `$effect` re-run that
+     * tears down the attachment silently strands the consumer's state
+     * machine in an "in-progress" state (whilePan keyframes never
+     * revert, threshold-based commit decisions never run).
+     *
+     * Bypasses the frame-loop wrappers deliberately: the wrapped
+     * handlers would queue to `frame.postRender` only for the
+     * about-to-flip `isAlive` flag in attachPan to cancel them. Raw
+     * dispatch keeps the lifecycle synchronous with teardown.
+     *
+     * No-op when no pointermove ever fired — matches the
+     * `handlePointerUp` no-movement contract upstream uses.
+     */
+    dispatchTerminal(rawHandlers) {
+        if (this.terminalDispatched)
+            return;
+        if (!(this.lastMoveEvent && this.lastMovePoint))
+            return;
+        const info = getPanInfo(this.lastMovePoint, this.history);
+        if (this.startEvent)
+            rawHandlers.onEnd?.(this.lastMoveEvent, info);
+        rawHandlers.onSessionEnd?.(this.lastMoveEvent, info);
+        this.terminalDispatched = true;
+    }
+    handlePointerMove = (event) => {
+        this.lastMoveEvent = event;
+        this.lastMovePoint = extractEventPoint(event);
+        // Per-frame throttle so a 1000hz mouse doesn't drown handlers.
+        frame.update(this.updatePoint, true);
+    };
+    handlePointerUp = (event) => {
+        this.end();
+        if (this.terminalDispatched)
+            return;
+        if (!(this.lastMoveEvent && this.lastMovePoint)) {
+            // No pointermove ever fired — match upstream framer-motion
+            // (`packages/framer-motion/src/gestures/pan/PanSession.ts`
+            // ~line 320) and return WITHOUT firing onEnd / onSessionEnd.
+            // Consumers that want a "tap" signal should use the press /
+            // tap gesture instead. This prevents a spurious
+            // onPanSessionStart → onPanSessionEnd pair on every plain
+            // click of a pan-enabled element.
+            return;
+        }
+        const finalPoint = event.type === 'pointercancel' ? this.lastMovePoint : extractEventPoint(event);
+        const info = getPanInfo(finalPoint, this.history);
+        if (this.startEvent)
+            this.handlers.onEnd?.(event, info);
+        this.handlers.onSessionEnd?.(event, info);
+        // Mark idempotent so a later forced teardown via
+        // `dispatchTerminal` doesn't replay this pair.
+        this.terminalDispatched = true;
+    };
+    updatePoint = () => {
+        if (!(this.lastMoveEvent && this.lastMovePoint))
+            return;
+        const info = getPanInfo(this.lastMovePoint, this.history);
+        const panAlreadyStarted = this.startEvent !== null;
+        const pastThreshold = distance2D(info.offset, { x: 0, y: 0 }) >= this.distanceThreshold;
+        if (!panAlreadyStarted && !pastThreshold)
+            return;
+        this.history.push({ ...this.lastMovePoint, timestamp: frameData.timestamp });
+        if (!panAlreadyStarted) {
+            this.handlers.onStart?.(this.lastMoveEvent, info);
+            this.startEvent = this.lastMoveEvent;
+        }
+        this.handlers.onMove?.(this.lastMoveEvent, info);
+    };
+    /**
+     * Track scrollable ancestors so we can compensate for scroll deltas
+     * during the gesture — mirrors upstream's `startScrollTracking`.
+     * For element scrolls: adjust `history[0]` so offset stays sane
+     * (pageX/pageY unaffected by element scroll). For window scrolls:
+     * adjust `lastMovePoint` (pageX/pageY shift with window scroll).
+     */
+    startScrollTracking(element) {
+        let current = element.parentElement;
+        while (current) {
+            const style = getComputedStyle(current);
+            if (overflowStyles.has(style.overflowX) || overflowStyles.has(style.overflowY)) {
+                this.scrollPositions.set(current, {
+                    x: current.scrollLeft,
+                    y: current.scrollTop
+                });
+            }
+            current = current.parentElement;
+        }
+        this.scrollPositions.set(this.contextWindow, {
+            x: this.contextWindow.scrollX,
+            y: this.contextWindow.scrollY
+        });
+        const onElementScroll = (event) => {
+            this.handleScroll(event.target);
+        };
+        const onWindowScroll = () => {
+            this.handleScroll(this.contextWindow);
+        };
+        this.contextWindow.addEventListener('scroll', onElementScroll, { capture: true });
+        this.contextWindow.addEventListener('scroll', onWindowScroll);
+        this.removeScrollListeners = () => {
+            this.contextWindow.removeEventListener('scroll', onElementScroll, {
+                capture: true
+            });
+            this.contextWindow.removeEventListener('scroll', onWindowScroll);
+        };
+    }
+    handleScroll(target) {
+        const initial = this.scrollPositions.get(target);
+        if (!initial)
+            return;
+        const isWindow = target === this.contextWindow;
+        const current = isWindow
+            ? { x: this.contextWindow.scrollX, y: this.contextWindow.scrollY }
+            : {
+                x: target.scrollLeft,
+                y: target.scrollTop
+            };
+        const delta = { x: current.x - initial.x, y: current.y - initial.y };
+        if (delta.x === 0 && delta.y === 0)
+            return;
+        if (isWindow) {
+            if (this.lastMovePoint) {
+                this.lastMovePoint.x += delta.x;
+                this.lastMovePoint.y += delta.y;
+            }
+        }
+        else if (this.history.length > 0) {
+            this.history[0].x -= delta.x;
+            this.history[0].y -= delta.y;
+        }
+        this.scrollPositions.set(target, current);
+        frame.update(this.updatePoint, true);
+    }
+}

package/dist/utils/spring.svelte.d.ts

@@ -9,6 +9,10 @@ import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
  * `velocity`, `restDelta`, `restSpeed`) plus `skipInitialAnimation` for
  * scroll-restoration scenarios.
  *
+ * `useSpring` is a thin wrapper over {@link useFollowValue} that hard-codes
+ * `type: 'spring'`. For other transition types (tween, inertia, keyframes)
+ * use `useFollowValue` directly.
+ *
  * @see https://motion.dev/docs/react-use-spring
  */
 export type UseSpringOptions = SpringOptions & Pick<FollowValueOptions, 'skipInitialAnimation'>;
@@ -22,41 +26,36 @@ export type UseSpringOptions = SpringOptions & Pick<FollowValueOptions, 'skipIni
  * - `current` — a Svelte-5 reactive read backed by `$state`. Use in templates
  *   and `$derived` / `$effect` to track the spring value without subscribing.
  * - `subscribe` — Svelte readable store contract. Calls the run function once
- *   synchronously with the current value, then on every change. Lets the
- *   spring be used with `$spring` template syntax, `get(spring)`, and as a
- *   dependency in `useTransform`'s function form.
+ *   synchronously with the current value, then on every change.
  */
 export type SpringMotionValue<T extends number | string> = AugmentedMotionValue<T>;
 /**
  * Creates a spring-animated `MotionValue`.
  *
  * Set a target with `.set(v)` to animate to it using spring physics, or
- * `.jump(v)` to skip the animation. Pass another `MotionValue` (or, for
- * backwards compatibility, a Svelte readable store like the ones from
- * `useScroll` / `useTime`) as `source` and the spring will animate towards
- * whatever that source emits.
- *
- * Returned object is a real motion-dom `MotionValue` — composes with
- * `animate()`, `useTransform`, `useVelocity`, and motion-dom's animation
- * engine. On top, it exposes:
+ * `.jump(v)` to skip the animation. Pass another `MotionValue` (or a Svelte
+ * readable store from `useScroll` / `useTime`) as `source` and the spring
+ * will animate toward whatever that source emits.
  *
- * - `.current` — Svelte-5 reactive read for templates and `$derived` /
- *   `$effect`.
- * - `.subscribe(run)` — Svelte readable store contract so `$spring` template
- *   syntax and `useTransform(() => …, [spring])` keep working during the
- *   Tier 2 migration window.
+ * Returned object is a real motion-dom `MotionValue` augmented with a
+ * `$state`-backed `.current` getter and a Svelte readable `.subscribe` shim.
+ * Composes with `useTransform`, `useVelocity`, `animate()`, and the rest of
+ * the motion-value surface.
  *
- * Lifecycle: must be called during component initialization. Cleanup is
- * registered via `$effect`; the spring stops animating and unsubscribes from
- * its source when the surrounding component / effect tears down. Call
- * `.destroy()` to clean up early.
+ * Lifecycle: must be called during component initialization. The follow
+ * animation, source bridge (if any), and motion value teardown are bound to
+ * the surrounding `$effect` scope.
  *
  * SSR-safe: returns a static `MotionValue` with no animation on the server.
  *
- * @template T
- * @param {number|string|MotionValue<number>|MotionValue<string>|Readable<number|string>} source Initial value or a source to follow.
- * @param {UseSpringOptions} [options] Spring + follow configuration.
- * @returns {SpringMotionValue<T>} A `MotionValue` with `.current` and `.subscribe`.
+ * Implementation: thin wrapper over {@link useFollowValue} that hard-codes
+ * `type: 'spring'`. For tween / inertia / keyframes follows, call
+ * `useFollowValue` directly.
+ *
+ * @template T The value type — `number` or `string` (unit strings preserved).
+ * @param source Initial value, a `MotionValue` to follow, or a Svelte readable.
+ * @param options Spring + follow configuration.
+ * @returns A `MotionValue<T>` with `.current` and `.subscribe`.
  *
  * @example
  * ```svelte
@@ -67,7 +66,7 @@ export type SpringMotionValue<T extends number | string> = AugmentedMotionValue<
  * </script>
  *
  * <button onclick={() => x.set(100)}>Animate</button>
- * <div>{x.current}</div>
+ * <div style="transform: translateX({x.current}px)">{x.current}</div>
  * ```
  *
  * @see https://motion.dev/docs/react-use-spring

package/dist/utils/spring.svelte.js

@@ -1,54 +1,10 @@
-import { attachFollow, isMotionValue, motionValue } from 'motion-dom';
+import {} from 'motion-dom';
 import {} from 'svelte/store';
-import { augmentMotionValue, isSvelteReadable, sampleSource } from './augmentMotionValue.svelte.js';
+import {} from './augmentMotionValue.svelte.js';
+import { useFollowValue } from './followValue.svelte.js';
 export function useSpring(source, options = {}) {
-    // SSR: return a static MotionValue with no animation. Reads return the
-    // best-effort initial value; .set / .jump become no-ops to avoid drifting
-    // away from the server-rendered snapshot.
-    if (typeof window === 'undefined') {
-        const initial = sampleSource(source);
-        const ssrValue = motionValue(initial);
-        ssrValue.set = () => undefined;
-        ssrValue.jump = () => undefined;
-        return augmentMotionValue(ssrValue);
-    }
-    // Resolve initial + follow source.
-    let followSource;
-    let cleanupReadableBridge;
-    let svelteBridge;
-    if (isMotionValue(source)) {
-        followSource = source;
-    }
-    else if (isSvelteReadable(source)) {
-        // Bridge a Svelte readable into a MotionValue so attachFollow can
-        // track it. Synchronous initial sample comes from svelte/store's get().
-        const initialFromReadable = sampleSource(source);
-        svelteBridge = motionValue(initialFromReadable);
-        cleanupReadableBridge = source.subscribe((v) => {
-            // The Svelte readable contract calls the subscriber synchronously
-            // with the current value on subscribe. Skip if it equals the
-            // already-seeded bridge value so attachFollow doesn't fire a
-            // spring on the initial emit. Subsequent emits go through set()
-            // and trigger animation.
-            if (svelteBridge.get() === v)
-                return;
-            svelteBridge.set(v);
-        });
-        followSource = svelteBridge;
-    }
-    else {
-        followSource = source;
-    }
-    const initial = isMotionValue(followSource) ? followSource.get() : followSource;
-    const value = motionValue(initial);
-    const stopFollow = attachFollow(value, followSource, { type: 'spring', ...options });
-    // Side-cleanup for our augmentations. Single-shot guard lives in the
-    // augmented `value.destroy` (the only caller), so no flag here.
-    const dispose = () => {
-        stopFollow?.();
-        cleanupReadableBridge?.();
-        svelteBridge?.destroy();
-    };
-    $effect(() => () => value.destroy());
-    return augmentMotionValue(value, dispose);
+    // Cast through `unknown` because TypeScript can't narrow the multi-form
+    // `source` against `useFollowValue`'s overload set; runtime behavior is
+    // identical — `useFollowValue` dispatches on the same shapes.
+    return useFollowValue(source, { type: 'spring', ...options });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Framer Motion for Svelte 5. Declarative motion.<tag> components with AnimatePresence exit animations, gestures (hover, tap, drag, focus, in-view), variants, FLIP layout animations, shared-layout transitions, spring physics, and scroll-linked motion values. The drop-in Framer Motion alternative for Svelte and SvelteKit.",
   "keywords": [
     "svelte",
@@ -104,7 +104,7 @@
     "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.60.0",
     "@sveltejs/adapter-auto": "^7.0.1",
-    "@sveltejs/kit": "^2.60.1",
+    "@sveltejs/kit": "^2.61.1",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^7.1.2",
     "@tailwindcss/aspect-ratio": "^0.4.2",
@@ -131,7 +131,7 @@
     "prettier": "^3.8.3",
     "prettier-plugin-organize-imports": "^4.3.0",
     "prettier-plugin-sort-json": "^4.2.0",
-    "prettier-plugin-svelte": "^3.5.2",
+    "prettier-plugin-svelte": "^4.0.1",
     "prettier-plugin-tailwindcss": "^0.8.0",
     "publint": "^0.3.21",
     "runed": "0.37.1",
@@ -144,7 +144,7 @@
     "tailwindcss-animate": "^1.0.7",
     "tsx": "^4.22.3",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.4",
+    "typescript-eslint": "^8.60.0",
     "vite": "^8.0.14",
     "vite-tsconfig-paths": "^6.1.1",
     "vitest": "^4.1.7"