@humanspeak/svelte-motion 0.4.9 → 0.5.0

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

@@ -0,0 +1,61 @@
+import { type MotionValue as MotionDomMotionValue } from 'motion-dom';
+import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
+/**
+ * The shape returned by {@link useMotionValue}: a real motion-dom
+ * `MotionValue<T>` (so it composes with `animate()`, `useTransform`,
+ * `useSpring`, etc. and passes `isMotionValue`) plus a Svelte 5 reactive
+ * `.current` getter and a Svelte readable store `.subscribe` shim.
+ *
+ * @template T The value type — typically `number` or `string`.
+ * @see {@link AugmentedMotionValue}
+ */
+export type MotionValue<T = number> = AugmentedMotionValue<T>;
+/**
+ * Re-export of motion-dom's raw `MotionValue` type for cases where the
+ * un-augmented shape is needed (e.g. typing follow sources, function
+ * dependencies). Most call sites should prefer {@link MotionValue}.
+ */
+export type RawMotionValue<T = number> = MotionDomMotionValue<T>;
+/**
+ * Creates a tracked, mutable value backed by motion-dom's `MotionValue`.
+ *
+ * Use `.set(v)` to write the value imperatively, `.get()` to sample it
+ * imperatively, and `.current` to read it inside Svelte 5 reactive scopes
+ * (templates, `$derived`, `$effect`). The same value also implements the
+ * Svelte readable store contract via `.subscribe(run)`, so legacy `$mv`
+ * template syntax and `svelte/store`'s `get()` keep working.
+ *
+ * Returned object is a real motion-dom `MotionValue` — it composes with
+ * `useTransform`, `useSpring`, `useVelocity`, the `animate()` driver, and
+ * passes `isMotionValue`. Unlike `useSpring`, writes are immediate — there
+ * is no follow source and no animation.
+ *
+ * Lifecycle: must be called during component initialization. Cleanup is
+ * registered via `$effect`; motion-dom's internal listeners and animation
+ * subscriptions are released when the surrounding component / effect tears
+ * down. Call `.destroy()` to clean up early.
+ *
+ * SSR-safe: motion-dom's `motionValue` runs without DOM access; on the
+ * server reads return the initial value and writes still work, with no
+ * timers or listeners attached.
+ *
+ * @template T The value type — typically `number` or `string`.
+ * @param initial The starting value.
+ * @returns A `MotionValue<T>` augmented with `.current` and `.subscribe`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useMotionValue, useTransform } from '@humanspeak/svelte-motion'
+ *
+ *   const x = useMotionValue(0)
+ *   const opacity = useTransform(x, [0, 200], [0, 1])
+ * </script>
+ *
+ * <input type="range" min="0" max="200" oninput={(e) => x.set(+e.currentTarget.value)} />
+ * <div style="opacity: {opacity.current}">x = {x.current}</div>
+ * ```
+ *
+ * @see https://motion.dev/docs/react-motion-value
+ */
+export declare const useMotionValue: <T = number>(initial: T) => MotionValue<T>;

package/dist/utils/motionValue.svelte.js

@@ -0,0 +1,49 @@
+import { motionValue } from 'motion-dom';
+import { augmentMotionValue } from './augmentMotionValue.svelte.js';
+/**
+ * Creates a tracked, mutable value backed by motion-dom's `MotionValue`.
+ *
+ * Use `.set(v)` to write the value imperatively, `.get()` to sample it
+ * imperatively, and `.current` to read it inside Svelte 5 reactive scopes
+ * (templates, `$derived`, `$effect`). The same value also implements the
+ * Svelte readable store contract via `.subscribe(run)`, so legacy `$mv`
+ * template syntax and `svelte/store`'s `get()` keep working.
+ *
+ * Returned object is a real motion-dom `MotionValue` — it composes with
+ * `useTransform`, `useSpring`, `useVelocity`, the `animate()` driver, and
+ * passes `isMotionValue`. Unlike `useSpring`, writes are immediate — there
+ * is no follow source and no animation.
+ *
+ * Lifecycle: must be called during component initialization. Cleanup is
+ * registered via `$effect`; motion-dom's internal listeners and animation
+ * subscriptions are released when the surrounding component / effect tears
+ * down. Call `.destroy()` to clean up early.
+ *
+ * SSR-safe: motion-dom's `motionValue` runs without DOM access; on the
+ * server reads return the initial value and writes still work, with no
+ * timers or listeners attached.
+ *
+ * @template T The value type — typically `number` or `string`.
+ * @param initial The starting value.
+ * @returns A `MotionValue<T>` augmented with `.current` and `.subscribe`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useMotionValue, useTransform } from '@humanspeak/svelte-motion'
+ *
+ *   const x = useMotionValue(0)
+ *   const opacity = useTransform(x, [0, 200], [0, 1])
+ * </script>
+ *
+ * <input type="range" min="0" max="200" oninput={(e) => x.set(+e.currentTarget.value)} />
+ * <div style="opacity: {opacity.current}">x = {x.current}</div>
+ * ```
+ *
+ * @see https://motion.dev/docs/react-motion-value
+ */
+export const useMotionValue = (initial) => {
+    const value = motionValue(initial);
+    $effect(() => () => value.destroy());
+    return augmentMotionValue(value);
+};

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

