@humanspeak/svelte-motion 0.4.9 → 0.5.0

package/dist/utils/time.svelte.js

@@ -0,0 +1,128 @@
+import { cancelFrame, frame, motionValue } from 'motion-dom';
+import { SvelteMap } from 'svelte/reactivity';
+import { augmentMotionValue } from './augmentMotionValue.svelte.js';
+// `SvelteMap` (not plain Map) per `eslint/svelte/prefer-svelte-reactivity`
+// inside `.svelte.ts` files. The contents aren't read in reactive scopes —
+// this is a plain keyed cache — but the linter rule applies uniformly.
+const sharedTimelines = new SvelteMap();
+// Clear shared timelines on HMR dispose to avoid stale entries across hot
+// reloads.
+const hot = import.meta.hot;
+if (hot) {
+    hot.dispose(() => {
+        for (const t of sharedTimelines.values()) {
+            t.cancel();
+            t.base.destroy();
+        }
+        sharedTimelines.clear();
+    });
+}
+/**
+ * Starts a keep-alive frame-loop callback that writes elapsed-milliseconds
+ * into a fresh `MotionValue<number>`. Returns the value and a cancel
+ * function that stops the loop. Caller owns the value's destroy lifecycle.
+ *
+ * Uses motion-dom's `frame.update(cb, true)` — `true` is the `keepAlive`
+ * flag, telling the frame loop to re-schedule the callback every frame
+ * automatically. Matches React framer-motion's `useAnimationFrame`.
+ */
+const startTimeBase = () => {
+    const base = motionValue(0);
+    let start = 0;
+    const tick = ({ timestamp }) => {
+        if (!start)
+            start = timestamp;
+        base.set(timestamp - start);
+    };
+    frame.update(tick, true);
+    return {
+        base,
+        cancel: () => cancelFrame(tick)
+    };
+};
+/**
+ * Returns an augmented `MotionValue<number>` that ticks once per render
+ * frame with the milliseconds elapsed since the value was created.
+ *
+ * Mirrors React framer-motion's `useTime` 1:1: a `MotionValue<number>`
+ * driven by motion-dom's `frame.update(tick, true)` keep-alive callback.
+ * The frame loop dedupes per-frame work across all motion-dom consumers,
+ * so multiple `useTime()` calls share the same render schedule.
+ *
+ * Two modes:
+ *
+ * - **Unique timeline** — `useTime()` starts its own keep-alive callback.
+ *   The motion value and the callback are torn down when the surrounding
+ *   `$effect` scope unmounts.
+ * - **Shared timeline** — `useTime(id)` callers passing the same `id` all
+ *   observe a single shared frame-loop callback. Each call still returns
+ *   an independent motion value (so destroying one consumer's value
+ *   doesn't ripple to others) but the values stay in lockstep. The
+ *   shared callback cancels the moment the last consumer unmounts; the
+ *   next `useTime(id)` call restarts it.
+ *
+ * The result is augmented with a `$state`-backed `.current` getter and a
+ * `.subscribe` shim — it composes with `useTransform`, `useSpring`, and
+ * the rest of the Tier 2 surface.
+ *
+ * Lifecycle: must be called during component initialization. SSR-safe:
+ * returns a static `motionValue(0)` with no frame loop on the server.
+ *
+ * @param id Optional timeline identifier for sharing across components.
+ * @returns A `MotionValue<number>` with `.current` and `.subscribe`.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useTime, useTransform } from '@humanspeak/svelte-motion'
+ *
+ *   const time = useTime()
+ *   const rotate = useTransform(time, [0, 4000], [0, 360], { clamp: false })
+ * </script>
+ *
+ * <div style="transform: rotate({rotate.current}deg)">↻</div>
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-time
+ */
+export const useTime = (id) => {
+    // SSR: return a static motion value with no frame loop. Matches
+    // useSpring / useScroll's SSR branch — no $effect is registered.
+    if (typeof window === 'undefined') {
+        return augmentMotionValue(motionValue(0));
+    }
+    // Unique timeline: own callback, own MV, own lifecycle.
+    if (!id) {
+        const { base, cancel } = startTimeBase();
+        $effect(() => () => {
+            cancel();
+            base.destroy();
+        });
+        return augmentMotionValue(base);
+    }
+    // Shared timeline: one frame callback per `id`, mirrored into per-
+    // consumer MVs.
+    let timeline = sharedTimelines.get(id);
+    if (!timeline) {
+        const { base, cancel } = startTimeBase();
+        timeline = { base, refcount: 0, cancel };
+        sharedTimelines.set(id, timeline);
+    }
+    timeline.refcount++;
+    const consumerMv = motionValue(timeline.base.get());
+    const unsubBase = timeline.base.on('change', (t) => consumerMv.set(t));
+    $effect(() => () => {
+        unsubBase();
+        consumerMv.destroy();
+        const t = sharedTimelines.get(id);
+        if (!t)
+            return;
+        t.refcount--;
+        if (t.refcount > 0)
+            return;
+        t.cancel();
+        t.base.destroy();
+        sharedTimelines.delete(id);
+    });
+    return augmentMotionValue(consumerMv);
+};

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

