@humanspeak/svelte-motion 0.6.0 → 0.6.1

package/dist/html/_MotionContainer.svelte

@@ -14,6 +14,8 @@
     import type {
         MotionProps,
         MotionTransition,
+        AnimationControlsDefinition,
+        AnimationControlsSubscriber,
         DragAxis,
         DragConstraints,
         DragControls,
@@ -33,6 +35,7 @@
     import { onDestroy, untrack, type Snippet } from 'svelte'
     import { VOID_TAGS } from '../utils/constants'
     import { mergeTransitions, animateWithLifecycle } from '../utils/animation'
+    import { isAnimationControls } from '../utils/animationControls.svelte'
     import { attachWhileTap } from '../utils/interaction'
     import { attachWhileHover, computeHoverBaseline, splitHoverDefinition } from '../utils/hover'
     import { attachWhileFocus } from '../utils/focus'
@@ -60,6 +63,7 @@
     import { ProjectionNode } from '../utils/projection'
     import { getProjectionParent, setProjectionParent } from '../components/projection.context'
     import { MotionDomProjectionAdapter } from '../utils/motionDomProjection'
+    import { SvelteSet } from 'svelte/reactivity'
     import {
         getMotionDomProjectionParent,
         setMotionDomProjectionParent
@@ -69,6 +73,7 @@
         resolveAnimate,
         resolveExit,
         resolveWhile,
+        resolveVariantList,
         resolveRestingValues
     } from '../utils/variants'
     import {
@@ -282,6 +287,11 @@
         width: rect.width,
         height: rect.height
     })
+    const hasRectChanged = (previous: RectLike, next: RectLike): boolean =>
+        Math.abs(previous.left - next.left) > 0.5 ||
+        Math.abs(previous.top - next.top) > 0.5 ||
+        Math.abs(previous.width - next.width) > 0.5 ||
+        Math.abs(previous.height - next.height) > 0.5
     const isViewportOffscreen = (rect: DOMRect): boolean =>
         rect.bottom <= 0 ||
         rect.right <= 0 ||
@@ -463,6 +473,8 @@
 
     // Variant inheritance and resolution
     const parentVariantStore = getVariantContext()
+    const animateControls = $derived(isAnimationControls(animateProp) ? animateProp : undefined)
+    const declarativeAnimateProp = $derived(animateControls ? undefined : animateProp)
 
     // Get initial inherited variant synchronously
     let initialInheritedVariant: string | undefined = undefined
@@ -472,8 +484,8 @@
 
     // Create store with initial value so children can inherit immediately
     const initialVariantValue =
-        typeof animateProp === 'string'
-            ? animateProp
+        typeof declarativeAnimateProp === 'string'
+            ? declarativeAnimateProp
             : (variantsProp && initialInheritedVariant) || undefined
     const localVariantStore = writable<string | undefined>(initialVariantValue)
 
@@ -490,7 +502,8 @@
 
     // Use the initial value first, then switch to reactive once mounted
     const effectiveAnimate = $derived(
-        animateProp ?? (variantsProp ? (inheritedVariant ?? initialInheritedVariant) : undefined)
+        declarativeAnimateProp ??
+            (variantsProp ? (inheritedVariant ?? initialInheritedVariant) : undefined)
     )
 
     // Propagate initial={false} to children BEFORE setting variant context
@@ -547,7 +560,8 @@
 
     $effect(() => {
         if (!variantsProp) return localVariantStore.set(undefined)
-        if (typeof animateProp === 'string') return localVariantStore.set(animateProp)
+        if (typeof declarativeAnimateProp === 'string')
+            return localVariantStore.set(declarativeAnimateProp)
         if (typeof effectiveAnimate === 'string') return localVariantStore.set(effectiveAnimate)
         localVariantStore.set(undefined)
     })
@@ -692,6 +706,168 @@
             : null
     }
 