@@ -0,0 +1,91 @@
+import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
+import { type ElementOrGetter } from './dom.js';
+/**
+ * A scroll offset edge defined as a string (e.g. `"start"`, `"end"`,
+ * `"center"`) or a number (0–1 progress). Each offset entry is a pair of
+ * `[target, container]`.
+ *
+ * Intentionally looser than motion's internal `ScrollOffset` type — that
+ * uses template-literal types (`` `${Edge} ${Edge}` ``) we don't want to
+ * surface to consumers. The runtime call paths through `scroll(...)` cast
+ * `options.offset as never` to bridge the two; safe because every shape our
+ * type allows is structurally a member of motion's union.
+ */
+type ScrollOffset = Array<[number | string, number | string]> | string[];
+/**
+ * Options accepted by {@link useScroll}.
+ */
+export type UseScrollOptions = {
+    /** Scrollable container to track. Defaults to the page. Accepts an element or a getter function. */
+    container?: ElementOrGetter;
+    /** Target element to track position of within the container. Accepts an element or a getter function. */
+    target?: ElementOrGetter;
+    /** Scroll offset configuration for element position tracking. */
+    offset?: ScrollOffset;
+    /** Which axis to use for the single-axis `progress` value supplied to `scroll()`. */
+    axis?: 'x' | 'y';
+};
+/**
+ * Return type of {@link useScroll} — four motion-dom `MotionValue<number>`s
+ * representing scroll position and normalised progress for both axes, each
+ * augmented with `.current` + `.subscribe`.
+ */
+export type UseScrollReturn = {
+    scrollX: AugmentedMotionValue<number>;
+    scrollY: AugmentedMotionValue<number>;
+    scrollXProgress: AugmentedMotionValue<number>;
+    scrollYProgress: AugmentedMotionValue<number>;
+};
+/**
+ * Creates scroll-linked motion values for building scroll-driven animations
+ * such as progress indicators and parallax effects.
+ *
+ * Returns four `MotionValue<number>`s: `scrollX` / `scrollY` (current
+ * position in px) and `scrollXProgress` / `scrollYProgress` (0–1
+ * normalised). Each is a real motion-dom `MotionValue` augmented with a
+ * `$state`-backed `.current` getter and a `.subscribe` shim, so they
+ * compose with `useTransform`, `useSpring`, and the rest of the Tier 2
+ * surface, and they read reactively in Svelte 5 templates.
+ *
+ * **GPU-accelerated when supported.** On browsers that implement CSS
+ * scroll-timeline (no `target`) or view-timeline (with a `target` and a
+ * preset `offset`), the *Progress motion values run on the compositor
+ * thread via WAAPI — no per-frame JS callback. The non-progress
+ * `scrollX` / `scrollY` motion values always use the JS-driven `scroll()`
+ * primitive since the absolute pixel offset isn't directly available from
+ * native timelines.
+ *
+ * `container` and `target` accept either an `HTMLElement` directly or a
+ * getter `() => HTMLElement | undefined`. The getter form is the right
+ * choice with `bind:this`. Element resolution is deferred to a microtask
+ * (matches React framer-motion 1:1, faster than rAF polling), so a getter
+ * that hasn't hydrated yet is retried as soon as Svelte's mount tick
+ * settles it.
+ *
+ * Lifecycle: the underlying `scroll()` observer and any accelerate factory
+ * attach at mount via `$effect` and detach at unmount, regardless of how
+ * many consumers are reading the values. The four motion values are torn
+ * down at the same time.
+ *
+ * SSR-safe: returns four static `motionValue(0)`s with no scroll observer
+ * on the server.
+ *
+ * @param options Optional scroll tracking configuration.
+ * @returns Four `MotionValue<number>`s — `scrollX`, `scrollY`, `scrollXProgress`, `scrollYProgress`.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useScroll, useSpring } from '@humanspeak/svelte-motion'
+ *
+ *   const { scrollYProgress } = useScroll()
+ *   const scaleX = useSpring(scrollYProgress)
+ * </script>
+ *
+ * <div style="transform: scaleX({scaleX.current}); transform-origin: left;" />
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-scroll
+ */
+export declare const useScroll: (options?: UseScrollOptions) => UseScrollReturn;
+export {};

