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>;