@humanspeak/svelte-motion 0.4.9 → 0.5.0

package/dist/index.d.ts

@@ -10,31 +10,36 @@ 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 { 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

@@ -14,22 +14,22 @@ export { useAnimationFrame } from './utils/animationFrame';
 export { useCycle } from './utils/cycle.svelte';
 export { createDragControls } from './utils/dragControls';
 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/motionTemplate.svelte.d.ts

@@ -0,0 +1,53 @@
+import { type Readable } from 'svelte/store';
+import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
+/**
+ * Input to {@link useMotionTemplate}'s interpolation slots: a motion-dom
+ * `MotionValue`, a Svelte readable, or a plain `number` / `string` literal.
+ * Mirrors framer-motion's `useMotionTemplate` signature.
+ */
+export type MotionTemplateInput = AugmentedMotionValue<number | string> | Readable<number | string> | number | string;
+/**
+ * Tagged template literal that builds an augmented `MotionValue<string>`
+ * from interpolated motion values, Svelte readables, and plain literals.
+ *
+ * Mirrors framer-motion 1:1: returns a real motion-dom `MotionValue<string>`
+ * (via `transformValue`) that auto-tracks every `MotionValue.get()` called
+ * during template composition. Whenever any tracked input emits, the
+ * composer reruns and writes the new string into the result value.
+ *
+ * Svelte-readable slots are sampled via `svelte/store`'s `get()` inside the
+ * composer so they re-emit when adjacent motion values trigger a recompute.
+ * Plain `number` / `string` slots are stringified inline.
+ *
+ * The result is augmented with a `$state`-backed `.current` getter and a
+ * Svelte readable `.subscribe` shim so it composes with the rest of the
+ * Tier 2 surface and reads reactively in Svelte 5 scopes.
+ *
+ * Lifecycle: must be called during component initialization. motion-dom
+ * cleans up the change-subscriptions when the result `MotionValue` is
+ * destroyed; we wire that destroy to the surrounding `$effect`.
+ *
+ * SSR-safe: motion-dom's `transformValue` works without DOM access (no
+ * timers, no listeners). On the server the result is a static augmented
+ * motion value with no `$effect` registered.
+ *
+ * @param strings Static template string parts (supplied by the tagged-template syntax).
+ * @param values Interpolated motion values, Svelte readables, or literals.
+ * @returns An `AugmentedMotionValue<string>` with the composed template.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useSpring, useTransform, useMotionTemplate } from '@humanspeak/svelte-motion'
+ *
+ *   const x = useSpring(0)
+ *   const blur = useTransform(x, [-100, 0, 100], [10, 0, 10])
+ *   const filter = useMotionTemplate`blur(${blur}px)`
+ * </script>
+ *
+ * <div style="filter: {filter.current}">Animated blur</div>
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-motion-template
+ */
+export declare const useMotionTemplate: (strings: TemplateStringsArray, ...values: MotionTemplateInput[]) => AugmentedMotionValue<string>;

package/dist/utils/motionTemplate.svelte.js

@@ -0,0 +1,78 @@
+import { isMotionValue, transformValue } from 'motion-dom';
+import {} from 'svelte/store';
+import { augmentMotionValue, sampleSource } from './augmentMotionValue.svelte.js';
+/**
+ * Tagged template literal that builds an augmented `MotionValue<string>`
+ * from interpolated motion values, Svelte readables, and plain literals.
+ *
+ * Mirrors framer-motion 1:1: returns a real motion-dom `MotionValue<string>`
+ * (via `transformValue`) that auto-tracks every `MotionValue.get()` called
+ * during template composition. Whenever any tracked input emits, the
+ * composer reruns and writes the new string into the result value.
+ *
+ * Svelte-readable slots are sampled via `svelte/store`'s `get()` inside the
+ * composer so they re-emit when adjacent motion values trigger a recompute.
+ * Plain `number` / `string` slots are stringified inline.
+ *
+ * The result is augmented with a `$state`-backed `.current` getter and a
+ * Svelte readable `.subscribe` shim so it composes with the rest of the
+ * Tier 2 surface and reads reactively in Svelte 5 scopes.
+ *
+ * Lifecycle: must be called during component initialization. motion-dom
+ * cleans up the change-subscriptions when the result `MotionValue` is
+ * destroyed; we wire that destroy to the surrounding `$effect`.
+ *
+ * SSR-safe: motion-dom's `transformValue` works without DOM access (no
+ * timers, no listeners). On the server the result is a static augmented
+ * motion value with no `$effect` registered.
+ *
+ * @param strings Static template string parts (supplied by the tagged-template syntax).
+ * @param values Interpolated motion values, Svelte readables, or literals.
+ * @returns An `AugmentedMotionValue<string>` with the composed template.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useSpring, useTransform, useMotionTemplate } from '@humanspeak/svelte-motion'
+ *
+ *   const x = useSpring(0)
+ *   const blur = useTransform(x, [-100, 0, 100], [10, 0, 10])
+ *   const filter = useMotionTemplate`blur(${blur}px)`
+ * </script>
+ *
+ * <div style="filter: {filter.current}">Animated blur</div>
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-motion-template
+ */
+export const useMotionTemplate = (strings, ...values) => {
+    const numFragments = strings.length;
+    const buildValue = () => {
+        let output = '';
+        for (let i = 0; i < numFragments; i++) {
+            output += strings[i] ?? '';
+            if (i >= values.length)
+                continue;
+            const value = values[i];
+            // motion-dom's collectMotionValues session inside transformValue
+            // auto-discovers MotionValue deps via `.get()`. Readables don't
+            // participate — they're sampled inline via get(); they only
+            // re-emit if some adjacent motion value triggers a recompute.
+            if (isMotionValue(value)) {
+                output += String(value.get());
+            }
+            else if (value && typeof value === 'object' && 'subscribe' in value) {
+                output += String(sampleSource(value));
+            }
+            else {
+                output += String(value);
+            }
+        }
+        return output;
+    };
+    const result = transformValue(buildValue);
+    if (typeof window !== 'undefined') {
+        $effect(() => () => result.destroy());
+    }
+    return augmentMotionValue(result);
+};