package/dist/utils/scroll.svelte.js

@@ -0,0 +1,259 @@
+import { scroll } from 'motion';
+import { cancelMicrotask, microtask, motionValue, supportsScrollTimeline, supportsViewTimeline } from 'motion-dom';
+import { augmentMotionValue } from './augmentMotionValue.svelte.js';
+import { isRefPending, resolveElement } from './dom.js';
+/**
+ * Named view-timeline presets — mirror framer-motion's ScrollOffset table.
+ * Each entry is a pair of `[target, container]` intersection points that
+ * defines a phase of the scroll relationship.
+ */
+const VIEW_TIMELINE_PRESETS = [
+    [
+        [
+            [0, 1],
+            [1, 1]
+        ],
+        'entry'
+    ],
+    [
+        [
+            [0, 0],
+            [1, 0]
+        ],
+        'exit'
+    ],
+    [
+        [
+            [1, 0],
+            [0, 1]
+        ],
+        'cover'
+    ],
+    [
+        [
+            [0, 0],
+            [1, 1]
+        ],
+        'contain'
+    ]
+];
+const PROGRESS_BY_STRING = { start: 0, end: 1 };
+/**
+ * Parse `"start end"` / `"end start"` / etc. into an explicit
+ * `[target, container]` intersection pair.
+ */
+const parseStringOffset = (s) => {
+    const parts = s.trim().split(/\s+/);
+    if (parts.length !== 2)
+        return undefined;
+    const a = PROGRESS_BY_STRING[parts[0]];
+    const b = PROGRESS_BY_STRING[parts[1]];
+    if (a === undefined || b === undefined)
+        return undefined;
+    return [a, b];
+};
+/**
+ * Normalize a {@link ScrollOffset} into an array of explicit intersection
+ * pairs, or `undefined` if the shape doesn't match the simple two-element
+ * preset form.
+ */
+const normaliseOffset = (offset) => {
+    if (offset.length !== 2)
+        return undefined;
+    const result = [];
+    for (const item of offset) {
+        if (Array.isArray(item)) {
+            result.push(item);
+        }
+        else if (typeof item === 'string') {
+            const parsed = parseStringOffset(item);
+            if (!parsed)
+                return undefined;
+            result.push(parsed);
+        }
+        else {
+            return undefined;
+        }
+    }
+    return result;
+};
+const matchesPreset = (offset, preset) => {
+    const normalised = normaliseOffset(offset);
+    if (!normalised)
+        return false;
+    for (let i = 0; i < 2; i++) {
+        const o = normalised[i];
+        const p = preset[i];
+        if (o[0] !== p[0] || o[1] !== p[1])
+            return false;
+    }
+    return true;
+};
+/**
+ * Map a {@link ScrollOffset} to its corresponding CSS view-timeline range, if
+ * any. Returning `undefined` signals the caller to fall back to JS-driven
+ * scroll tracking. Mirrors framer-motion's `offsetToViewTimelineRange`.
+ */
+const offsetToViewTimelineRange = (offset) => {
+    if (!offset)
+        return { rangeStart: 'contain 0%', rangeEnd: 'contain 100%' };
+    for (const [preset, name] of VIEW_TIMELINE_PRESETS) {
+        if (matchesPreset(offset, preset)) {
+            return { rangeStart: `${name} 0%`, rangeEnd: `${name} 100%` };
+        }
+    }
+    return undefined;
+};
+/**
+ * Whether this scroll configuration can be driven by a native CSS
+ * scroll-timeline / view-timeline. When `true`, the resulting motion value
+ * runs on the compositor thread without per-frame JS callbacks.
+ */
+const canAccelerateScroll = (target, offset) => {
+    if (typeof window === 'undefined')
+        return false;
+    return target
+        ? supportsViewTimeline() && !!offsetToViewTimelineRange(offset)
+        : supportsScrollTimeline();
+};
+/**
+ * Build the AccelerateConfig for a progress motion value driven by a native
+ * scroll-timeline / view-timeline animation. Mirrors framer-motion's
+ * `makeAccelerateConfig` 1:1: the `factory` defers `scroll()` until refs
+ * hydrate via `microtask.read`, then attaches the animation; the `times` /
+ * `keyframes` / `ease` / `duration` describe the 0→1 linear mapping.
+ */
+const makeAccelerateConfig = (axis, options) => ({
+    factory: (animation) => {
+        let cleanup;
+        const start = () => {
+            if (isRefPending(options.container) || isRefPending(options.target)) {
+                microtask.read(start);
+                return;
+            }
+            cleanup = scroll(animation, {
+                offset: options.offset,
+                axis,
+                container: resolveElement(options.container),
+                target: resolveElement(options.target)
+            });
+        };
+        microtask.read(start);
+        return () => {
+            cancelMicrotask(start);
+            cleanup?.();
+        };
+    },
+    times: [0, 1],
+    keyframes: [0, 1],
+    ease: (v) => v,
+    duration: 1
+});
+/**
+ * Creates scroll-linked motion values for building scroll-driven animations
+ * such as progress indicators and parallax effects.
+ *
+ * Returns four `MotionValue<number>`s: `scrollX` / `scrollY` (current
+ * position in px) and `scrollXProgress` / `scrollYProgress` (0–1
+ * normalised). Each is a real motion-dom `MotionValue` augmented with a
+ * `$state`-backed `.current` getter and a `.subscribe` shim, so they
+ * compose with `useTransform`, `useSpring`, and the rest of the Tier 2
+ * surface, and they read reactively in Svelte 5 templates.
+ *
+ * **GPU-accelerated when supported.** On browsers that implement CSS
+ * scroll-timeline (no `target`) or view-timeline (with a `target` and a
+ * preset `offset`), the *Progress motion values run on the compositor
+ * thread via WAAPI — no per-frame JS callback. The non-progress
+ * `scrollX` / `scrollY` motion values always use the JS-driven `scroll()`
+ * primitive since the absolute pixel offset isn't directly available from
+ * native timelines.
+ *
+ * `container` and `target` accept either an `HTMLElement` directly or a
+ * getter `() => HTMLElement | undefined`. The getter form is the right
+ * choice with `bind:this`. Element resolution is deferred to a microtask
+ * (matches React framer-motion 1:1, faster than rAF polling), so a getter
+ * that hasn't hydrated yet is retried as soon as Svelte's mount tick
+ * settles it.
+ *
+ * Lifecycle: the underlying `scroll()` observer and any accelerate factory
+ * attach at mount via `$effect` and detach at unmount, regardless of how
+ * many consumers are reading the values. The four motion values are torn
+ * down at the same time.
+ *
+ * SSR-safe: returns four static `motionValue(0)`s with no scroll observer
+ * on the server.
+ *
+ * @param options Optional scroll tracking configuration.
+ * @returns Four `MotionValue<number>`s — `scrollX`, `scrollY`, `scrollXProgress`, `scrollYProgress`.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useScroll, useSpring } from '@humanspeak/svelte-motion'
+ *
+ *   const { scrollYProgress } = useScroll()
+ *   const scaleX = useSpring(scrollYProgress)
+ * </script>
+ *
+ * <div style="transform: scaleX({scaleX.current}); transform-origin: left;" />
+ * ```
+ *
+ * @see https://motion.dev/docs/react-use-scroll
+ */
+export const useScroll = (options = {}) => {
+    const scrollX = motionValue(0);
+    const scrollY = motionValue(0);
+    const scrollXProgress = motionValue(0);
+    const scrollYProgress = motionValue(0);
+    // SSR: return static motion values with no observer and no $effect.
+    if (typeof window === 'undefined') {
+        return {
+            scrollX: augmentMotionValue(scrollX),
+            scrollY: augmentMotionValue(scrollY),
+            scrollXProgress: augmentMotionValue(scrollXProgress),
+            scrollYProgress: augmentMotionValue(scrollYProgress)
+        };
+    }
+    // The *Progress MVs accelerate to the compositor thread when the browser
+    // supports CSS scroll/view-timelines; the non-progress scrollX/scrollY
+    // MVs always need the JS callback for absolute pixel offsets.
+    if (canAccelerateScroll(options.target, options.offset)) {
+        scrollXProgress.accelerate = makeAccelerateConfig('x', options);
+        scrollYProgress.accelerate = makeAccelerateConfig('y', options);
+    }
+    let cleanup;
+    const start = () => {
+        if (isRefPending(options.container) || isRefPending(options.target)) {
+            microtask.read(start);
+            return;
+        }
+        cleanup = scroll((_progress, info) => {
+            scrollX.set(info.x.current);
+            scrollY.set(info.y.current);
+            scrollXProgress.set(info.x.progress);
+            scrollYProgress.set(info.y.progress);
+        }, {
+            container: resolveElement(options.container),
+            target: resolveElement(options.target),
+            offset: options.offset,
+            axis: options.axis
+        });
+    };
+    $effect(() => {
+        microtask.read(start);
+        return () => {
+            cancelMicrotask(start);
+            cleanup?.();
+            scrollX.destroy();
+            scrollY.destroy();
+            scrollXProgress.destroy();
+            scrollYProgress.destroy();
+        };
+    });
+    return {
+        scrollX: augmentMotionValue(scrollX),
+        scrollY: augmentMotionValue(scrollY),
+        scrollXProgress: augmentMotionValue(scrollXProgress),
+        scrollYProgress: augmentMotionValue(scrollYProgress)
+    };
+};

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