@@ -0,0 +1,170 @@
+import { type MotionValue, type TransformOptions } from 'motion-dom';
+import { type Readable } from 'svelte/store';
+import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
+export type TransformValues = Partial<{
+    x: number;
+    y: number;
+    scale: number;
+    scaleX: number;
+    scaleY: number;
+    rotate: number;
+}>;
+/**
+ * Build a CSS transform string from numeric values (no matrices).
+ *
+ * @param values Partial map of translate/scale/rotate values.
+ * @returns A space-separated CSS `transform` string, or `""` when all values are defaults.
+ *
+ * @example
+ * ```ts
+ * buildTransform({ x: 10, y: 20, scale: 1.5 })
+ * // => "translate(10px, 20px) scale(1.5)"
+ *
+ * buildTransform({ x: 0, y: 0, rotate: 0 }) // all defaults
+ * // => ""
+ * ```
+ */
+export declare const buildTransform: (values: TransformValues) => string;
+/**
+ * Lightweight safety check for transform magnitudes and NaN values.
+ *
+ * @param values Transform values to validate.
+ * @param opts Optional configuration; `maxScale` caps allowable absolute scale (default 8).
+ * @returns `true` if all scale values are finite and within bounds.
+ *
+ * @example
+ * ```ts
+ * isSafeTransform({ scale: 2 })                  // true
+ * isSafeTransform({ scale: 100 })                // false (exceeds default maxScale=8)
+ * isSafeTransform({ scale: 100 }, { maxScale: 200 })  // true
+ * isSafeTransform({ scale: NaN })                // false
+ * ```
+ */
+export declare const isSafeTransform: (values: TransformValues, opts?: {
+    maxScale?: number;
+}) => boolean;
+/**
+ * Extract the uniform scale factor from a CSS `matrix()` string.
+ *
+ * @param matrix A CSS `matrix(...)` value, `"none"`, `null`, or `undefined`.
+ * @returns The `a` component of the matrix (uniform scale), or `null` if unparseable.
+ *
+ * @example
+ * ```ts
+ * parseMatrixScale('matrix(1.5, 0, 0, 1.5, 0, 0)')  // 1.5
+ * parseMatrixScale('none')                          // null
+ * parseMatrixScale(null)                            // null
+ * ```
+ */
+export declare const parseMatrixScale: (matrix: string | null | undefined) => number | null;
+export type { TransformOptions };
+/**
+ * Any motion-value shape this library accepts as a transform input: the raw
+ * motion-dom `MotionValue<T>` and our augmented `AugmentedMotionValue<T>` are
+ * both runtime-identical (the augmentation is a Svelte 5 retype, not a
+ * subclass), but TypeScript's private-field nominal typing means the two
+ * aren't structurally assignable in public signatures. This alias accepts
+ * both so call sites compile cleanly.
+ */
+export type AnyMotionValue<T> = MotionValue<T> | AugmentedMotionValue<T>;
+/**
+ * A source for {@link useTransform}'s mapping form: any motion value or a
+ * Svelte readable store. Svelte readables are bridged into a `MotionValue`
+ * internally so motion-dom's `mapValue` / `transformValue` can track them.
+ */
+export type TransformSource<T> = AnyMotionValue<T> | Readable<T>;
+/**
+ * Single-input transformer signature: `(latest) => output`.
+ */
+export type SingleTransformer<I, O> = (input: I) => O;
+/**
+ * Multi-input transformer signature: `([latestA, latestB, ...]) => output`.
+ */
+export type MultiTransformer<I, O> = (inputs: I[]) => O;
+/**
+ * Output map for the multi-output mapping form: `{ key: [stop, …] }`. The
+ * keys are stable per call and each entry produces its own `MotionValue`.
+ */
+export type TransformOutputMap<O> = {
+    [key: string]: O[];
+};
+/**
+ * Creates an augmented `MotionValue<O>` derived from one or more `MotionValue`s
+ * (or Svelte readables), composed via a range mapping or a compute function.
+ *
+ * Mirrors framer-motion's `useTransform` 1:1 with five forms:
+ *
+ * - **Mapping form** — `useTransform(source, input, output, options?)` maps a
+ *   numeric source's value across `input → output` stops with clamp, easing,
+ *   and a pluggable mixer for non-numeric outputs. Delegates to motion-dom's
+ *   `mapValue` (which is itself `transformValue` over the curried mapper).
+ * - **Multi-output mapping form** — `useTransform(source, input, outputMap, options?)`
+ *   produces an object of motion values, one per key in `outputMap`. Each
+ *   value is the same mapping form applied to that key's output stops.
+ * - **Single-transformer form** — `useTransform(mv, (latest) => O)` recomputes
+ *   on every change of `mv`. Auto-tracks via `transformValue`.
+ * - **Multi-transformer form** — `useTransform([mv1, mv2, …], ([latest, …]) => O)`
+ *   recomputes on every change of any input. Auto-tracks via `transformValue`.
+ * - **Compute form** — `useTransform(() => compute)` recomputes whenever any
+ *   `MotionValue` referenced inside `compute` (via `.get()` or `.current`)
+ *   changes. Auto-tracks via `transformValue` — no explicit deps array; the
+ *   `collectMotionValues` session inside `transformValue` discovers them.
+ *
+ * Returns an {@link AugmentedMotionValue<O>} — a real motion-dom `MotionValue`
+ * (composes with `useSpring`, `useVelocity`, `animate()`, etc.) plus a
+ * `$state`-backed `.current` getter and a Svelte readable `.subscribe` shim.
+ *
+ * Lifecycle: must be called during component initialization. Source
+ * subscriptions, the underlying motion value, and any Svelte-readable bridges
+ * are torn down when the surrounding `$effect` scope unmounts.
+ *
+ * @template O Output value type.
+ * @param sourceOrCompute A motion value / readable (mapping forms), a single
+ *   `MotionValue` (single-transformer form), an array of `MotionValue`s
+ *   (multi-transformer form), or a compute function (compute form).
+ * @param inputOrTransformer Input stops `number[]` (mapping forms) or a
+ *   transformer function (`(latest) => O` / `(latest[]) => O`).
+ * @param outputOrOutputMap Output stops `O[]` (single-output mapping) or an
+ *   output map `{ [key]: O[] }` (multi-output mapping).
+ * @param options Optional `TransformOptions` — `clamp`, `ease`, `mixer`.
+ * @returns An `AugmentedMotionValue<O>` for single-output forms, or an object
+ *   of motion values keyed by `outputMap` for the multi-output form.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useMotionValue, useTransform } from '@humanspeak/svelte-motion'
+ *
+ *   const x = useMotionValue(0)
+ *
+ *   // Mapping form
+ *   const opacity = useTransform(x, [0, 100], [0, 1])
+ *
+ *   // Single-MV transformer
+ *   const doubled = useTransform(x, (latest) => latest * 2)
+ *
+ *   // Compute form — auto-tracks via collectMotionValues
+ *   const y = useMotionValue(0)
+ *   const sum = useTransform(() => x.get() + y.get())
+ *
+ *   // Multi-output mapping
+ *   const { rotate, scale } = useTransform(x, [0, 100], {
+ *     rotate: [0, 360],
+ *     scale: [1, 2]
+ *   })
+ * </script>
+ *
+ * <div style="opacity: {opacity.current}; transform: rotate({rotate.current}deg) scale({scale.current})">
+ *   {sum.current}
+ * </div>
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-transform
+ */
+export declare function useTransform<O>(source: TransformSource<number>, input: number[], output: O[], options?: TransformOptions<O>): AugmentedMotionValue<O>;
+export declare function useTransform<T extends TransformOutputMap<unknown>>(source: TransformSource<number>, input: number[], outputMap: T, options?: TransformOptions<T[keyof T][number]>): {
+    [K in keyof T]: AugmentedMotionValue<T[K][number]>;
+};
+export declare function useTransform<I, O>(source: AnyMotionValue<I>, transformer: SingleTransformer<I, O>): AugmentedMotionValue<O>;
+export declare function useTransform<I, O>(sources: ReadonlyArray<AnyMotionValue<I>>, transformer: MultiTransformer<I, O>): AugmentedMotionValue<O>;
+export declare function useTransform<O>(compute: () => O): AugmentedMotionValue<O>;