+    const getAnimationPromise = (control: unknown): Promise<unknown> => {
+        const finished = getFinishedPromise(control)
+        if (finished) return finished
+        if (control && typeof (control as Promise<unknown>).then === 'function') {
+            return control as Promise<unknown>
+        }
+        return Promise.resolve()
+    }
+
+    type StoppableAnimationControl = {
+        stop?: () => void
+        cancel?: () => void
+    }
+
+    const activeAnimationControls = new SvelteSet<StoppableAnimationControl>()
+    let animationControlsGeneration = 0
+    let animationControlsHasReceivedCommand = false
+
+    const isStoppableAnimationControl = (control: unknown): control is StoppableAnimationControl =>
+        !!control &&
+        typeof control === 'object' &&
+        (typeof (control as StoppableAnimationControl).stop === 'function' ||
+            typeof (control as StoppableAnimationControl).cancel === 'function')
+
+    const trackAnimationControlsControl = (control: unknown): Promise<unknown> => {
+        const promise = getAnimationPromise(control)
+        if (isStoppableAnimationControl(control)) {
+            activeAnimationControls.add(control)
+            promise.then(
+                () => activeAnimationControls.delete(control),
+                () => activeAnimationControls.delete(control)
+            )
+        }
+        return promise
+    }
+
+    const resolveAnimationControlsDefinition = (
+        definition: AnimationControlsDefinition
+    ): DOMKeyframesDefinition | undefined => {
+        const resolvedDefinition =
+            typeof definition === 'function' ? definition(effectiveCustom) : definition
+        if (typeof resolvedDefinition === 'string' || Array.isArray(resolvedDefinition)) {
+            return resolveVariantList(variantsProp, resolvedDefinition, effectiveCustom)
+        }
+        return resolvedDefinition
+    }
+
+    const applyAnimationControlsTarget = (definition: AnimationControlsDefinition) => {
+        if (!element) return
+        const resolved = resolveAnimationControlsDefinition(definition)
+        if (!resolved) return
+
+        animationControlsHasReceivedCommand = true
+        const target = { ...(resolved as Record<string, unknown>) } as Record<string, unknown> & {
+            transition?: AnimationOptions
+            transitionEnd?: Record<string, unknown>
+        }
+        const transitionEnd = target.transitionEnd
+        delete target.transition
+        delete target.transitionEnd
+        const finalTarget = resolveRestingValues({
+            ...target,
+            ...(transitionEnd ?? {})
+        } as DOMKeyframesDefinition) as Record<string, unknown> | undefined
+        if (!finalTarget) return
+
+        const transformedTarget = transformSVGPathProperties(element, finalTarget) as Record<
+            string,
+            unknown
+        >
+        animate(element, transformedTarget as DOMKeyframesDefinition, { duration: 0 })
+        element.setAttribute(
+            'style',
+            mergeInlineStyles(element.getAttribute('style') ?? '', undefined, transformedTarget)
+        )
+        enterAnimationSettled = true
+    }
+
+    const stopAnimationControlsAnimations = () => {
+        animationControlsHasReceivedCommand = true
+        animationControlsGeneration += 1
+
+        for (const control of activeAnimationControls) {
+            if (typeof control.stop === 'function') {
+                control.stop()
+            } else {
+                control.cancel?.()
+            }
+        }
+        activeAnimationControls.clear()
+
+        if (!element) return
+        if (typeof element.getAnimations !== 'function') return
+        for (const animation of element.getAnimations()) {
+            try {
+                animation.commitStyles?.()
+            } catch {
+                // Ignore unsupported commitStyles cases.
+            }
+            animation.cancel()
+        }
+    }
+
+    const startAnimationControlsDefinition = async (
+        definition: AnimationControlsDefinition,
+        transitionOverride?: AnimationOptions
+    ): Promise<unknown> => {
+        if (!element) return
+        const resolved = resolveAnimationControlsDefinition(definition)
+        if (!resolved) return
+
+        animationControlsHasReceivedCommand = true
+        const filtered = filterReducedMotionKeyframes(
+            resolved as Record<string, unknown>,
+            reducedMotion
+        ) as Record<string, unknown> & {
+            transition?: AnimationOptions
+            transitionEnd?: Record<string, unknown>
+        }
+        const transition = filtered.transition
+        const target = { ...filtered }
+        delete target.transition
+        delete target.transitionEnd
+        const transitionAnimate: MotionTransition =
+            transitionOverride ?? mergeTransitions(mergedTransition ?? {}, transition ?? {})
+        const svgPathFinished =
+            isSVGPathElement(element) && hasSVGPathProperties(target)
+                ? animateSVGPathAttributes(element, target, transitionAnimate, true)
+                : []
+        const payload = transformSVGPathProperties(
+            element,
+            svgPathFinished.length > 0 ? stripSVGPathKeyframes(target) : target
+        ) as Record<string, unknown>
+
+        const controlsGeneration = ++animationControlsGeneration
+        enterAnimationSettled = false
+        onAnimationStartProp?.(definition as unknown as DOMKeyframesDefinition)
+
+        const promises: Promise<unknown>[] = [...svgPathFinished]
+        if (isNotEmpty(payload)) {
+            promises.push(
+                trackAnimationControlsControl(
+                    animate(
+                        element,
+                        payload as DOMKeyframesDefinition,
+                        transitionAnimate as AnimationOptions
+                    )
+                )
+            )
+        }
+
+        try {
+            await Promise.all(promises)
+        } catch (error) {
+            if (controlsGeneration !== animationControlsGeneration) return
+            throw error
+        }
+        if (controlsGeneration !== animationControlsGeneration) return
+        applyAnimationControlsTarget(definition)
+        onAnimationCompleteProp?.(definition as unknown as DOMKeyframesDefinition)
+    }
+
     /**
      * Animates SVG path drawing props via motion-dom's `svgEffect`, matching
      * upstream's attribute-based pathLength/pathSpacing/pathOffset behavior.
@@ -704,7 +880,8 @@
     const animateSVGPathAttributes = (
         path: SVGPathElement,
         keyframes: Record<string, unknown>,
-        transition: MotionTransition
+        transition: MotionTransition,
+        trackControl = false
     ): Promise<unknown>[] => {
         if (!hasSVGPathProperties(keyframes)) return []
 
@@ -733,7 +910,9 @@
                         : keyframes[key]) as never,
                     transition as unknown as AnimationOptions
                 )
-                return getFinishedPromise(control)
+                return trackControl
+                    ? trackAnimationControlsControl(control)
+                    : getFinishedPromise(control)
             })
             .filter((promise): promise is Promise<unknown> => promise !== null)
     }
@@ -831,9 +1010,13 @@
                 ? (resolveRestingValues(
                       animateKeyframes as DOMKeyframesDefinition | undefined
                   ) as unknown as Record<string, unknown>)
-                : isNotEmpty(initialKeyframes)
-                  ? undefined
-                  : (animateKeyframes as unknown as Record<string, unknown>)
+                : animateControls &&
+                    !animationControlsHasReceivedCommand &&
+                    isNotEmpty(initialKeyframes)
+                  ? (initialKeyframes as unknown as Record<string, unknown>)
+                  : isNotEmpty(initialKeyframes)
+                    ? undefined
+                    : (animateKeyframes as unknown as Record<string, unknown>)
         ),
         class: classProp
     })
@@ -1320,9 +1503,12 @@
                             // which shows up as a "pop" after the deferred animation completes.
                             pwLog('[motion] wait-unblocked: marking enter handled')
                             initialAnimationTriggered = true
-                            if (animateProp && typeof animateProp !== 'string') {
+                            if (
+                                declarativeAnimateProp &&
+                                typeof declarativeAnimateProp !== 'string'
+                            ) {
                                 objectAnimateRanOnMount = true
-                                lastAnimatePropJson = JSON.stringify(animateProp)
+                                lastAnimatePropJson = JSON.stringify(declarativeAnimateProp)
                             }
                             isLoaded = 'ready'
                         })
@@ -1360,8 +1546,8 @@
     let lastAnimatePropJson = $state<string | undefined>(undefined)
     let motionDomProjectionUpdatePending = false
     const currentAnimateKey = $derived(
-        typeof animateProp === 'string'
-            ? animateProp
+        typeof declarativeAnimateProp === 'string'
+            ? declarativeAnimateProp
             : typeof effectiveAnimate === 'string'
               ? effectiveAnimate
               : undefined
@@ -1372,6 +1558,7 @@
         motionDomProjection.updateOptions({
             layout: layoutProp,
             layoutId: scopedLayoutId,
+            layoutScroll: layoutScrollProp,
             transition: mergedTransition as never,
             style: styleProp
         })
@@ -1380,6 +1567,13 @@
     $effect(() => {
         if (!motionDomProjection) return
         if (!element) return
+        motionDomProjection.updateOptions({
+            layout: layoutProp,
+            layoutId: scopedLayoutId,
+            layoutScroll: layoutScrollProp,
+            transition: mergedTransition as never,
+            style: styleProp
+        })
         motionDomProjection.mount(element)
         return () => {
             motionDomProjection.unmount()
@@ -1423,10 +1617,18 @@
         if (previous) {
             const next = measureLayoutRect()
             if (next) {
-                const flipLayoutMode = layoutProp === 'position' ? 'position' : true
-                const transforms = computeFlipTransforms(previous, next, flipLayoutMode)
-                runFlipAnimation(element!, transforms, (mergedTransition ?? {}) as AnimationOptions)
-                lastRect = next
+                if (motionDomProjection) {
+                    lastRect = next
+                } else {
+                    const flipLayoutMode = layoutProp === 'position' ? 'position' : true
+                    const transforms = computeFlipTransforms(previous, next, flipLayoutMode)
+                    runFlipAnimation(
+                        element!,
+                        transforms,
+                        (mergedTransition ?? {}) as AnimationOptions
+                    )
+                    lastRect = next
+                }
             }
         }
         projection.didUpdate()
@@ -1469,14 +1671,20 @@
 
         let rafId: number | null = null
         let wasViewportOffscreenSinceLastLayout = false
+        let wasViewportScrolledSinceLastLayout = false
         const flipLayoutMode = layoutProp === 'position' ? 'position' : true
         motionDomProjection?.seedLayout()
         lastRect = measureLayoutRect()
         setCompositorHints(element!, true)
 
         const rememberOffscreenScroll = () => {
+            wasViewportScrolledSinceLastLayout = true
+            if (motionDomProjection?.isAnimating()) {
+                motionDomProjection.finishAnimation()
+            }
             if (isViewportOffscreen(element!.getBoundingClientRect())) {
                 wasViewportOffscreenSinceLastLayout = true
+                motionDomProjection?.finishAnimation()
             }
         }
 
@@ -1503,18 +1711,42 @@
                 return
             }
 
+            if (
+                wasViewportScrolledSinceLastLayout ||
+                wasViewportOffscreenSinceLastLayout ||
+                isViewportOffscreen(element!.getBoundingClientRect())
+            ) {
+                lastRect = measureLayoutRect()
+                motionDomProjection?.finishAnimation()
+                wasViewportScrolledSinceLastLayout = false
+                wasViewportOffscreenSinceLastLayout = false
+                return
+            }
+
             const nextBox = projection.commitLayoutChange()
+            let shouldCommitMotionDomLayout = false
             if (nextBox && lastRect) {
                 const next = boxToRectLike(nextBox)
-                const transforms = computeFlipTransforms(lastRect, next, flipLayoutMode)
-                runFlipAnimation(element!, transforms, (mergedTransition ?? {}) as AnimationOptions)
+                shouldCommitMotionDomLayout = hasRectChanged(lastRect, next)
+                if (!motionDomProjection) {
+                    const transforms = computeFlipTransforms(lastRect, next, flipLayoutMode)
+                    runFlipAnimation(
+                        element!,
+                        transforms,
+                        (mergedTransition ?? {}) as AnimationOptions
+                    )
+                }
                 lastRect = next
+                wasViewportScrolledSinceLastLayout = false
                 wasViewportOffscreenSinceLastLayout = false
             } else if (nextBox) {
                 lastRect = boxToRectLike(nextBox)
+                wasViewportScrolledSinceLastLayout = false
                 wasViewportOffscreenSinceLastLayout = false
             }
-            motionDomProjection?.commitObservedLayoutChange()
+            if (shouldCommitMotionDomLayout) {
+                motionDomProjection?.commitObservedLayoutChange()
+            }
         }
 
         const commitPresenceLayoutRelease = (event: Event) => {
@@ -1532,14 +1764,20 @@
             lastRect = next
             const shouldSkipLayoutAnimation =
                 detail?.viewportScrolledDuringHold ||
+                wasViewportScrolledSinceLastLayout ||
                 wasViewportOffscreenSinceLastLayout ||
                 isViewportOffscreen(viewportRect)
-            if (!shouldSkipLayoutAnimation) {
+            if (!shouldSkipLayoutAnimation && !motionDomProjection) {
                 const transforms = computeFlipTransforms(previous, next, flipLayoutMode)
                 runFlipAnimation(element!, transforms, (mergedTransition ?? {}) as AnimationOptions)
             }
+            wasViewportScrolledSinceLastLayout = false
             wasViewportOffscreenSinceLastLayout = false
-            motionDomProjection?.commitObservedLayoutChange()
+            if (!shouldSkipLayoutAnimation && hasRectChanged(previous, next)) {
+                motionDomProjection?.commitObservedLayoutChange()
+            } else if (shouldSkipLayoutAnimation) {
+                motionDomProjection?.finishAnimation()
+            }
         }
 
         const scheduleProjectionCommit = () => {
@@ -1581,6 +1819,7 @@
 
         const prev = layoutIdRegistry.consume(scopedLayoutId)
         if (!prev) return // First appearance, no animation needed
+        if (motionDomProjection) return
 
         const next = measureRect(element, resolveLayoutScrollAncestors())
         const transforms = computeFlipTransforms(prev.rect, next, true)
@@ -1690,6 +1929,22 @@
         )
     })
 
+    // Legacy animation controls (`animate={controls}`) mirror upstream's
+    // VisualElement subscription model with a small Svelte adapter. The
+    // controls own when animations start; this component only resolves
+    // variants/custom data and runs the resulting target on its element.
+    $effect(() => {
+        if (!(element && animateControls)) return
+
+        const subscriber: AnimationControlsSubscriber = {
+            start: startAnimationControlsDefinition,
+            set: applyAnimationControlsTarget,
+            stop: stopAnimationControlsAnimations
+        }
+
+        return animateControls.subscribe(subscriber)
+    })
+
     // Handle key prop changes inside AnimatePresence (simulates React's key-based remounting)
     // When key changes, run exit → initial → animate sequence on the same element
     $effect(() => {
@@ -1798,10 +2053,14 @@
     // Re-run animate when animateProp changes while ready
     $effect(() => {
         if (!(element && isLoaded === 'ready')) return
+        if (animateControls) return
         // Skip first run if we mounted with initial={false} AND the variant hasn't changed
         if (mountedWithInitialFalse) {
             // Only skip if the variant is the same as what we mounted with
-            if (typeof animateProp === 'string' && lastRanVariantKey === animateProp) {
+            if (
+                typeof declarativeAnimateProp === 'string' &&
+                lastRanVariantKey === declarativeAnimateProp
+            ) {
                 mountedWithInitialFalse = false
                 return
             }
@@ -1813,25 +2072,28 @@
             pwLog('[motion] effect: skipping, initial animation already triggered')
             initialAnimationTriggered = false
             // Also mark object animate as ran to prevent duplicate runs from effect re-triggers
-            if (animateProp && typeof animateProp !== 'string') {
+            if (declarativeAnimateProp && typeof declarativeAnimateProp !== 'string') {
                 objectAnimateRanOnMount = true
             }
             return
         }
-        if (typeof animateProp === 'string') {
+        if (typeof declarativeAnimateProp === 'string') {
             // Compare BOTH the variant key and the resolved keyframes JSON.
             // For static variants the JSON is constant per key; for
             // function-form variants the JSON changes when `custom`
             // changes, which we must treat as a new animation target.
             const resolvedJson = resolvedAnimate ? JSON.stringify(resolvedAnimate) : undefined
-            if (lastRanVariantKey !== animateProp || lastRanResolvedJson !== resolvedJson) {
-                lastRanVariantKey = animateProp
+            if (
+                lastRanVariantKey !== declarativeAnimateProp ||
+                lastRanResolvedJson !== resolvedJson
+            ) {
+                lastRanVariantKey = declarativeAnimateProp
                 lastRanResolvedJson = resolvedJson
                 runAnimation()
             }
-        } else if (animateProp) {
+        } else if (declarativeAnimateProp) {
             // Object animate props - detect if the prop actually changed
-            const currentJson = JSON.stringify(animateProp)
+            const currentJson = JSON.stringify(declarativeAnimateProp)
             const propChanged = lastAnimatePropJson !== currentJson
 
             // Reset flag if animate prop changed
@@ -1853,7 +2115,7 @@
     // Also run when inherited/effective variant changes
     $effect(() => {
         void resolvedAnimate
-        if (!(element && isLoaded === 'ready' && !animateProp && resolvedAnimate)) return
+        if (!(element && isLoaded === 'ready' && !declarativeAnimateProp && resolvedAnimate)) return
         // Skip first run if we mounted with initial={false} AND the variant hasn't changed
         if (mountedWithInitialFalse) {
             // Only skip if the variant is the same as what we mounted with
@@ -1914,9 +2176,9 @@
                     dataPath = 6
                     isLoaded = 'initial'
                     initialAnimationTriggered = true
-                    if (animateProp && typeof animateProp !== 'string') {
+                    if (declarativeAnimateProp && typeof declarativeAnimateProp !== 'string') {
                         objectAnimateRanOnMount = true
-                        lastAnimatePropJson = JSON.stringify(animateProp)
+                        lastAnimatePropJson = JSON.stringify(declarativeAnimateProp)
                     }
                     finishOptimizedAppearAnimation(optimizedAppearId)
                         .then(() => {
@@ -1980,8 +2242,8 @@
 
                     // Mark that we're triggering the initial animation to prevent duplicate runs
                     initialAnimationTriggered = true
-                    if (animateProp && typeof animateProp !== 'string') {
-                        lastAnimatePropJson = JSON.stringify(animateProp)
+                    if (declarativeAnimateProp && typeof declarativeAnimateProp !== 'string') {
+                        lastAnimatePropJson = JSON.stringify(declarativeAnimateProp)
                     }
 
                     // IMPORTANT: Start the animation BEFORE changing isLoaded.

package/dist/index.d.ts

@@ -12,9 +12,10 @@ export { motion } from './motion';
 export { animate, delay, hover, inView, press, resize, scroll, stagger, transform } from 'motion';
 export { anticipate, backIn, backInOut, backOut, circIn, circInOut, circOut, cubicBezier, easeIn, easeInOut, easeOut } from 'motion';
 export { clamp, distance, distance2D, interpolate, mix, pipe, progress, wrap } from 'motion';
-export type { DragAxis, DragConstraints, DragControls, DragInfo, DragTransition, MotionAnimate, MotionInitial, MotionOnDirectionLock, MotionOnDragTransitionEnd, MotionOnInViewEnd, MotionOnInViewStart, MotionOnProjectionUpdate, MotionTransition, MotionWhileDrag, MotionWhileFocus, MotionWhileHover, MotionWhileInView, MotionWhileTap, ProjectionUpdatePayload, ReducedMotionConfig, Variants } from './types';
+export type { AnimationControls, AnimationControlsDefinition, AnimationControlsSubscriber, DragAxis, DragConstraints, DragControls, DragInfo, DragTransition, MotionAnimate, MotionInitial, MotionOnDirectionLock, MotionOnDragTransitionEnd, MotionOnInViewEnd, MotionOnInViewStart, MotionOnProjectionUpdate, MotionTransition, MotionWhileDrag, MotionWhileFocus, MotionWhileHover, MotionWhileInView, MotionWhileTap, ProjectionUpdatePayload, ReducedMotionConfig, Variants } from './types';
 export { useAnimate } from './utils/animate.svelte';
 export type { AnimationScope } from './utils/animate.svelte';
+export { animationControls, isAnimationControls, useAnimation, useAnimationControls } from './utils/animationControls.svelte';
 export { useAnimationFrame } from './utils/animationFrame';
 export type { AugmentedMotionValue } from './utils/augmentMotionValue.svelte';
 export { useCycle } from './utils/cycle.svelte';

package/dist/index.js

@@ -15,6 +15,7 @@ export { anticipate, backIn, backInOut, backOut, circIn, circInOut, circOut, cub
 // Re-export utility functions
 export { clamp, distance, distance2D, interpolate, mix, pipe, progress, wrap } from 'motion';
 export { useAnimate } from './utils/animate.svelte';
+export { animationControls, isAnimationControls, useAnimation, useAnimationControls } from './utils/animationControls.svelte';
 export { useAnimationFrame } from './utils/animationFrame';
 export { useCycle } from './utils/cycle.svelte';
 export { createDragControls } from './utils/dragControls';

package/dist/types.d.ts

@@ -74,7 +74,91 @@ export type MotionInitial = DOMKeyframesDefinition | string | string[] | false |
  * <motion.div variants={myVariants} animate="visible" />
  * ```
  */