@@ -1,5 +1,6 @@
 import { type FollowValueOptions, type MotionValue, type SpringOptions } from 'motion-dom';
 import { type Readable } from 'svelte/store';
+import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
 /**
  * Spring + follow options for {@link useSpring}.
  *
@@ -25,12 +26,7 @@ export type UseSpringOptions = SpringOptions & Pick<FollowValueOptions, 'skipIni
  *   spring be used with `$spring` template syntax, `get(spring)`, and as a
  *   dependency in `useTransform`'s function form.
  */
-export type SpringMotionValue<T extends number | string> = 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;
-};
+export type SpringMotionValue<T extends number | string> = AugmentedMotionValue<T>;
 /**
  * Creates a spring-animated `MotionValue`.
  *

package/dist/utils/spring.svelte.js

@@ -1,26 +1,16 @@
 import { attachFollow, isMotionValue, motionValue } from 'motion-dom';
-import { get } from 'svelte/store';
-/**
- * Detects a Svelte readable store. Excludes motion-dom `MotionValue` instances
- * (which also expose `subscribe`-shaped APIs in some versions) so the
- * MotionValue path is preferred.
- */
-const isSvelteReadable = (value) => {
-    return (!!value &&
-        typeof value === 'object' &&
-        typeof value.subscribe === 'function' &&
-        !isMotionValue(value));
-};
+import {} from 'svelte/store';
+import { augmentMotionValue, isSvelteReadable, sampleSource } from './augmentMotionValue.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 = readInitial(source);
+        const initial = sampleSource(source);
         const ssrValue = motionValue(initial);
         ssrValue.set = () => undefined;
         ssrValue.jump = () => undefined;
