@humanspeak/svelte-motion 0.1.25 → 0.1.27

package/dist/components/motionConfig.context.d.ts

@@ -1,3 +1,14 @@
 import type { MotionConfigProps } from '../types.js';
+/**
+ * Retrieve the current motion configuration from Svelte component context.
+ *
+ * @returns The active `MotionConfigProps`, or `undefined` if none was set by a parent.
+ */
 export declare const getMotionConfig: () => MotionConfigProps | undefined;
+/**
+ * Provide motion configuration to descendant components via Svelte context.
+ *
+ * @param motionConfig The configuration to propagate (e.g. `transition`).
+ * @returns The same `MotionConfigProps` that was set.
+ */
 export declare const createMotionConfig: (motionConfig: MotionConfigProps) => MotionConfigProps;

package/dist/components/motionConfig.context.js

@@ -1,8 +1,19 @@
 import { getContext, setContext } from 'svelte';
 const key = Symbol('motionConfig');
+/**
+ * Retrieve the current motion configuration from Svelte component context.
+ *
+ * @returns The active `MotionConfigProps`, or `undefined` if none was set by a parent.
+ */
 export const getMotionConfig = () => {
     return getContext(key);
 };
+/**
+ * Provide motion configuration to descendant components via Svelte context.
+ *
+ * @param motionConfig The configuration to propagate (e.g. `transition`).
+ * @returns The same `MotionConfigProps` that was set.
+ */
 export const createMotionConfig = (motionConfig) => {
     return setContext(key, motionConfig);
 };

package/dist/components/variantContext.context.d.ts

@@ -2,18 +2,26 @@ import type { Writable } from 'svelte/store';
 /**
  * Provide a writable store for the current variant key so children can
  * react to changes over time (true inheritance like Framer Motion).
+ *
+ * @param store Writable store holding the current variant name.
  */
-export declare function setVariantContext(store: Writable<string | undefined>): void;
+export declare const setVariantContext: (store: Writable<string | undefined>) => void;
 /**
  * Read the parent's variant store (if any). Children subscribe to this store
  * to inherit and react to parent `animate` changes.
+ *
+ * @returns The parent variant store, or `undefined` if none exists.
  */
-export declare function getVariantContext(): Writable<string | undefined> | undefined;
+export declare const getVariantContext: () => Writable<string | undefined> | undefined;
 /**
- * Set initial={false} in context so children inherit it
+ * Set initial={false} in context so children inherit it.
+ *
+ * @param value Whether the parent has `initial={false}`.
  */
-export declare function setInitialFalseContext(value: boolean): void;
+export declare const setInitialFalseContext: (value: boolean) => void;
 /**
- * Check if parent has initial={false}
+ * Check if parent has initial={false}.
+ *
+ * @returns `true` if a parent set `initial={false}`, otherwise `false`.
  */
-export declare function getInitialFalseContext(): boolean;
+export declare const getInitialFalseContext: () => boolean;

package/dist/components/variantContext.context.js

@@ -4,26 +4,34 @@ const INITIAL_FALSE_CONTEXT_KEY = Symbol('initial-false-context');
 /**
  * Provide a writable store for the current variant key so children can
  * react to changes over time (true inheritance like Framer Motion).
+ *
+ * @param store Writable store holding the current variant name.
  */
-export function setVariantContext(store) {
+export const setVariantContext = (store) => {
     setContext(VARIANT_CONTEXT_KEY, store);
-}
+};
 /**
  * Read the parent's variant store (if any). Children subscribe to this store
  * to inherit and react to parent `animate` changes.
+ *
+ * @returns The parent variant store, or `undefined` if none exists.
  */
-export function getVariantContext() {
+export const getVariantContext = () => {
     return getContext(VARIANT_CONTEXT_KEY);
-}
+};
 /**
- * Set initial={false} in context so children inherit it
+ * Set initial={false} in context so children inherit it.
+ *
+ * @param value Whether the parent has `initial={false}`.
  */
-export function setInitialFalseContext(value) {
+export const setInitialFalseContext = (value) => {
     setContext(INITIAL_FALSE_CONTEXT_KEY, value);
-}
+};
 /**
- * Check if parent has initial={false}
+ * Check if parent has initial={false}.
+ *
+ * @returns `true` if a parent set `initial={false}`, otherwise `false`.
  */
-export function getInitialFalseContext() {
+export const getInitialFalseContext = () => {
     return getContext(INITIAL_FALSE_CONTEXT_KEY) ?? false;
-}
+};