-export type MotionAnimate = DOMKeyframesDefinition | string | string[] | undefined;
+/**
+ * Definition accepted by legacy animation controls.
+ *
+ * Mirrors Motion's `AnimationDefinition`: a keyframes object, a variant
+ * label, an ordered list of variant labels, or a resolver function that
+ * receives `custom` data.
+ *
+ * @example
+ * ```ts
+ * controls.start('visible')
+ * controls.start(['visible', 'active'])
+ * controls.start({ opacity: 1, x: 0 })
+ * controls.start((custom) => ({ x: custom * 100 }))
+ * ```
+ */
+export type AnimationControlsDefinition = DOMKeyframesDefinition | string | string[] | ((custom: unknown) => DOMKeyframesDefinition | string);
+/**
+ * Internal subscriber shape used by {@link AnimationControls}.
+ *
+ * Motion's upstream controls subscribe VisualElements. Svelte Motion
+ * subscribes a lightweight adapter from each `motion.*` component.
+ */
+export type AnimationControlsSubscriber = {
+    /** Start an animation on the subscribed component. */
+    start: (definition: AnimationControlsDefinition, transitionOverride?: AnimationOptions) => Promise<unknown>;
+    /** Synchronously set final values on the subscribed component. */
+    set: (definition: AnimationControlsDefinition) => void;
+    /** Stop currently running animations on the subscribed component. */
+    stop: () => void;
+};
+/**
+ * Legacy imperative controls returned by {@link useAnimationControls}.
+ *
+ * Pass the object to `animate={controls}` on one or more `motion.*`
+ * components, then call `controls.start(...)`, `controls.set(...)`, or
+ * `controls.stop()` from events or effects.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { motion, useAnimationControls } from '@humanspeak/svelte-motion'
+ *
+ *   const controls = useAnimationControls()
+ * </script>
+ *
+ * <button onclick={() => controls.start('open')}>Open</button>
+ * <motion.div animate={controls} variants={{ open: { opacity: 1 } }} />
+ * ```
+ */
+export type AnimationControls = {
+    /**
+     * Subscribe a motion component adapter to these controls.
+     *
+     * @param subscriber Component adapter to animate.
+     * @returns Unsubscribe callback.
+     */
+    subscribe: (subscriber: AnimationControlsSubscriber) => () => void;
+    /**
+     * Start an animation on every subscribed component.
+     *
+     * @param definition Target keyframes, variant label(s), or resolver.
+     * @param transitionOverride Optional transition that overrides the
+     *   component/default transition for this run.
+     * @returns Promise resolving when all subscribed animations complete.
+     */
+    start: (definition: AnimationControlsDefinition, transitionOverride?: AnimationOptions) => Promise<unknown[]>;
+    /**
+     * Synchronously set every subscribed component to the target's final
+     * values.
+     *
+     * @param definition Target keyframes, variant label(s), or resolver.
+     */
+    set: (definition: AnimationControlsDefinition) => void;
+    /** Stop animations on every subscribed component. */
+    stop: () => void;
+    /**
+     * Mark controls as mounted and return cleanup.
+     *
+     * Called automatically by `useAnimationControls()`.
+     *
+     * @returns Cleanup that marks controls unmounted and stops subscribers.
+     */
+    mount: () => () => void;
+};
+export type MotionAnimate = DOMKeyframesDefinition | string | string[] | AnimationControls | undefined;
 /**
  * Exit animation properties for a motion component when unmounted.
  *

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

@@ -0,0 +1,63 @@
+import type { AnimationControls } from '../types.js';
+/**
+ * Returns true when a value looks like Motion's legacy animation controls.
+ *
+ * Upstream `motion-dom` treats any non-null object with a `start`
+ * function as animation controls. Matching that narrow check keeps
+ * `animate={controls}` detection compatible with Motion's public shape.
+ *
+ * @param value Value passed to `animate`.
+ * @returns Whether `value` is an animation controls object.
+ *
+ * @example
+ * ```ts
+ * const controls = useAnimationControls()
+ * isAnimationControls(controls) // true
+ * isAnimationControls({ opacity: 1 }) // false
+ * ```
+ */
+export declare const isAnimationControls: (value: unknown) => value is AnimationControls;
+/**
+ * Create legacy animation controls.
+ *
+ * This mirrors upstream Motion's `animationControls()`: controls collect
+ * subscribed motion components, guard `start`/`set` until mounted, fan out
+ * starts to every subscriber, and stop all subscribers on unmount.
+ *
+ * @returns Animation controls with `subscribe`, `start`, `set`, `stop`,
+ *   and `mount`.
+ *
+ * @example
+ * ```ts
+ * const controls = animationControls()
+ * const cleanup = controls.mount()
+ * await controls.start({ opacity: 1 })
+ * cleanup()
+ * ```
+ */
+export declare const animationControls: () => AnimationControls;
+/**
+ * Create imperative controls for one or more `motion.*` components.
+ *
+ * Pass the returned object to `animate={controls}`. Once mounted, call
+ * `controls.start(definition)`, `controls.set(definition)`, or
+ * `controls.stop()` to coordinate every subscribed component.
+ *
+ * @returns Mounted animation controls.
+ * @see https://motion.dev/docs/react-use-animation-controls
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { motion, useAnimationControls } from '@humanspeak/svelte-motion'
+ *
+ *   const controls = useAnimationControls()
+ * </script>
+ *
+ * <button onclick={() => controls.start({ scale: 1.2 })}>Pop</button>
+ * <motion.div animate={controls} />
+ * ```
+ */
+export declare const useAnimationControls: () => AnimationControls;
+/** Alias matching Motion's legacy `useAnimation` export. */
+export declare const useAnimation: () => AnimationControls;

