@humanspeak/svelte-motion 0.4.9 → 0.5.1

package/dist/index.d.ts

@@ -10,31 +10,38 @@ export type { DragAxis, DragConstraints, DragControls, DragInfo, DragTransition,
 export { useAnimate } from './utils/animate.svelte';
 export type { AnimationScope } from './utils/animate.svelte';
 export { useAnimationFrame } from './utils/animationFrame';
+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';
-export { useMotionValue } from './utils/motionValue';
-export type { MotionValue } from './utils/motionValue';
+export { useMotionTemplate } from './utils/motionTemplate.svelte';
+export type { MotionTemplateInput } from './utils/motionTemplate.svelte';
+export { useMotionValue } from './utils/motionValue.svelte';
+export type { MotionValue, RawMotionValue } from './utils/motionValue.svelte';
 export { useMotionValueEvent } from './utils/motionValueEvent';
 export { useReducedMotion } from './utils/reducedMotion.svelte';
 export type { ReducedMotionState } from './utils/reducedMotion.svelte';
 export { useReducedMotionConfig } from './utils/reducedMotionConfig.svelte';
-export { useScroll } from './utils/scroll';
+export { useScroll } from './utils/scroll.svelte';
+export type { UseScrollOptions, UseScrollReturn } from './utils/scroll.svelte';
 export { useSpring } from './utils/spring.svelte';
 export type { SpringMotionValue, UseSpringOptions } from './utils/spring.svelte';
 export { useIsPresent, usePresence } from './utils/usePresence';
 export type { UsePresenceState } from './utils/usePresence';
-export { useVelocity } from './utils/velocity';
+export { useVelocity } from './utils/velocity.svelte';
+export type { VelocitySource } from './utils/velocity.svelte';
 /**
  * @deprecated Use `styleString` instead for reactive styles with automatic unit handling.
  */
 export { stringifyStyleObject } from './utils/styleObject';
 export { styleString } from './utils/styleObject.svelte';
-export { useTime } from './utils/time';
-export { useTransform } from './utils/transform';
+export { useTime } from './utils/time.svelte';
+export { useTransform } from './utils/transform.svelte';
+export type { MultiTransformer, SingleTransformer, TransformOptions, TransformOutputMap, TransformSource } from './utils/transform.svelte';
 export { AnimatePresence, LayoutGroup, MotionConfig, PresenceChild };
 export { default as MotionA } from './html/A.svelte';
 export { default as MotionAbbr } from './html/Abbr.svelte';

package/dist/index.js

@@ -13,23 +13,24 @@ 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';
-export { useMotionValue } from './utils/motionValue';
+export { useMotionTemplate } from './utils/motionTemplate.svelte';
+export { useMotionValue } from './utils/motionValue.svelte';
 export { useMotionValueEvent } from './utils/motionValueEvent';
 export { useReducedMotion } from './utils/reducedMotion.svelte';
 export { useReducedMotionConfig } from './utils/reducedMotionConfig.svelte';
-export { useScroll } from './utils/scroll';
+export { useScroll } from './utils/scroll.svelte';
 export { useSpring } from './utils/spring.svelte';
 export { useIsPresent, usePresence } from './utils/usePresence';
-export { useVelocity } from './utils/velocity';
+export { useVelocity } from './utils/velocity.svelte';
 /**
  * @deprecated Use `styleString` instead for reactive styles with automatic unit handling.
  */
 export { stringifyStyleObject } from './utils/styleObject';
 export { styleString } from './utils/styleObject.svelte';
-export { useTime } from './utils/time';
-export { useTransform } from './utils/transform';
+export { useTime } from './utils/time.svelte';
+export { useTransform } from './utils/transform.svelte';
 export { AnimatePresence, LayoutGroup, MotionConfig, PresenceChild };
 // Named component exports — tree-shakeable alternative to the `motion` object
 export { default as MotionA } from './html/A.svelte';

package/dist/utils/attachable.js

@@ -1,3 +1,4 @@
+import { cancelMicrotask, microtask } from 'motion-dom';
 import { resolveElement } from './dom.js';
 /**
  * Builds a subscriber-refcounted DOM-attachment primitive. Both `useScroll`
@@ -27,17 +28,21 @@ import { resolveElement } from './dom.js';
  */
 export const createAttachable = (config) => {
     let cleanup;
-    let pollRaf = 0;
+    let pollScheduled = false;
     let subscriberCount = 0;
     // When stop() runs synchronously inside onAttach, cleanup hasn't been
     // assigned yet. Defer the teardown so the just-returned disposer still
     // gets invoked.
     let attaching = false;
     let stopRequestedDuringAttach = false;
+    const pollTick = () => {
+        pollScheduled = false;
+        tryAttach();
+    };
     const cancelPoll = () => {
-        if (pollRaf) {
-            cancelAnimationFrame(pollRaf);
-            pollRaf = 0;
+        if (pollScheduled) {
+            cancelMicrotask(pollTick);
+            pollScheduled = false;
         }
     };
     const stop = () => {
@@ -65,11 +70,11 @@ export const createAttachable = (config) => {
             els[key] = el;
         }
         if (needsPoll) {
-            if (!pollRaf) {
-                pollRaf = requestAnimationFrame(() => {
-                    pollRaf = 0;
-                    tryAttach();
-                });
+            // Microtask schedule (matches useScroll's pattern) — one frame
+            // faster than rAF for refs that hydrate the same tick.
+            if (!pollScheduled) {
+                pollScheduled = true;
+                microtask.read(pollTick);
             }
             return;
         }

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

@@ -0,0 +1,156 @@
+import { type MotionValue } from 'motion-dom';
+import { type Readable } from 'svelte/store';
+/**
+ * A motion-dom `MotionValue<T>` augmented with the two affordances every
+ * Tier-2 hook in this library exposes for Svelte 5 consumers:
+ *
+ * - `current` — a `$state`-backed reactive getter. Reads inside templates,
+ *   `$derived`, and `$effect` track changes automatically without going
+ *   through `.subscribe()`.
+ * - `subscribe(run)` — Svelte readable store contract. Calls `run(value)`
+ *   once synchronously on subscribe, then on every change. Lets the same
+ *   value drive `$value` template syntax, `svelte/store`'s `get()`, and
+ *   anything else that expects a readable.
+ *
+ * Every Wave 3 hook (`useMotionValue`, `useTransform`, `useScroll`,
+ * `useTime`, `useVelocity`, `useMotionTemplate`) and `useSpring` returns a
+ * value of this shape. The point is to keep one shared surface across all
+ * motion-value-producing hooks instead of repeating the wiring in each.
+ */
+export type AugmentedMotionValue<T> = Omit<MotionValue<T>, 'current'> & {
+    /** Reactive read in Svelte 5 templates / `$derived` / `$effect`. */
+    readonly current: T;
+    /** Svelte readable store compatibility. */
+    subscribe: (run: (value: T) => void) => () => void;
+};
+/**
+ * Detects a Svelte readable store, excluding motion-dom `MotionValue`
+ * instances (which also expose `subscribe`-shaped APIs in some versions).
+ * Used by hook factories that accept either a `MotionValue` or a readable
+ * store as a source.
+ *
+ * @template T The value type the readable emits.
+ * @param value Any value to test.
+ * @returns Whether the value is a Svelte readable (and not a `MotionValue`).
+ *
+ * @example
+ * ```ts
+ * import { writable } from 'svelte/store'
+ * import { motionValue } from 'motion-dom'
+ *
+ * isSvelteReadable(writable(0))  // true
+ * isSvelteReadable(motionValue(0))  // false (a MotionValue, not a readable)
+ * isSvelteReadable({ subscribe: 'nope' })  // false (subscribe isn't callable)
+ * ```
+ */
+export declare const isSvelteReadable: <T = unknown>(value: unknown) => value is Readable<T>;
+/**
+ * Synchronously samples a source: returns `T` directly, calls `.get()` on
+ * a `MotionValue`, or `svelte/store`'s `get()` on a readable. Used by hook
+ * factories to seed an initial value before any subscription is established.
+ *
+ * @template T The value type.
+ * @param source A plain value, a `MotionValue`, or a Svelte readable.
+ * @returns The current value of the source.
+ *
+ * @example
+ * ```ts
+ * sampleSource(42)               // 42
+ * sampleSource(motionValue(7))   // 7
+ * sampleSource(writable(11))     // 11
+ * ```
+ */
+export declare const sampleSource: <T>(source: T | MotionValue<T> | Readable<T>) => T;
+/**
+ * Layer Svelte 5 affordances onto a motion-dom `MotionValue`:
+ *
+ * 1. A `$state`-tracked `.current` accessor. motion-dom writes to its own
+ *    `current` field on every frame via an internal setter; we redirect that
+ *    setter through `$state` so templates and `$derived` / `$effect` re-run
+ *    automatically. Same-value writes are skipped (motion-dom can call the
+ *    setter at rest, and `$state` would itself dedupe, but the explicit
+ *    check avoids the extra accessor work).
+ *
+ * 2. A `.subscribe(run)` shim implementing the Svelte readable store
+ *    contract: synchronous initial emit, then re-emit on every change.
+ *    Forwarded to motion-dom's `.on('change', …)` event bus.
+ *
+ * 3. `.destroy()` is wrapped so a caller-supplied `dispose` runs once before
+ *    motion-dom's own teardown (and only once, guarded against re-entrant
+ *    or duplicate destroy calls).
+ *
+ * The returned reference is the same `MotionValue` passed in, only retyped —
+ * so identity checks (`isMotionValue`, `===`) still work and motion-dom's
+ * own machinery (animation, follow, composition) is untouched.
+ *
+ * **Call once per MotionValue.** This function mutates the value (rewrites
+ * `current`, `subscribe`, `destroy`). Calling it twice would re-define the
+ * accessors and the first call's `dispose` would be discarded.
+ *
+ * @template T The value type — typically `number` or `string`.
+ * @param value The motion-dom `MotionValue` to augment.
+ * @param dispose Optional cleanup that runs once when `.destroy()` is first called (before motion-dom's internal teardown). Defaults to a no-op.
+ * @returns The same `MotionValue` typed as {@link AugmentedMotionValue}.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { motionValue } from 'motion-dom'
+ *   import { augmentMotionValue } from './augmentMotionValue.svelte.js'
+ *
+ *   const mv = motionValue(0)
+ *   const aug = augmentMotionValue(mv, () => console.log('disposed'))
+ *
+ *   $effect(() => () => aug.destroy())
+ * </script>
+ *
+ * <div style="transform: translateX({aug.current}px)">{aug.current}</div>
+ * ```
+ */
+export declare const augmentMotionValue: <T>(value: MotionValue<T>, dispose?: VoidFunction) => AugmentedMotionValue<T>;
+/**
+ * Bridges a Svelte `Readable<T>` into a motion-dom `MotionValue<T>` that
+ * mirrors the readable's emissions, so motion-dom primitives (`mapValue`,
+ * `transformValue`, `attachFollow`, `getVelocity`, etc.) that only accept
+ * `MotionValue` can track readable-shaped sources.
+ *
+ * The bridge:
+ * 1. Seeds via `get(source)` so the initial value is correct synchronously.
+ * 2. Subscribes to the readable, skipping the *synchronous initial emit*
+ *    (Svelte readables always fire one on subscribe, but the seed already
+ *    has it — without the skip the bridge would double-write on attach).
+ * 3. Optionally coerces each emit through `coerce` — useful for unit-string
+ *    sources (e.g. `"100px"` → `100`).
+ *
+ * Returns the bridge value and a `dispose` that tears down the subscription
+ * and destroys the bridge MV. Callers register `dispose` with their lifecycle
+ * ($effect cleanup or the augmented `destroy`'s `dispose` slot).
+ *
+ * @template TIn The readable's emit type (often `number | string`).
+ * @template TOut The bridge MotionValue's value type (often `number`).
+ * @param source A Svelte readable store.
+ * @param coerce Optional transform applied to each emit (and the initial seed). Identity by default.
+ * @returns A `MotionValue<TOut>` mirroring the readable + a dispose function.
+ *
+ * @example
+ * ```ts
+ * import { writable } from 'svelte/store'
+ *
+ * // Identity bridge — readable<number> → motionValue<number>
+ * const w = writable(0)
+ * const { value: mv, dispose } = bridgeReadableToMotionValue(w)
+ * w.set(50); mv.get() === 50
+ *
+ * // Coerce bridge — readable<string> → motionValue<number>
+ * const w2 = writable('100px')
+ * const bridge = bridgeReadableToMotionValue<string, number>(w2, parseFloat)
+ * bridge.value.get() === 100
+ *
+ * // Always pair with dispose() in your $effect cleanup.
+ * $effect(() => () => dispose())
+ * ```
+ */
+export declare const bridgeReadableToMotionValue: <TIn, TOut = TIn>(source: Readable<TIn>, coerce?: (v: TIn) => TOut) => {
+    value: MotionValue<TOut>;
+    dispose: VoidFunction;
+};

package/dist/utils/augmentMotionValue.svelte.js

@@ -0,0 +1,193 @@
+import { isMotionValue, motionValue } from 'motion-dom';
+import { get } from 'svelte/store';
+/**
+ * Detects a Svelte readable store, excluding motion-dom `MotionValue`
+ * instances (which also expose `subscribe`-shaped APIs in some versions).
+ * Used by hook factories that accept either a `MotionValue` or a readable
+ * store as a source.
+ *
+ * @template T The value type the readable emits.
+ * @param value Any value to test.
+ * @returns Whether the value is a Svelte readable (and not a `MotionValue`).
+ *
+ * @example
+ * ```ts
+ * import { writable } from 'svelte/store'
+ * import { motionValue } from 'motion-dom'
+ *
+ * isSvelteReadable(writable(0))  // true
+ * isSvelteReadable(motionValue(0))  // false (a MotionValue, not a readable)
+ * isSvelteReadable({ subscribe: 'nope' })  // false (subscribe isn't callable)
+ * ```
+ */
+export const isSvelteReadable = (value) => {
+    return (!!value &&
+        typeof value === 'object' &&
+        typeof value.subscribe === 'function' &&
+        !isMotionValue(value));
+};
+/**
+ * Synchronously samples a source: returns `T` directly, calls `.get()` on
+ * a `MotionValue`, or `svelte/store`'s `get()` on a readable. Used by hook
+ * factories to seed an initial value before any subscription is established.
+ *
+ * @template T The value type.
+ * @param source A plain value, a `MotionValue`, or a Svelte readable.
+ * @returns The current value of the source.
+ *
+ * @example
+ * ```ts
+ * sampleSource(42)               // 42
+ * sampleSource(motionValue(7))   // 7
+ * sampleSource(writable(11))     // 11
+ * ```
+ */
+export const sampleSource = (source) => {
+    if (isMotionValue(source))
+        return source.get();
+    if (isSvelteReadable(source))
+        return get(source);
+    return source;
+};
+/**
+ * Layer Svelte 5 affordances onto a motion-dom `MotionValue`:
+ *
+ * 1. A `$state`-tracked `.current` accessor. motion-dom writes to its own
+ *    `current` field on every frame via an internal setter; we redirect that
+ *    setter through `$state` so templates and `$derived` / `$effect` re-run
+ *    automatically. Same-value writes are skipped (motion-dom can call the
+ *    setter at rest, and `$state` would itself dedupe, but the explicit
+ *    check avoids the extra accessor work).
+ *
+ * 2. A `.subscribe(run)` shim implementing the Svelte readable store
+ *    contract: synchronous initial emit, then re-emit on every change.
+ *    Forwarded to motion-dom's `.on('change', …)` event bus.
+ *
+ * 3. `.destroy()` is wrapped so a caller-supplied `dispose` runs once before
+ *    motion-dom's own teardown (and only once, guarded against re-entrant
+ *    or duplicate destroy calls).
+ *
+ * The returned reference is the same `MotionValue` passed in, only retyped —
+ * so identity checks (`isMotionValue`, `===`) still work and motion-dom's
+ * own machinery (animation, follow, composition) is untouched.
+ *
+ * **Call once per MotionValue.** This function mutates the value (rewrites
+ * `current`, `subscribe`, `destroy`). Calling it twice would re-define the
+ * accessors and the first call's `dispose` would be discarded.
+ *
+ * @template T The value type — typically `number` or `string`.
+ * @param value The motion-dom `MotionValue` to augment.
+ * @param dispose Optional cleanup that runs once when `.destroy()` is first called (before motion-dom's internal teardown). Defaults to a no-op.
+ * @returns The same `MotionValue` typed as {@link AugmentedMotionValue}.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { motionValue } from 'motion-dom'
+ *   import { augmentMotionValue } from './augmentMotionValue.svelte.js'
+ *
+ *   const mv = motionValue(0)
+ *   const aug = augmentMotionValue(mv, () => console.log('disposed'))
+ *
+ *   $effect(() => () => aug.destroy())
+ * </script>
+ *
+ * <div style="transform: translateX({aug.current}px)">{aug.current}</div>
+ * ```
+ */
+export const augmentMotionValue = (value, dispose = () => undefined) => {
+    // motion-dom's `.get()` returns `NonNullable<V>`, which would otherwise
+    // narrow `$state` to that and reject nullable-T setter writes. Cast to T
+    // so the state slot matches the public augmented signature; motion-dom's
+    // own contract guarantees it never sets a null/undefined frame value.
+    let current = $state(value.get());
+    Object.defineProperty(value, 'current', {
+        get: () => current,
+        set: (v) => {
+            if (v !== current)
+                current = v;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    const originalDestroy = value.destroy.bind(value);
+    let destroyed = false;
+    value.destroy = () => {
+        if (destroyed)
+            return;
+        destroyed = true;
+        dispose();
+        originalDestroy();
+    };
+    const subscribe = (run) => {
+        run(value.get());
+        return value.on('change', run);
+    };
+    Object.defineProperty(value, 'subscribe', {
+        value: subscribe,
+        writable: false,
+        enumerable: false,
+        configurable: true
+    });
+    return value;
+};
+/**
+ * Bridges a Svelte `Readable<T>` into a motion-dom `MotionValue<T>` that
+ * mirrors the readable's emissions, so motion-dom primitives (`mapValue`,
+ * `transformValue`, `attachFollow`, `getVelocity`, etc.) that only accept
+ * `MotionValue` can track readable-shaped sources.
+ *
+ * The bridge:
+ * 1. Seeds via `get(source)` so the initial value is correct synchronously.
+ * 2. Subscribes to the readable, skipping the *synchronous initial emit*
+ *    (Svelte readables always fire one on subscribe, but the seed already
+ *    has it — without the skip the bridge would double-write on attach).
+ * 3. Optionally coerces each emit through `coerce` — useful for unit-string
+ *    sources (e.g. `"100px"` → `100`).
+ *
+ * Returns the bridge value and a `dispose` that tears down the subscription
+ * and destroys the bridge MV. Callers register `dispose` with their lifecycle
+ * ($effect cleanup or the augmented `destroy`'s `dispose` slot).
+ *
+ * @template TIn The readable's emit type (often `number | string`).
+ * @template TOut The bridge MotionValue's value type (often `number`).
+ * @param source A Svelte readable store.
+ * @param coerce Optional transform applied to each emit (and the initial seed). Identity by default.
+ * @returns A `MotionValue<TOut>` mirroring the readable + a dispose function.
+ *
+ * @example
+ * ```ts
+ * import { writable } from 'svelte/store'
+ *
+ * // Identity bridge — readable<number> → motionValue<number>
+ * const w = writable(0)
+ * const { value: mv, dispose } = bridgeReadableToMotionValue(w)
+ * w.set(50); mv.get() === 50
+ *
+ * // Coerce bridge — readable<string> → motionValue<number>
+ * const w2 = writable('100px')
+ * const bridge = bridgeReadableToMotionValue<string, number>(w2, parseFloat)
+ * bridge.value.get() === 100
+ *
+ * // Always pair with dispose() in your $effect cleanup.
+ * $effect(() => () => dispose())
+ * ```
+ */
+export const bridgeReadableToMotionValue = (source, coerce = (v) => v) => {
+    const bridge = motionValue(coerce(get(source)));
+    let seenInitial = false;
+    const unsub = source.subscribe((v) => {
+        if (!seenInitial) {
+            seenInitial = true;
+            return;
+        }
+        bridge.set(coerce(v));
+    });
+    return {
+        value: bridge,
+        dispose: () => {
+            unsub();
+            bridge.destroy();
+        }
+    };
+};

package/dist/utils/dom.d.ts

@@ -41,3 +41,16 @@ export type ElementOrGetter = HTMLElement | (() => HTMLElement | null | undefine
  * ```
  */
 export declare const resolveElement: (ref?: ElementOrGetter) => HTMLElement | undefined;
+/**
+ * Tests whether an `ElementOrGetter` is currently unresolved — defined as a
+ * getter that returns falsy. Direct element refs are never "pending" (they
+ * were already resolved at call time) and absent refs are not "pending"
+ * either (they're just absent).
+ *
+ * Lets microtask-defer / rAF-defer loops wait for refs to hydrate after
+ * `bind:this` settles on mount.
+ *
+ * @param ref Element or getter to check.
+ * @returns `true` only when `ref` is a getter and the getter currently returns falsy.
+ */
+export declare const isRefPending: (ref?: ElementOrGetter) => boolean;

package/dist/utils/dom.js

@@ -39,3 +39,22 @@ export const resolveElement = (ref) => {
     const value = typeof ref === 'function' ? ref() : ref;
     return value ?? undefined;
 };
+/**
+ * Tests whether an `ElementOrGetter` is currently unresolved — defined as a
+ * getter that returns falsy. Direct element refs are never "pending" (they
+ * were already resolved at call time) and absent refs are not "pending"
+ * either (they're just absent).
+ *
+ * Lets microtask-defer / rAF-defer loops wait for refs to hydrate after
+ * `bind:this` settles on mount.
+ *
+ * @param ref Element or getter to check.
+ * @returns `true` only when `ref` is a getter and the getter currently returns falsy.
+ */
+export const isRefPending = (ref) => {
+    if (!ref)
+        return false;
+    if (typeof ref !== 'function')
+        return false;
+    return !ref();
+};

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);
+}