package/dist/index.d.ts

@@ -9,6 +9,8 @@ export type { DragAxis, DragConstraints, DragControls, DragInfo, DragTransition,
 export { useAnimationFrame } from './utils/animationFrame';
 export { createDragControls } from './utils/dragControls';
 export { useMotionTemplate } from './utils/motionTemplate';
+export { useMotionValueEvent } from './utils/motionValueEvent';
+export { useScroll } from './utils/scroll';
 export { useSpring } from './utils/spring';
 export { useVelocity } from './utils/velocity';
 /**

package/dist/index.js

@@ -12,6 +12,8 @@ export { clamp, distance, distance2D, interpolate, mix, pipe, progress, wrap } f
 export { useAnimationFrame } from './utils/animationFrame';
 export { createDragControls } from './utils/dragControls';
 export { useMotionTemplate } from './utils/motionTemplate';
+export { useMotionValueEvent } from './utils/motionValueEvent';
+export { useScroll } from './utils/scroll';
 export { useSpring } from './utils/spring';
 export { useVelocity } from './utils/velocity';
 /**

package/dist/utils/animationFrame.d.ts

@@ -32,4 +32,4 @@
  * <div bind:this={ref}>Animated content</div>
  * ```
  */
-export declare function useAnimationFrame(callback: (time: DOMHighResTimeStamp) => void): () => void;
+export declare const useAnimationFrame: (callback: (time: DOMHighResTimeStamp) => void) => (() => void);

package/dist/utils/animationFrame.js

@@ -32,7 +32,7 @@
  * <div bind:this={ref}>Animated content</div>
  * ```
  */
-export function useAnimationFrame(callback) {
+export const useAnimationFrame = (callback) => {
     // SSR guard
     if (typeof window === 'undefined')
         return () => { };
@@ -51,4 +51,4 @@ export function useAnimationFrame(callback) {
             cancelAnimationFrame(rafId);
         }
     };
-}
+};

package/dist/utils/dragMath.d.ts

@@ -3,10 +3,12 @@
  * Preserves float precision.
  */
 export declare const mixNumber: (from: number, to: number, t: number) => number;
+/** Range with optional min/max boundaries for constraining a point. */
 export type ConstraintRange = {
     min?: number;
     max?: number;
 };
+/** Per-side elastic factors, a uniform factor, or `undefined` for no elasticity. */
 export type ConstraintElastic = {
     min: number;
     max: number;
@@ -15,5 +17,20 @@ export type ConstraintElastic = {
  * Apply float-safe constraints with optional elastic mixing.
  * Mirrors Framer Motion behavior: clamp via Math.min/Math.max with no rounding.
  * If `elastic` provided, blends toward the bound using its side-specific factor.
+ *
+ * @param point The unconstrained value to clamp.
+ * @param range Min/max boundaries. Either or both may be omitted.
+ * @param elastic Optional per-side elastic factor(s) in [0,1]. When provided,
+ *   the value is interpolated toward the boundary instead of hard-clamped.
+ * @returns The constrained (and optionally elastically blended) value.
+ *
+ * @example
+ * ```ts
+ * // Hard clamp to [0, 100]
+ * applyConstraints(120, { min: 0, max: 100 }) // 100
+ *
+ * // Elastic overshoot (50 % blend toward max)
+ * applyConstraints(120, { min: 0, max: 100 }, 0.5) // 110
+ * ```
  */
-export declare function applyConstraints(point: number, range: ConstraintRange, elastic?: ConstraintElastic): number;
+export declare const applyConstraints: (point: number, range: ConstraintRange, elastic?: ConstraintElastic) => number;

package/dist/utils/dragMath.js

@@ -7,8 +7,23 @@ export const mixNumber = (from, to, t) => from + (to - from) * t;
  * Apply float-safe constraints with optional elastic mixing.
  * Mirrors Framer Motion behavior: clamp via Math.min/Math.max with no rounding.
  * If `elastic` provided, blends toward the bound using its side-specific factor.
+ *
+ * @param point The unconstrained value to clamp.
+ * @param range Min/max boundaries. Either or both may be omitted.
+ * @param elastic Optional per-side elastic factor(s) in [0,1]. When provided,
+ *   the value is interpolated toward the boundary instead of hard-clamped.
+ * @returns The constrained (and optionally elastically blended) value.
+ *
+ * @example
+ * ```ts
+ * // Hard clamp to [0, 100]
+ * applyConstraints(120, { min: 0, max: 100 }) // 100
+ *
+ * // Elastic overshoot (50 % blend toward max)
+ * applyConstraints(120, { min: 0, max: 100 }, 0.5) // 110
+ * ```
  */
-export function applyConstraints(point, range, elastic) {
+export const applyConstraints = (point, range, elastic) => {
     const hasMin = range.min !== undefined;
     const hasMax = range.max !== undefined;
     if (hasMin && point < range.min) {
@@ -26,4 +41,4 @@ export function applyConstraints(point, range, elastic) {
         return Math.min(point, range.max);
     }
     return point;
-}
+};

package/dist/utils/dragParams.d.ts

@@ -27,10 +27,10 @@ export type BoundaryPhysics = {
  *   - `timeConstant` is expressed in seconds and internally converted to milliseconds.
  * @returns {BoundaryPhysics} Fully resolved physics parameters for inertia and boundary spring.
  */
-export declare function deriveBoundaryPhysics(elastic: number | undefined, transition?: {
+export declare const deriveBoundaryPhysics: (elastic: number | undefined, transition?: {
     bounceStiffness?: number;
     bounceDamping?: number;
     timeConstant?: number;
     restDelta?: number;
     restSpeed?: number;
-}): BoundaryPhysics;
+}) => BoundaryPhysics;

package/dist/utils/dragParams.js

@@ -13,7 +13,7 @@
  *   - `timeConstant` is expressed in seconds and internally converted to milliseconds.
  * @returns {BoundaryPhysics} Fully resolved physics parameters for inertia and boundary spring.
  */
-export function deriveBoundaryPhysics(elastic, transition) {
+export const deriveBoundaryPhysics = (elastic, transition) => {
     const truthyElastic = typeof elastic === 'number' ? elastic > 0 : !!elastic;
     let bounceStiffness = truthyElastic ? 200 : 1_000_000;
     let bounceDamping = truthyElastic ? 40 : 10_000_000;
@@ -26,4 +26,4 @@ export function deriveBoundaryPhysics(elastic, transition) {
     const restDelta = transition?.restDelta ?? 1;
     const restSpeed = transition?.restSpeed ?? 10;
     return { timeConstantMs, restDelta, restSpeed, bounceStiffness, bounceDamping };
-}
+};

package/dist/utils/inertia.d.ts

@@ -7,14 +7,21 @@
  *
  * This module is SSR-safe and holds no references to the DOM or timers.
  */
+/** Current position and velocity on a single axis. */
 export type AxisState = {
     value: number;
     velocity: number;
 };
+/** Min/max boundary pair for clamping an axis. */
 export type Bounds = {
     min: number;
     max: number;
 };
+/**
+ * Parameters controlling the inertia decay and boundary spring phases.
+ *
+ * @see deriveBoundaryPhysics
+ */
 export type InertiaHandoffOptions = {
     timeConstantMs: number;
     restDelta: number;
@@ -22,6 +29,7 @@ export type InertiaHandoffOptions = {
     bounceStiffness: number;
     bounceDamping: number;
 };
+/** Value returned by each step of the inertia/spring simulation. */
 export type StepResult = {
     value: number;
     done: boolean;
@@ -29,5 +37,20 @@ export type StepResult = {
 /**
  * Create a stepper that yields a value at each elapsed time. Handoff from
  * inertia to spring when crossing the bounds.
+ *
+ * @param initial Starting position and velocity on the axis.
+ * @param bounds Min/max boundaries for the axis.
+ * @param opts Physics parameters for decay and boundary spring.
+ * @returns A function that accepts elapsed time in ms and returns the current `StepResult`.
+ *
+ * @example
+ * ```ts
+ * const step = createInertiaToBoundary(
+ *     { value: 50, velocity: 200 },
+ *     { min: 0, max: 300 },
+ *     { timeConstantMs: 350, restDelta: 0.5, restSpeed: 10, bounceStiffness: 500, bounceDamping: 25 }
+ * )
+ * const { value, done } = step(16) // advance 16 ms
+ * ```
  */
-export declare function createInertiaToBoundary(initial: AxisState, bounds: Bounds, opts: InertiaHandoffOptions): (tMs: number) => StepResult;
+export declare const createInertiaToBoundary: (initial: AxisState, bounds: Bounds, opts: InertiaHandoffOptions) => ((tMs: number) => StepResult);

package/dist/utils/inertia.js

@@ -51,8 +51,23 @@ const solveCrossTimeMs = (x0, v0, tauMs, boundary) => {
 /**
  * Create a stepper that yields a value at each elapsed time. Handoff from
  * inertia to spring when crossing the bounds.
+ *
+ * @param initial Starting position and velocity on the axis.
+ * @param bounds Min/max boundaries for the axis.
+ * @param opts Physics parameters for decay and boundary spring.
+ * @returns A function that accepts elapsed time in ms and returns the current `StepResult`.
+ *
+ * @example
+ * ```ts
+ * const step = createInertiaToBoundary(
+ *     { value: 50, velocity: 200 },
+ *     { min: 0, max: 300 },
+ *     { timeConstantMs: 350, restDelta: 0.5, restSpeed: 10, bounceStiffness: 500, bounceDamping: 25 }
+ * )
+ * const { value, done } = step(16) // advance 16 ms
+ * ```
  */
-export function createInertiaToBoundary(initial, bounds, opts) {
+export const createInertiaToBoundary = (initial, bounds, opts) => {
     const min = bounds.min;
     const max = bounds.max;
     const tauMs = Math.max(1, opts.timeConstantMs);
@@ -156,4 +171,4 @@ export function createInertiaToBoundary(initial, bounds, opts) {
         const settled = boundaryTarget != null ? springX : x;
         return { value: Math.min(max, Math.max(min, settled)), done: true };
     };
-}
+};

package/dist/utils/layoutId.d.ts

@@ -19,6 +19,15 @@ export type LayoutIdRegistry = {
 export declare const layoutIdRegistry: LayoutIdRegistry;
 /**
  * Get the global layoutId registry.
+ *
+ * @returns The singleton `LayoutIdRegistry` instance.
+ *
+ * @example
+ * ```ts
+ * const registry = getLayoutIdRegistry()
+ * registry.snapshot('hero', element.getBoundingClientRect())
+ * const entry = registry.consume('hero') // one-shot: returns and deletes
+ * ```
  */
-export declare function getLayoutIdRegistry(): LayoutIdRegistry;
+export declare const getLayoutIdRegistry: () => LayoutIdRegistry;
 export {};

package/dist/utils/layoutId.js

@@ -17,7 +17,16 @@ export const layoutIdRegistry = {
 };
 /**
  * Get the global layoutId registry.
+ *
+ * @returns The singleton `LayoutIdRegistry` instance.
+ *
+ * @example
+ * ```ts
+ * const registry = getLayoutIdRegistry()
+ * registry.snapshot('hero', element.getBoundingClientRect())
+ * const entry = registry.consume('hero') // one-shot: returns and deletes
+ * ```
  */
-export function getLayoutIdRegistry() {
+export const getLayoutIdRegistry = () => {
     return layoutIdRegistry;
-}
+};

package/dist/utils/log.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Detect whether the current page is running inside a Playwright test.
+ *
+ * @returns `true` when the URL contains the `@isPlaywright=true` query param.
+ */
 export declare const isPlaywrightEnv: () => boolean;
+/**
+ * Log to the console only in DEV mode inside a Playwright environment.
+ *
+ * @param args Values forwarded to `console.log`.
+ */
 export declare const pwLog: (...args: unknown[]) => void;
+/**
+ * Warn to the console only in DEV mode inside a Playwright environment.
+ *
+ * @param args Values forwarded to `console.warn`.
+ */
 export declare const pwWarn: (...args: unknown[]) => void;

package/dist/utils/log.js

@@ -5,11 +5,21 @@
  * In production builds (npm package), these are noops to reduce bundle size.
  */
 import { DEV } from 'esm-env';
+/**
+ * Detect whether the current page is running inside a Playwright test.
+ *
+ * @returns `true` when the URL contains the `@isPlaywright=true` query param.
+ */
 export const isPlaywrightEnv = () => {
     if (typeof window === 'undefined')
         return false;
     return window.location.search.includes('@isPlaywright=true');
 };
+/**
+ * Log to the console only in DEV mode inside a Playwright environment.
+ *
+ * @param args Values forwarded to `console.log`.
+ */
 export const pwLog = (...args) => {
     if (!DEV)
         return;
@@ -17,6 +27,11 @@ export const pwLog = (...args) => {
         return;
     console.log(...args);
 };
+/**
+ * Warn to the console only in DEV mode inside a Playwright environment.
+ *
+ * @param args Values forwarded to `console.warn`.
+ */
 export const pwWarn = (...args) => {
     if (!DEV)
         return;

package/dist/utils/motionValueEvent.d.ts

@@ -0,0 +1,29 @@
+import type { Readable } from 'svelte/store';
+/**
+ * Subscribes to a Svelte store and fires a callback on every *change*,
+ * skipping the initial synchronous emission that Svelte stores produce
+ * on subscribe.
+ *
+ * Returns an unsubscribe function. Use inside `$effect` or `onDestroy`
+ * for automatic cleanup.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useMotionValueEvent, useSpring } from '@humanspeak/svelte-motion'
+ *   import { onDestroy } from 'svelte'
+ *
+ *   const x = useSpring(0)
+ *   const unsub = useMotionValueEvent(x, 'change', (latest) => {
+ *     console.log('x changed to', latest)
+ *   })
+ *   onDestroy(unsub)
+ * </script>
+ * ```
+ *
+ * @param store A readable Svelte store to observe.
+ * @param event The event type — currently only `'change'` is supported.
+ * @param callback Invoked with the latest value on each change after the initial emission.
+ * @returns An unsubscribe function.
+ */
+export declare const useMotionValueEvent: <T>(store: Readable<T>, event: "change", callback: (latest: T) => void) => (() => void);

package/dist/utils/motionValueEvent.js

@@ -0,0 +1,38 @@
+/**
+ * Subscribes to a Svelte store and fires a callback on every *change*,
+ * skipping the initial synchronous emission that Svelte stores produce
+ * on subscribe.
+ *
+ * Returns an unsubscribe function. Use inside `$effect` or `onDestroy`
+ * for automatic cleanup.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useMotionValueEvent, useSpring } from '@humanspeak/svelte-motion'
+ *   import { onDestroy } from 'svelte'
+ *
+ *   const x = useSpring(0)
+ *   const unsub = useMotionValueEvent(x, 'change', (latest) => {
+ *     console.log('x changed to', latest)
+ *   })
+ *   onDestroy(unsub)
+ * </script>
+ * ```
+ *
+ * @param store A readable Svelte store to observe.
+ * @param event The event type — currently only `'change'` is supported.
+ * @param callback Invoked with the latest value on each change after the initial emission.
+ * @returns An unsubscribe function.
+ */
+export const useMotionValueEvent = (store, event, callback) => {
+    let initialized = false;
+    const unsub = store.subscribe((value) => {
+        if (!initialized) {
+            initialized = true;
+            return;
+        }
+        callback(value);
+    });
+    return unsub;
+};

package/dist/utils/presence.d.ts

@@ -54,23 +54,23 @@ export type AnimatePresenceContext = {
  * @param context Optional callbacks, for example `onExitComplete`.
  * @returns A presence context with register/update/unregister APIs.
  */
-export declare function createAnimatePresenceContext(context: {
+export declare const createAnimatePresenceContext: (context: {
     initial?: boolean;
     mode?: AnimatePresenceMode;
     onExitComplete?: () => void;
-}): AnimatePresenceContext;
+}) => AnimatePresenceContext;
 /**
  * Get the current `AnimatePresence` context from Svelte component context.
  *
  * Note: Trivial wrapper - ignored for coverage.
  */
-export declare function getAnimatePresenceContext(): AnimatePresenceContext | undefined;
+export declare const getAnimatePresenceContext: () => AnimatePresenceContext | undefined;
 /**
  * Set the `AnimatePresence` context into Svelte component context.
  *
  * Note: Trivial wrapper - ignored for coverage.
  */
-export declare function setAnimatePresenceContext(context: AnimatePresenceContext): void;
+export declare const setAnimatePresenceContext: (context: AnimatePresenceContext) => void;
 /**
  * Get the current presence depth from Svelte component context.
  *
@@ -127,4 +127,4 @@ export declare const setPresenceDepth: (depth: number) => void;
  * @param exit The exit keyframes definition.
  * @param mergedTransition The element's merged transition for precedence.
  */
-export declare function usePresence(key: string, element: HTMLElement | null, exit: MotionExit, mergedTransition?: MotionTransition): void;
+export declare const usePresence: (key: string, element: HTMLElement | null, exit: MotionExit, mergedTransition?: MotionTransition) => void;

package/dist/utils/presence.js

@@ -51,7 +51,7 @@ const resetTransforms = (element) => {
  * @param context Optional callbacks, for example `onExitComplete`.
  * @returns A presence context with register/update/unregister APIs.
  */
-export function createAnimatePresenceContext(context) {
+export const createAnimatePresenceContext = (context) => {
     // Default initial to true (animate on first mount) unless explicitly false
     const initial = context.initial !== false;
     // Default mode to 'sync' if not specified
@@ -466,25 +466,25 @@ export function createAnimatePresenceContext(context) {
         updateChildState,
         unregisterChild
     };
-}
+};
 /**
  * Get the current `AnimatePresence` context from Svelte component context.
  *
  * Note: Trivial wrapper - ignored for coverage.
  */
 /* c8 ignore next 3 */
-export function getAnimatePresenceContext() {
+export const getAnimatePresenceContext = () => {
     return getContext(ANIMATE_PRESENCE_CONTEXT);
-}
+};
 /**
  * Set the `AnimatePresence` context into Svelte component context.
  *
  * Note: Trivial wrapper - ignored for coverage.
  */
 /* c8 ignore next 3 */
-export function setAnimatePresenceContext(context) {
+export const setAnimatePresenceContext = (context) => {
     setContext(ANIMATE_PRESENCE_CONTEXT, context);
-}
+};
 /**
  * Get the current presence depth from Svelte component context.
  *
@@ -546,7 +546,7 @@ export const setPresenceDepth = (depth) => {
  * @param exit The exit keyframes definition.
  * @param mergedTransition The element's merged transition for precedence.
  */
-export function usePresence(key, element, exit, mergedTransition) {
+export const usePresence = (key, element, exit, mergedTransition) => {
     const context = getAnimatePresenceContext();
     pwLog('[presence] usePresence called', {
         key,
@@ -567,5 +567,5 @@ export function usePresence(key, element, exit, mergedTransition) {
             reason: !element ? 'no element' : !context ? 'no context' : 'no exit'
         });
     }
-}
+};
 /* c8 ignore end */

package/dist/utils/scroll.d.ts

@@ -0,0 +1,68 @@
+import { type Readable } from 'svelte/store';
+/**
+ * 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]`.
+ */
+type ScrollOffset = Array<[number | string, number | string]> | string[];
+/**
+ * An element reference — either an element directly or a getter function
+ * that returns one (useful with Svelte's `bind:this` where the element
+ * isn't available until after mount).
+ */
+type ElementOrGetter = HTMLElement | (() => HTMLElement | undefined);
+/**
+ * Options accepted by `useScroll`.
+ */
+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 `useScroll` — four readable Svelte stores representing
+ * scroll position and normalised progress for both axes.
+ */
+type UseScrollReturn = {
+    scrollX: Readable<number>;
+    scrollY: Readable<number>;
+    scrollXProgress: Readable<number>;
+    scrollYProgress: Readable<number>;
+};
+/**
+ * Creates scroll-linked Svelte stores for building scroll-driven animations
+ * such as progress indicators and parallax effects.
+ *
+ * When the returned stores are used with `opacity` / `transform` CSS properties
+ * the animations can be hardware accelerated by the browser.
+ *
+ * SSR-safe: returns static `readable(0)` stores on the server.
+ *
+ * `container` and `target` accept either an `HTMLElement` directly or a
+ * getter function `() => HTMLElement | undefined`. This is useful with
+ * Svelte's `bind:this` where the element isn't available until after mount.
+ * When a getter is provided, element resolution is deferred until the
+ * first subscriber arrives, and if the element isn't available yet the
+ * stores poll on each animation frame until it is.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useScroll, useSpring } from '@humanspeak/svelte-motion'
+ *
+ *   const { scrollYProgress } = useScroll()
+ *   const scaleX = useSpring(scrollYProgress)
+ * </script>
+ *
+ * <div style="transform: scaleX({$scaleX}); transform-origin: left;" />
+ * ```
+ *
+ * @param options Optional scroll tracking configuration.
+ * @returns An object with `scrollX`, `scrollY`, `scrollXProgress`, and `scrollYProgress` stores.
+ */
+export declare const useScroll: (options?: UseScrollOptions) => UseScrollReturn;
+export {};

package/dist/utils/scroll.js

@@ -0,0 +1,119 @@
+import { scroll } from 'motion';
+import { readable, writable } from 'svelte/store';
+/**
+ * Resolves an element-or-getter to an HTMLElement (or undefined).
+ */
+const resolveElement = (ref) => {
+    if (!ref)
+        return undefined;
+    return typeof ref === 'function' ? ref() : ref;
+};
+/**
+ * Creates scroll-linked Svelte stores for building scroll-driven animations
+ * such as progress indicators and parallax effects.
+ *
+ * When the returned stores are used with `opacity` / `transform` CSS properties
+ * the animations can be hardware accelerated by the browser.
+ *
+ * SSR-safe: returns static `readable(0)` stores on the server.
+ *
+ * `container` and `target` accept either an `HTMLElement` directly or a
+ * getter function `() => HTMLElement | undefined`. This is useful with
+ * Svelte's `bind:this` where the element isn't available until after mount.
+ * When a getter is provided, element resolution is deferred until the
+ * first subscriber arrives, and if the element isn't available yet the
+ * stores poll on each animation frame until it is.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useScroll, useSpring } from '@humanspeak/svelte-motion'
+ *
+ *   const { scrollYProgress } = useScroll()
+ *   const scaleX = useSpring(scrollYProgress)
+ * </script>
+ *
+ * <div style="transform: scaleX({$scaleX}); transform-origin: left;" />
+ * ```
+ *
+ * @param options Optional scroll tracking configuration.
+ * @returns An object with `scrollX`, `scrollY`, `scrollXProgress`, and `scrollYProgress` stores.
+ */
+export const useScroll = (options) => {
+    if (typeof window === 'undefined') {
+        return {
+            scrollX: readable(0),
+            scrollY: readable(0),
+            scrollXProgress: readable(0),
+            scrollYProgress: readable(0)
+        };
+    }
+    const stores = {
+        scrollX: writable(0),
+        scrollY: writable(0),
+        scrollXProgress: writable(0),
+        scrollYProgress: writable(0)
+    };
+    let cleanup;
+    let pollRaf = 0;
+    let subscriberCount = 0;
+    const attach = () => {
+        if (cleanup)
+            return;
+        // Resolve elements — they may not be available yet when using getters
+        const container = resolveElement(options?.container);
+        const target = resolveElement(options?.target);
+        // If a getter was provided but returned undefined, the element isn't
+        // mounted yet. Poll on the next frame until it appears.
+        const needsContainer = options?.container && !container;
+        const needsTarget = options?.target && !target;
+        if (needsContainer || needsTarget) {
+            if (!pollRaf) {
+                pollRaf = requestAnimationFrame(() => {
+                    pollRaf = 0;
+                    attach();
+                });
+            }
+            return;
+        }
+        cleanup = scroll((_progress, info) => {
+            stores.scrollX.set(info.x.current);
+            stores.scrollY.set(info.y.current);
+            stores.scrollXProgress.set(info.x.progress);
+            stores.scrollYProgress.set(info.y.progress);
+        }, {
+            container,
+            target,
+            offset: options?.offset,
+            axis: options?.axis
+        });
+    };
+    const detach = () => {
+        if (subscriberCount <= 0) {
+            if (pollRaf) {
+                cancelAnimationFrame(pollRaf);
+                pollRaf = 0;
+            }
+            if (cleanup) {
+                cleanup();
+                cleanup = undefined;
+            }
+        }
+    };
+    const make = (key) => readable(0, (set) => {
+        subscriberCount++;
+        const unsub = stores[key].subscribe(set);
+        attach();
+        return () => {
+            unsub();
+            subscriberCount--;
+            detach();
+        };
+    });
+    return {
+        scrollX: make('scrollX'),
+        scrollY: make('scrollY'),
+        scrollXProgress: make('scrollXProgress'),
+        scrollYProgress: make('scrollYProgress')
+    };
+};

package/dist/utils/testing.d.ts

@@ -1 +1,12 @@
+/**
+ * Return a promise that resolves after the given number of milliseconds.
+ *
+ * @param ms Delay in milliseconds.
+ * @returns A promise that resolves after the delay.
+ *
+ * @example
+ * ```ts
+ * await sleep(100) // pause for 100 ms
+ * ```
+ */
 export declare const sleep: (ms: number) => Promise<unknown>;

package/dist/utils/testing.js

@@ -1 +1,12 @@
+/**
+ * Return a promise that resolves after the given number of milliseconds.
+ *
+ * @param ms Delay in milliseconds.
+ * @returns A promise that resolves after the delay.
+ *
+ * @example
+ * ```ts
+ * await sleep(100) // pause for 100 ms
+ * ```
+ */
 export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/dist/utils/transform.d.ts

@@ -6,13 +6,30 @@ export type TransformValues = Partial<{
     scaleY: number;
     rotate: number;
 }>;
-/** Build a CSS transform string from numeric values (no matrices). */
-export declare function buildTransform(values: TransformValues): string;
-/** Lightweight safety check for transform magnitudes and NaN values. */
-export declare function isSafeTransform(values: TransformValues, opts?: {
+/**
+ * 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.
+ */
+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.
+ */
+export declare const isSafeTransform: (values: TransformValues, opts?: {
     maxScale?: number;
-}): boolean;
-export declare function parseMatrixScale(matrix: string | null | undefined): number | null;
+}) => 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.
+ */
+export declare const parseMatrixScale: (matrix: string | null | undefined) => number | null;
 import { type Readable } from 'svelte/store';
 /**
  * Options for range-mapping transform.

package/dist/utils/transform.js

@@ -7,8 +7,13 @@ const DEFAULTS = {
     scaleY: 1,
     rotate: 0
 };
-/** Build a CSS transform string from numeric values (no matrices). */
-export function buildTransform(values) {
+/**
+ * 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.
+ */
+export const buildTransform = (values) => {
     const v = { ...DEFAULTS, ...values };
     // If explicit per-axis scales provided, use them; otherwise use uniform scale
     const useAxes = values.scaleX !== undefined || values.scaleY !== undefined;
@@ -26,9 +31,15 @@ export function buildTransform(values) {
         parts.push(`scale(${round(v.scale)})`);
     }
     return parts.join(' ').trim();
-}
-/** Lightweight safety check for transform magnitudes and NaN values. */
-export function isSafeTransform(values, opts) {
+};
+/**
+ * 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.
+ */
+export const isSafeTransform = (values, opts) => {
     const maxScale = opts?.maxScale ?? 8;
     const entries = [
         ['scale', values.scale],
@@ -44,8 +55,14 @@ export function isSafeTransform(values, opts) {
             return false;
     }
     return true;
-}
-export function parseMatrixScale(matrix) {
+};
+/**
+ * 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.
+ */
+export const parseMatrixScale = (matrix) => {
     if (!matrix || matrix === 'none')
         return null;
     const m = matrix.match(/matrix\(([^)]+)\)/);
@@ -53,11 +70,16 @@ export function parseMatrixScale(matrix) {
         return null;
     const [a] = m[1].split(',').map((s) => parseFloat(s.trim()));
     return Number.isFinite(a) ? a : null;
-}
-function round(n) {
-    // avoid excessive precision in strings
+};
+/**
+ * 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;
-}
+};
 import { derived, readable } from 'svelte/store';
 /**
  * Creates a linear mixer function for numeric values.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "A lightweight animation library for Svelte 5 that provides smooth, hardware-accelerated animations. Features include spring physics, custom easing, and fluid transitions. Built on top of the motion library, it offers a simple API for creating complex animations with minimal code. Perfect for interactive UIs, micro-interactions, and engaging user experiences.",
   "keywords": [
     "svelte",
@@ -53,8 +53,8 @@
     }
   },
   "dependencies": {
-    "motion": "^12.34.2",
-    "motion-dom": "^12.34.2"
+    "motion": "^12.34.3",
+    "motion-dom": "^12.34.3"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
@@ -62,7 +62,7 @@
     "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.58.2",
     "@sveltejs/adapter-auto": "^7.0.1",
-    "@sveltejs/kit": "^2.52.2",
+    "@sveltejs/kit": "^2.53.0",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@tailwindcss/aspect-ratio": "^0.4.2",
@@ -75,7 +75,7 @@
     "@types/node": "^25.3.0",
     "@vitest/coverage-v8": "^4.0.18",
     "concurrently": "^9.2.1",
-    "eslint": "^10.0.0",
+    "eslint": "^10.0.1",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-import": "2.32.0",
     "eslint-plugin-svelte": "3.15.0",
@@ -93,8 +93,8 @@
     "prettier-plugin-tailwindcss": "^0.7.2",
     "publint": "^0.3.17",
     "runed": "0.37.1",
-    "svelte": "^5.53.0",
-    "svelte-check": "^4.4.1",
+    "svelte": "^5.53.2",
+    "svelte-check": "^4.4.3",
     "svg-tags": "^1.0.0",
     "tailwind-merge": "^3.5.0",
     "tailwind-variants": "^3.2.2",