package/dist/utils/animationControls.svelte.js

@@ -0,0 +1,111 @@
+import { SvelteSet } from 'svelte/reactivity';
+const mountedError = 'controls.start() should only be called after a component has mounted. Consider calling within a $effect.';
+const setMountedError = 'controls.set() should only be called after a component has mounted. Consider calling within a $effect.';
+/**
+ * Returns true when a value looks like Motion's legacy animation controls.
+ *
+ * Upstream `motion-dom` treats any non-null object with a `start`
+ * function as animation controls. Matching that narrow check keeps
+ * `animate={controls}` detection compatible with Motion's public shape.
+ *
+ * @param value Value passed to `animate`.
+ * @returns Whether `value` is an animation controls object.
+ *
+ * @example
+ * ```ts
+ * const controls = useAnimationControls()
+ * isAnimationControls(controls) // true
+ * isAnimationControls({ opacity: 1 }) // false
+ * ```
+ */
+export const isAnimationControls = (value) => {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof value.start === 'function');
+};
+/**
+ * Create legacy animation controls.
+ *
+ * This mirrors upstream Motion's `animationControls()`: controls collect
+ * subscribed motion components, guard `start`/`set` until mounted, fan out
+ * starts to every subscriber, and stop all subscribers on unmount.
+ *
+ * @returns Animation controls with `subscribe`, `start`, `set`, `stop`,
+ *   and `mount`.
+ *
+ * @example
+ * ```ts
+ * const controls = animationControls()
+ * const cleanup = controls.mount()
+ * await controls.start({ opacity: 1 })
+ * cleanup()
+ * ```
+ */
+export const animationControls = () => {
+    let hasMounted = false;
+    const subscribers = new SvelteSet();
+    const controls = {
+        subscribe(subscriber) {
+            subscribers.add(subscriber);
+            return () => {
+                subscribers.delete(subscriber);
+            };
+        },
+        start(definition, transitionOverride) {
+            if (!hasMounted) {
+                throw new Error(mountedError);
+            }
+            const animations = [];
+            subscribers.forEach((subscriber) => {
+                animations.push(subscriber.start(definition, transitionOverride));
+            });
+            return Promise.all(animations);
+        },
+        set(definition) {
+            if (!hasMounted) {
+                throw new Error(setMountedError);
+            }
+            subscribers.forEach((subscriber) => subscriber.set(definition));
+        },
+        stop() {
+            subscribers.forEach((subscriber) => subscriber.stop());
+        },
+        mount() {
+            hasMounted = true;
+            return () => {
+                hasMounted = false;
+                controls.stop();
+            };
+        }
+    };
+    return controls;
+};
+/**
+ * Create imperative controls for one or more `motion.*` components.
+ *
+ * Pass the returned object to `animate={controls}`. Once mounted, call
+ * `controls.start(definition)`, `controls.set(definition)`, or
+ * `controls.stop()` to coordinate every subscribed component.
+ *
+ * @returns Mounted animation controls.
+ * @see https://motion.dev/docs/react-use-animation-controls
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { motion, useAnimationControls } from '@humanspeak/svelte-motion'
+ *
+ *   const controls = useAnimationControls()
+ * </script>
+ *
+ * <button onclick={() => controls.start({ scale: 1.2 })}>Pop</button>
+ * <motion.div animate={controls} />
+ * ```
+ */
+export const useAnimationControls = () => {
+    const controls = animationControls();
+    $effect(() => controls.mount());
+    return controls;
+};
+/** Alias matching Motion's legacy `useAnimation` export. */
+export const useAnimation = useAnimationControls;