package/dist/utils/transform.svelte.js

@@ -0,0 +1,189 @@
+// Utilities for building and validating transform strings
+import { isMotionValue, mapValue, transformValue } from 'motion-dom';
+import {} from 'svelte/store';
+import { augmentMotionValue, bridgeReadableToMotionValue } from './augmentMotionValue.svelte.js';
+const DEFAULTS = {
+    x: 0,
+    y: 0,
+    scale: 1,
+    scaleX: 1,
+    scaleY: 1,
+    rotate: 0
+};
+/**
+ * Build a CSS transform string from numeric values (no matrices).
+ *
+ * @param values Partial map of translate/scale/rotate values.
+ * @returns A space-separated CSS `transform` string, or `""` when all values are defaults.
+ *
+ * @example
+ * ```ts
+ * buildTransform({ x: 10, y: 20, scale: 1.5 })
+ * // => "translate(10px, 20px) scale(1.5)"
+ *
+ * buildTransform({ x: 0, y: 0, rotate: 0 }) // all defaults
+ * // => ""
+ * ```
+ */
+export const buildTransform = (values) => {
+    const v = { ...DEFAULTS, ...values };
+    const useAxes = values.scaleX !== undefined || values.scaleY !== undefined;
+    const parts = [];
+    if (v.x !== 0 || v.y !== 0)
+        parts.push(`translate(${round(v.x)}px, ${round(v.y)}px)`);
+    if (v.rotate !== 0)
+        parts.push(`rotate(${round(v.rotate)}deg)`);
+    if (useAxes) {
+        parts.push(`scaleX(${round(v.scaleX)})`);
+        parts.push(`scaleY(${round(v.scaleY)})`);
+    }
+    else if (v.scale !== 1) {
+        parts.push(`scale(${round(v.scale)})`);
+    }
+    return parts.join(' ').trim();
+};
+/**
+ * Lightweight safety check for transform magnitudes and NaN values.
+ *
+ * @param values Transform values to validate.
+ * @param opts Optional configuration; `maxScale` caps allowable absolute scale (default 8).
+ * @returns `true` if all scale values are finite and within bounds.
+ *
+ * @example
+ * ```ts
+ * isSafeTransform({ scale: 2 })                  // true
+ * isSafeTransform({ scale: 100 })                // false (exceeds default maxScale=8)
+ * isSafeTransform({ scale: 100 }, { maxScale: 200 })  // true
+ * isSafeTransform({ scale: NaN })                // false
+ * ```
+ */
+export const isSafeTransform = (values, opts) => {
+    const maxScale = opts?.maxScale ?? 8;
+    const entries = [
+        ['scale', values.scale],
+        ['scaleX', values.scaleX],
+        ['scaleY', values.scaleY]
+    ];
+    for (const [, val] of entries) {
+        if (val === undefined)
+            continue;
+        if (!Number.isFinite(val))
+            return false;
+        if (Math.abs(val) > maxScale)
+            return false;
+    }
+    return true;
+};
+/**
+ * Extract the uniform scale factor from a CSS `matrix()` string.
+ *
+ * @param matrix A CSS `matrix(...)` value, `"none"`, `null`, or `undefined`.
+ * @returns The `a` component of the matrix (uniform scale), or `null` if unparseable.
+ *
+ * @example
+ * ```ts
+ * parseMatrixScale('matrix(1.5, 0, 0, 1.5, 0, 0)')  // 1.5
+ * parseMatrixScale('none')                          // null
+ * parseMatrixScale(null)                            // null
+ * ```
+ */
+export const parseMatrixScale = (matrix) => {
+    if (!matrix || matrix === 'none')
+        return null;
+    const m = matrix.match(/matrix\(([^)]+)\)/);
+    if (!m)
+        return null;
+    const [a] = m[1].split(',').map((s) => parseFloat(s.trim()));
+    return Number.isFinite(a) ? a : null;
+};
+/**
+ * Round a number to six decimal places to avoid excessive precision in CSS strings.
+ *
+ * @param n The number to round.
+ * @returns The rounded value.
+ */
+const round = (n) => {
+    return Math.round(n * 1e6) / 1e6;
+};
+/**
+ * Normalizes a `TransformSource<T>` into a `MotionValue<T>`. Returns the
+ * source as-is for any motion-value input (no bridge), or a bridge
+ * `MotionValue` + cleanup for `Readable` inputs. The cast at the
+ * motion-value branch is safe — both `MotionValue` and `AugmentedMotionValue`
+ * are the same instance at runtime.
+ */
+const toMotionValue = (source) => {
+    if (isMotionValue(source)) {
+        return { value: source, dispose: () => undefined };
+    }
+    return bridgeReadableToMotionValue(source);
+};
+export function useTransform(sourceOrCompute, inputOrTransformer, outputOrOutputMap, options) {
+    // Compute form: useTransform(() => compute).
+    if (typeof sourceOrCompute === 'function') {
+        const compute = sourceOrCompute;
+        const value = transformValue(compute);
+        $effect(() => () => value.destroy());
+        return augmentMotionValue(value);
+    }
+    // Multi-input list form: useTransform([mv, mv, …], ([a, b, …]) => O).
+    if (Array.isArray(sourceOrCompute) && typeof inputOrTransformer === 'function') {
+        const sources = sourceOrCompute;
+        const transformer = inputOrTransformer;
+        const value = transformValue(() => {
+            const latest = [];
+            for (let i = 0; i < sources.length; i++) {
+                latest.push(sources[i].get());
+            }
+            return transformer(latest);
+        });
+        $effect(() => () => value.destroy());
+        return augmentMotionValue(value);
+    }
+    // Single-MV transformer form: useTransform(mv, (latest) => O).
+    if (typeof inputOrTransformer === 'function') {
+        const source = sourceOrCompute;
+        const transformer = inputOrTransformer;
+        const value = transformValue(() => transformer(source.get()));
+        $effect(() => () => value.destroy());
+        return augmentMotionValue(value);
+    }
+    // Mapping forms (single output array or output map).
+    const source = sourceOrCompute;
+    const input = inputOrTransformer ?? [];
+    const { value: numericSource, dispose: disposeBridge } = toMotionValue(source);
+    // Multi-output mapping form: useTransform(source, [range], { key: [out], … }, options).
+    // The `outputOrOutputMap !== null` check is load-bearing — `typeof null`
+    // is `'object'`, so a `null` argument would otherwise enter this branch
+    // and crash at `Object.keys(null)`.
+    if (outputOrOutputMap !== undefined &&
+        outputOrOutputMap !== null &&
+        !Array.isArray(outputOrOutputMap) &&
+        typeof outputOrOutputMap === 'object') {
+        const outputMap = outputOrOutputMap;
+        const keys = Object.keys(outputMap);
+        const result = {};
+        const inners = [];
+        for (const key of keys) {
+            const inner = mapValue(numericSource, input, outputMap[key], options);
+            inners.push(inner);
+            result[key] = augmentMotionValue(inner);
+        }
+        // One cleanup effect for all per-key MVs plus the shared bridge —
+        // saves N effect nodes vs. registering one per key.
+        $effect(() => () => {
+            for (const inner of inners)
+                inner.destroy();
+            disposeBridge();
+        });
+        return result;
+    }
+    // Single-output mapping form: useTransform(source, [range], [out], options).
+    const output = outputOrOutputMap ?? [];
+    const value = mapValue(numericSource, input, output, options);
+    $effect(() => () => {
+        value.destroy();
+        disposeBridge();
+    });
+    return augmentMotionValue(value);
+}

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