-        return augmentForSvelte(ssrValue, () => undefined);
+        return augmentMotionValue(ssrValue);
     }
     // Resolve initial + follow source.
     let followSource;
@@ -32,7 +22,7 @@ export function useSpring(source, options = {}) {
     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 = get(source);
+        const initialFromReadable = sampleSource(source);
         svelteBridge = motionValue(initialFromReadable);
         cleanupReadableBridge = source.subscribe((v) => {
             // The Svelte readable contract calls the subscriber synchronously
@@ -60,59 +50,5 @@ export function useSpring(source, options = {}) {
         svelteBridge?.destroy();
     };
     $effect(() => () => value.destroy());
-    return augmentForSvelte(value, dispose);
+    return augmentMotionValue(value, dispose);
 }
-/**
- * Pull the synchronous initial value out of any accepted source form.
- */
-const readInitial = (source) => {
-    if (typeof source === 'number' || typeof source === 'string')
-        return source;
-    if (isMotionValue(source))
-        return source.get();
-    if (isSvelteReadable(source))
-        return get(source);
-    return 0;
-};
-/**
- * Layer Svelte-friendly affordances onto a motion-dom MotionValue: a
- * `$state`-tracked `.current` accessor (routing motion-dom's internal
- * `this.current = v` writes through `$state` so templates and `$derived` /
- * `$effect` re-run) and a Svelte readable store `.subscribe(run)` shim.
- */
-const augmentForSvelte = (value, dispose) => {
-    let current = $state(value.get());
-    Object.defineProperty(value, 'current', {
-        get: () => current,
-        // Same-value writes are no-ops: motion-dom's `updateAndNotify` calls
-        // `setCurrent(v)` before its own change check, so spring frames at
-        // rest still hit this setter; skipping equal writes avoids gratuitous
-        // accessor work even though $state would itself dedupe.
-        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;
-};

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

@@ -0,0 +1,47 @@
+import { type AugmentedMotionValue } from './augmentMotionValue.svelte.js';
+/**
+ * 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 declare const useTime: (id?: string) => AugmentedMotionValue<number>;