package/dist/utils/layout.js

@@ -1,6 +1,7 @@
 import { animate } from 'motion';
 const layoutSizeAnimationAttribute = 'data-layout-size-animation';
-const px = (value) => `${Math.max(0, value)}px`;
+const roundedPx = (value) => `${Math.max(0, Math.round(value))}px`;
+const mix = (from, to, progress) => from + (to - from) * progress;
 const isViewportOffscreen = (el) => {
     if (typeof window === 'undefined')
         return false;
@@ -26,23 +27,29 @@ const runBoxSizeAnimation = (el, transforms, transition) => {
         if (child.style.willChange === 'transform')
             child.style.willChange = '';
     }
-    el.style.width = px(prevWidth);
-    el.style.height = px(prevHeight);
+    el.style.width = roundedPx(prevWidth);
+    el.style.height = roundedPx(prevHeight);
     const sizedRect = el.getBoundingClientRect();
     const residualDx = nextRect.left + dx - sizedRect.left;
     const residualDy = nextRect.top + dy - sizedRect.top;
     const shouldTranslate = Math.abs(residualDx) > 0.5 || Math.abs(residualDy) > 0.5;
-    const keyframes = {
-        width: [px(prevWidth), px(nextRect.width)],
-        height: [px(prevHeight), px(nextRect.height)]
-    };
     if (shouldTranslate) {
-        keyframes.x = [residualDx, 0];
-        keyframes.y = [residualDy, 0];
         el.style.transformOrigin = '0 0';
-        el.style.transform = `translate(${residualDx}px, ${residualDy}px)`;
+        el.style.transform = `translate(${Math.round(residualDx)}px, ${Math.round(residualDy)}px)`;
     }
-    const animation = animate(el, keyframes, transition);
+    const writeBox = (progress) => {
+        el.style.width = roundedPx(mix(prevWidth, nextRect.width, progress));
+        el.style.height = roundedPx(mix(prevHeight, nextRect.height, progress));
+        if (shouldTranslate) {
+            const x = Math.round(mix(residualDx, 0, progress));
+            const y = Math.round(mix(residualDy, 0, progress));
+            el.style.transform = x === 0 && y === 0 ? '' : `translate(${x}px, ${y}px)`;
+        }
+    };
+    const animation = animate(0, 1, {
+        ...transition,
+        onUpdate: writeBox
+    });
     let removeScrollListener;
     let offscreenRaf = null;
     let cleanupRan = false;
@@ -278,7 +285,7 @@ export const observeLayoutChanges = (el, onChange) => {
     const attributeObserver = new MutationObserver(() => schedule());
     attributeObserver.observe(el, {
         attributes: true,
-        attributeFilter: ['class', 'style', 'data-presence-layout-hold']
+        attributeFilter: ['class', 'data-presence-layout-hold']
     });
     const childListObserver = new MutationObserver(() => schedule());
     childListObserver.observe(el, {

package/dist/utils/motionDomProjection.d.ts

@@ -16,6 +16,8 @@ export interface MotionDomProjectionUpdateOptions {
     layout?: LayoutOption;
     /** Shared layout id used by upstream projection matching. */
     layoutId?: string;
+    /** Tracks scroll on this element for descendant layout projection. */
+    layoutScroll?: boolean;
     /** Transition passed to the upstream layout animation builder. */
     transition?: Transition;
     /** Inline style props passed through to the visual element. */
@@ -29,6 +31,7 @@ export interface MotionDomProjectionUpdateOptions {
  * and `HTMLVisualElement` internals Framer Motion uses.
  */
 export declare class MotionDomProjectionAdapter {
+    private static adapters;
     readonly visualElement: ProjectionVisualElement;
     readonly projection: IProjectionNode<HTMLElement>;
     private element;
@@ -121,6 +124,32 @@ export declare class MotionDomProjectionAdapter {
      * ```
      */
     commitObservedLayoutChange(): void;
+    /**
+     * Finish any active upstream layout animation in this subtree.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.finishAnimation()
+     * ```
+     */
+    finishAnimation(): void;
+    /**
+     * Check whether this projection subtree has an active layout animation.
+     *
+     * @returns `true` when this projection subtree is currently animating.
+     *
+     * @example
+     * ```ts
+     * if (adapter.isAnimating()) adapter.finishAnimation()
+     * ```
+     */
+    isAnimating(): boolean;
+    private seedCachedSnapshotsForSubtree;
+    private finishAnimationForSubtree;
+    private isAnimatingSubtree;
+    private updatePathScroll;
     private refreshCachedLayout;
 }
 export {};

package/dist/utils/motionDomProjection.js

@@ -42,6 +42,7 @@ const animationTypeForLayout = (layout) => typeof layout === 'string' && animati
  * and `HTMLVisualElement` internals Framer Motion uses.
  */
 export class MotionDomProjectionAdapter {
+    static adapters = new WeakMap();
     visualElement;
     projection;
     element = null;
@@ -59,6 +60,7 @@ export class MotionDomProjectionAdapter {
         }, { allowProjection: true });
         this.projection = new HTMLProjectionNode(this.visualElement.latestValues, parent?.projection);
         this.visualElement.projection = this.projection;
+        MotionDomProjectionAdapter.adapters.set(this.projection, this);
     }
     /**
      * Update projection options from current Svelte props.
@@ -82,6 +84,7 @@ export class MotionDomProjectionAdapter {
         this.projection.setOptions({
             layout: options.layout,
             layoutId: options.layoutId,
+            layoutScroll: options.layoutScroll,
             animationType: animationTypeForLayout(options.layout),
             transition: options.transition,
             visualElement: this.visualElement
@@ -104,6 +107,7 @@ export class MotionDomProjectionAdapter {
         if (this.element)
             this.unmount();
         this.element = element;
+        MotionDomProjectionAdapter.adapters.set(this.projection, this);
         this.visualElement.mount(element);
         this.seedLayout();
     }
@@ -124,6 +128,7 @@ export class MotionDomProjectionAdapter {
         this.projection.scheduleCheckAfterUnmount();
         this.visualElement.unmount();
         visualElementStore.delete(element);
+        MotionDomProjectionAdapter.adapters.delete(this.projection);
         this.element = null;
         this.lastLayout = undefined;
     }
@@ -138,7 +143,7 @@ export class MotionDomProjectionAdapter {
      * ```
      */
     willUpdate() {
-        if (!this.element || !this.layoutId)
+        if (!this.element || !this.layout)
             return;
         this.projection.willUpdate();
     }
@@ -153,7 +158,7 @@ export class MotionDomProjectionAdapter {
      * ```
      */
     didUpdate() {
-        if (!this.element || !this.layoutId)
+        if (!this.element || !this.layout)
             return;
         this.projection.root?.didUpdate();
         this.refreshCachedLayout();
@@ -171,6 +176,7 @@ export class MotionDomProjectionAdapter {
     seedLayout() {
         if (!this.element)
             return;
+        this.updatePathScroll();
         this.projection.isLayoutDirty = true;
         this.projection.updateLayout();
         this.lastLayout = cloneMeasurements(this.projection.layout);
@@ -191,19 +197,80 @@ export class MotionDomProjectionAdapter {
      * ```
      */
     commitObservedLayoutChange() {
-        if (!this.element || !this.layoutId)
+        if (!this.element || !this.layout)
             return;
-        const snapshot = cloneMeasurements(this.lastLayout);
-        if (!snapshot) {
+        if (!this.lastLayout) {
             this.seedLayout();
             return;
         }
         this.projection.root?.startUpdate();
-        this.projection.snapshot = snapshot;
-        this.projection.isLayoutDirty = true;
+        this.seedCachedSnapshotsForSubtree(this.projection);
         this.projection.root?.didUpdate();
         this.refreshCachedLayout();
     }
+    /**
+     * Finish any active upstream layout animation in this subtree.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.finishAnimation()
+     * ```
+     */
+    finishAnimation() {
+        if (!this.element || !this.layout)
+            return;
+        this.finishAnimationForSubtree(this.projection);
+        this.seedLayout();
+    }
+    /**
+     * Check whether this projection subtree has an active layout animation.
+     *
+     * @returns `true` when this projection subtree is currently animating.
+     *
+     * @example
+     * ```ts
+     * if (adapter.isAnimating()) adapter.finishAnimation()
+     * ```
+     */
+    isAnimating() {
+        return this.isAnimatingSubtree(this.projection);
+    }
+    seedCachedSnapshotsForSubtree(projection) {
+        const adapter = MotionDomProjectionAdapter.adapters.get(projection);
+        const snapshot = cloneMeasurements(adapter?.lastLayout);
+        if (snapshot && projection.options.layout) {
+            projection.snapshot = snapshot;
+            projection.isLayoutDirty = true;
+        }
+        for (const child of projection.children) {
+            this.seedCachedSnapshotsForSubtree(child);
+        }
+    }
+    finishAnimationForSubtree(projection) {
+        projection.finishAnimation();
+        projection.targetDelta = projection.relativeTarget = projection.target = undefined;
+        projection.isProjectionDirty = true;
+        projection.scheduleRender();
+        for (const child of projection.children) {
+            this.finishAnimationForSubtree(child);
+        }
+    }
+    isAnimatingSubtree(projection) {
+        if (projection.currentAnimation)
+            return true;
+        for (const child of projection.children) {
+            if (this.isAnimatingSubtree(child))
+                return true;
+        }
+        return false;
+    }
+    updatePathScroll() {
+        for (const node of this.projection.path) {
+            node.updateScroll();
+        }
+    }
     refreshCachedLayout() {
         requestAnimationFrame(() => {
             this.lastLayout = cloneMeasurements(this.projection.layout);

package/package.json

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