@@ -0,0 +1,61 @@
+import { type Readable } from 'svelte/store';
+import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
+/**
+ * Source for {@link useVelocity}: a motion-dom `MotionValue` or a Svelte
+ * readable. Svelte readables are bridged into a `MotionValue` so motion-dom's
+ * native velocity tracking can drive the result.
+ */
+export type VelocitySource = AugmentedMotionValue<number | string> | Readable<number | string>;
+/**
+ * Creates an augmented `MotionValue<number>` whose value tracks the velocity
+ * of `source` in units/second.
+ *
+ * Mirrors React framer-motion 1:1: on every `source` change, schedules an
+ * `updateVelocity` callback in motion-dom's frame loop via
+ * `frame.update(updateVelocity, false, true)`. `updateVelocity` reads
+ * `source.getVelocity()` (motion-dom tracks per-frame deltas + timestamps
+ * for free) and writes it to the result. If velocity is still non-zero,
+ * `updateVelocity` re-schedules itself for the next frame — so the loop
+ * only runs while there's actual motion and snaps to `0` the moment things
+ * settle. Idle CPU is zero.
+ *
+ * Returned value is a real motion-dom `MotionValue` (composes with
+ * `useTransform`, `useSpring`, `useMotionTemplate`, etc.) plus a
+ * `$state`-backed `.current` getter and a `.subscribe` shim.
+ *
+ * Lifecycle: must be called during component initialization. The change
+ * subscription, the frame-loop callback, and any Svelte-readable bridge are
+ * all torn down when the surrounding `$effect` unmounts.
+ *
+ * SSR-safe: returns a static augmented motion value with no subscriptions
+ * and no frame loop on the server.
+ *
+ * @param source A motion value or readable store of numeric or unit-string values.
+ * @returns A `MotionValue<number>` with `.current` and `.subscribe`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import {
+ *     useMotionValue,
+ *     useTransform,
+ *     useVelocity
+ *   } from '@humanspeak/svelte-motion'
+ *
+ *   const x = useMotionValue(0)
+ *   const xVelocity = useVelocity(x)
+ *   // Map velocity to a momentum-driven skew. Skew goes positive when x is
+ *   // accelerating right, negative when accelerating left, and snaps to 0
+ *   // when motion settles.
+ *   const skew = useTransform(xVelocity, [-1000, 0, 1000], [-15, 0, 15])
+ * </script>
+ *
+ * <div
+ *   style="transform: translateX({x.current}px) skewX({skew.current}deg)"
+ *   onpointermove={(e) => x.set(e.clientX)}
+ * />
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-velocity
+ */
+export declare const useVelocity: (source: VelocitySource) => AugmentedMotionValue<number>;

package/dist/utils/velocity.svelte.js

@@ -0,0 +1,132 @@
+import { cancelFrame, frame, isMotionValue, motionValue } from 'motion-dom';
+import {} from 'svelte/store';
+import { augmentMotionValue, bridgeReadableToMotionValue } from './augmentMotionValue.svelte.js';
+/**
+ * Parses a numeric value from a number or unit string (e.g. `"100px"` → `100`).
+ */
+const parseNumeric = (v) => {
+    if (typeof v === 'number')
+        return v;
+    const parsed = Number.parseFloat(String(v));
+    return Number.isFinite(parsed) ? parsed : 0;
+};
+/**
+ * Creates an augmented `MotionValue<number>` whose value tracks the velocity
+ * of `source` in units/second.
+ *
+ * Mirrors React framer-motion 1:1: on every `source` change, schedules an
+ * `updateVelocity` callback in motion-dom's frame loop via
+ * `frame.update(updateVelocity, false, true)`. `updateVelocity` reads
+ * `source.getVelocity()` (motion-dom tracks per-frame deltas + timestamps
+ * for free) and writes it to the result. If velocity is still non-zero,
+ * `updateVelocity` re-schedules itself for the next frame — so the loop
+ * only runs while there's actual motion and snaps to `0` the moment things
+ * settle. Idle CPU is zero.
+ *
+ * Returned value is a real motion-dom `MotionValue` (composes with
+ * `useTransform`, `useSpring`, `useMotionTemplate`, etc.) plus a
+ * `$state`-backed `.current` getter and a `.subscribe` shim.
+ *
+ * Lifecycle: must be called during component initialization. The change
+ * subscription, the frame-loop callback, and any Svelte-readable bridge are
+ * all torn down when the surrounding `$effect` unmounts.
+ *
+ * SSR-safe: returns a static augmented motion value with no subscriptions
+ * and no frame loop on the server.
+ *
+ * @param source A motion value or readable store of numeric or unit-string values.
+ * @returns A `MotionValue<number>` with `.current` and `.subscribe`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import {
+ *     useMotionValue,
+ *     useTransform,
+ *     useVelocity
+ *   } from '@humanspeak/svelte-motion'
+ *
+ *   const x = useMotionValue(0)
+ *   const xVelocity = useVelocity(x)
+ *   // Map velocity to a momentum-driven skew. Skew goes positive when x is
+ *   // accelerating right, negative when accelerating left, and snaps to 0
+ *   // when motion settles.
+ *   const skew = useTransform(xVelocity, [-1000, 0, 1000], [-15, 0, 15])
+ * </script>
+ *
+ * <div
+ *   style="transform: translateX({x.current}px) skewX({skew.current}deg)"
+ *   onpointermove={(e) => x.set(e.clientX)}
+ * />
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-velocity
+ */
+export const useVelocity = (source) => {
+    // Bridge non-numeric sources into a MotionValue<number> so motion-dom's
+    // getVelocity() tracks deltas correctly. Two paths feed this:
+    //   1. Svelte readables — always bridged (motion-dom doesn't know how to
+    //      read them).
+    //   2. MotionValue<string> — bridged too, because motion-dom samples
+    //      `canTrackVelocity` ONCE from the initial value via
+    //      `!isNaN(parseFloat(value))`. A string MV that starts non-numeric
+    //      (e.g. `""`) gets stuck at velocity = 0 forever, even if it later
+    //      becomes a unit string like `"100px"`. The bridge runs every emit
+    //      through `parseNumeric` so the tracker MV is always numeric.
+    let tracker;
+    let disposeBridge;
+    if (isMotionValue(source)) {
+        const initial = source.get();
+        if (typeof initial === 'number') {
+            tracker = source;
+        }
+        else if (typeof window !== 'undefined') {
+            const bridge = motionValue(parseNumeric(initial));
+            const unsub = source.on('change', (v) => {
+                bridge.set(parseNumeric(v));
+            });
+            tracker = bridge;
+            disposeBridge = () => {
+                unsub();
+                bridge.destroy();
+            };
+        }
+        else {
+            // SSR: parse the initial value but don't subscribe — the change
+            // listener would leak past the early SSR return below (no
+            // $effect runs to call dispose).
+            tracker = motionValue(parseNumeric(initial));
+        }
+    }
+    else if (typeof window !== 'undefined') {
+        const bridge = bridgeReadableToMotionValue(source, parseNumeric);
+        tracker = bridge.value;
+        disposeBridge = bridge.dispose;
+    }
+    else {
+        tracker = motionValue(0);
+    }
+    const result = motionValue(tracker.getVelocity());
+    // SSR: skip the frame-loop wiring entirely and return a static MV.
+    if (typeof window === 'undefined') {
+        return augmentMotionValue(result);
+    }
+    const updateVelocity = () => {
+        const latest = tracker.getVelocity();
+        result.set(latest);
+        if (latest)
+            frame.update(updateVelocity);
+    };
+    const unsubChange = tracker.on('change', () => {
+        // keepAlive: false, immediate: true — run at end of current frame if
+        // we're already in one. Matches React framer-motion's useVelocity.
+        frame.update(updateVelocity, false, true);
+    });
+    $effect(() => () => {
+        unsubChange();
+        cancelFrame(updateVelocity);
+        disposeBridge?.();
+        result.destroy();
+    });
+    return augmentMotionValue(result);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.4.9",
+  "version": "0.5.0",
   "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",