@humanspeak/svelte-motion 0.5.4 → 0.6.1

package/dist/html/_MotionContainer.svelte

@@ -14,6 +14,8 @@
     import type {
         MotionProps,
         MotionTransition,
+        AnimationControlsDefinition,
+        AnimationControlsSubscriber,
         DragAxis,
         DragConstraints,
         DragControls,
@@ -28,10 +30,12 @@
     import { isNotEmpty } from '../utils/objects'
     import { sleep } from '../utils/testing'
     import { animate, type AnimationOptions, type DOMKeyframesDefinition } from 'motion'
+    import { motionValue, svgEffect, type MotionValue } from 'motion-dom'
     import { isPlaywrightEnv, pwLog } from '../utils/log'
     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'
@@ -58,11 +62,18 @@
     import { attachPan, type AttachPanCleanup } from '../utils/pan'
     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
+    } from '../components/motionDomProjection.context'
     import {
         resolveInitial,
         resolveAnimate,
         resolveExit,
         resolveWhile,
+        resolveVariantList,
         resolveRestingValues
     } from '../utils/variants'
     import {
@@ -77,9 +88,19 @@
     import {
         transformSVGPathProperties,
         computeNormalizedSVGInitialAttrs,
+        hasSVGPathProperties,
+        isSVGPathElement,
         isSVGTag,
         SVG_NAMESPACE
     } from '../utils/svg'
+    import {
+        createOptimizedAppearData,
+        createOptimizedAppearScript,
+        finishOptimizedAppearAnimation,
+        hasOptimizedAppearAnimation,
+        markMotionMounted,
+        optimizedAppearDataAttribute
+    } from '../utils/optimizedAppear'
     import { getLayoutIdRegistry } from '../utils/layoutId'
     import {
         getLayoutScrollContainerRef,
@@ -93,6 +114,8 @@
         [key: string]: unknown
     }
 
+    const componentHydrationId = $props.id()
+
     let {
         children,
         tag = 'div',
@@ -234,6 +257,18 @@
     })
     setProjectionParent(projection)
 
+    const motionDomProjectionParent =
+        typeof window !== 'undefined' ? getMotionDomProjectionParent() : null
+    const motionDomProjection =
+        typeof window !== 'undefined'
+            ? new MotionDomProjectionAdapter({
+                  parent: motionDomProjectionParent
+              })
+            : null
+    if (motionDomProjection) {
+        setMotionDomProjectionParent(motionDomProjection)
+    }
+
     // Convert a projection `Box` (ancestor chain reset to base, self
     // transform stripped, scroll containers compensated) to the
     // `RectLike` shape `computeFlipTransforms` consumes.
@@ -246,9 +281,25 @@
         width: box.x.max - box.x.min,
         height: box.y.max - box.y.min
     })
+    const domRectToRectLike = (rect: DOMRect): RectLike => ({
+        left: rect.left,
+        top: rect.top,
+        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 ||
+        rect.top >= window.innerHeight ||
+        rect.left >= window.innerWidth
 
     // Ancestor-transform-invariant layout measurement for seeding the
-    // FLIP effect's first rect.
+    // fallback FLIP effect's first rect.
     const measureLayoutRect = (): RectLike | null => {
         const box = projection.measure()
         return box ? boxToRectLike(box) : null
@@ -422,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
@@ -431,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)
 
@@ -449,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
@@ -506,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)
     })
@@ -551,6 +606,338 @@
             reducedMotion
         )
     )
+    const optimizedAppearId = $derived(
+        effectiveInitialProp !== false &&
+            isNotEmpty(initialKeyframes) &&
+            isNotEmpty(animateKeyframes)
+            ? `svelte-motion-${componentHydrationId}`
+            : undefined
+    )
+    const optimizedAppearEntries = $derived(
+        createOptimizedAppearData(
+            initialKeyframes as Record<string, unknown> | undefined,
+            animateKeyframes as Record<string, unknown> | undefined,
+            mergedTransition
+        )
+    )
+    const optimizedAppearScript = $derived(
+        createOptimizedAppearScript(optimizedAppearId, optimizedAppearEntries)
+    )
+    const renderedOptimizedAppearScript = $derived(
+        optimizedAppearScript && (typeof window === 'undefined' || !window.MotionIsMounted)
+            ? optimizedAppearScript
+            : ''
+    )
+    const applyAnimateRestingStyle = () => {
+        if (!element) return
+        const restingValues = resolveRestingValues(
+            animateKeyframes as DOMKeyframesDefinition | undefined
+        ) as Record<string, unknown> | undefined
+        if (!restingValues) return
+        element.setAttribute(
+            'style',
+            mergeInlineStyles(element.getAttribute('style') ?? '', undefined, restingValues)
+        )
+    }
+    const isJsdomRuntime = (): boolean =>
+        typeof navigator !== 'undefined' && /jsdom/i.test(navigator.userAgent)
+    const getTransitionFallbackMs = (transition: AnimationOptions | undefined): number => {
+        const duration = typeof transition?.duration === 'number' ? transition.duration : 0
+        const delay = typeof transition?.delay === 'number' ? transition.delay : 0
+        return Math.max(0, (duration + delay) * 1000)
+    }
+    let cleanupSVGPathAttributeEffect: (() => void) | null = null
+
+    /**
+     * Reads the current normalized SVG path drawing state from DOM
+     * attributes. `motion-dom`'s svgEffect owns future writes; this only
+     * seeds its MotionValues from the currently rendered frame.
+     *
+     * @param {SVGPathElement} path The SVG path element to inspect.
+     * @returns {{ pathLength: number; pathSpacing: number; pathOffset: number }} The normalized drawing state.
+     */
+    const readSVGPathDrawingState = (
+        path: SVGPathElement
+    ): { pathLength: number; pathSpacing: number; pathOffset: number } => {
+        const dashArray =
+            path.getAttribute('stroke-dasharray') || path.style.strokeDasharray || '1 0'
+        const [rawLength, rawSpacing] = dashArray
+            .split(/[,\s]+/)
+            .filter(Boolean)
+            .map((part) => Number.parseFloat(part))
+        const rawOffset = Number.parseFloat(
+            path.getAttribute('stroke-dashoffset') || path.style.strokeDashoffset || '0'
+        )
+
+        return {
+            pathLength: Number.isFinite(rawLength) ? rawLength : 1,
+            pathSpacing: Number.isFinite(rawSpacing) ? rawSpacing : 1,
+            pathOffset: Number.isFinite(rawOffset) ? -rawOffset : 0
+        }
+    }
+
+    /**
+     * Removes custom SVG path props from keyframes after `svgEffect` has
+     * taken ownership of them.
+     *
+     * @param {Record<string, unknown>} keyframes Keyframes to copy.
+     * @returns {Record<string, unknown>} Keyframes without SVG path-only props.
+     */
+    const stripSVGPathKeyframes = (keyframes: Record<string, unknown>): Record<string, unknown> => {
+        const stripped = { ...keyframes }
+        delete stripped.pathLength
+        delete stripped.pathSpacing
+        delete stripped.pathOffset
+        return stripped
+    }
+
+    /**
+     * Extracts an animation completion promise from a Motion control when
+     * one is available.
+     *
+     * @param {unknown} control The return value from `animate`.
+     * @returns {Promise<unknown> | null} The finished promise, or null.
+     */
+    const getFinishedPromise = (control: unknown): Promise<unknown> | null => {
+        if (!control || typeof control !== 'object') return null
+        const finished = (control as { finished?: unknown }).finished
+        return finished && typeof (finished as Promise<unknown>).then === 'function'
+            ? (finished as Promise<unknown>)
+            : 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.
+     *
+     * @param {SVGPathElement} path The path element to animate.
+     * @param {Record<string, unknown>} keyframes Keyframes containing SVG path props.
+     * @param {MotionTransition} transition The transition to apply to generated MotionValues.
+     * @returns {Promise<unknown>[]} Promises for generated path animations.
+     */
+    const animateSVGPathAttributes = (
+        path: SVGPathElement,
+        keyframes: Record<string, unknown>,
+        transition: MotionTransition,
+        trackControl = false
+    ): Promise<unknown>[] => {
+        if (!hasSVGPathProperties(keyframes)) return []
+
+        cleanupSVGPathAttributeEffect?.()
+        const current = readSVGPathDrawingState(path)
+        const values: Record<string, MotionValue<number>> = {}
+
+        if ('pathLength' in keyframes) {
+            values.pathLength = motionValue(current.pathLength)
+        }
+        if ('pathLength' in keyframes || 'pathSpacing' in keyframes) {
+            values.pathSpacing = motionValue(current.pathSpacing)
+        }
+        if ('pathOffset' in keyframes) {
+            values.pathOffset = motionValue(current.pathOffset)
+        }
+
+        cleanupSVGPathAttributeEffect = svgEffect(path, values)
+
+        return Object.entries(values)
+            .map(([key, value]) => {
+                const control = animate(
+                    value as never,
+                    (key === 'pathSpacing' && !('pathSpacing' in keyframes)
+                        ? 1
+                        : keyframes[key]) as never,
+                    transition as unknown as AnimationOptions
+                )
+                return trackControl
+                    ? trackAnimationControlsControl(control)
+                    : getFinishedPromise(control)
+            })
+            .filter((promise): promise is Promise<unknown> => promise !== null)
+    }
+
+    onDestroy(() => {
+        cleanupSVGPathAttributeEffect?.()
+        cleanupSVGPathAttributeEffect = null
+    })
+
+    // Wait-mode enter coordination needs to affect the first rendered attrs,
+    // before the blocked entrant can participate in layout.
+    let waitCallbackRegistered = $state(false)
+    let waitUnsubscribe: (() => void) | null = null
+    let waitHiddenDisplay: string | null = null
+    let waitEnterReleased = $state(false)
+    let waitLayoutParent: HTMLElement | null = null
+    let waitLayoutParentWidth = ''
+    let waitLayoutParentHeight = ''
+    let waitLayoutViewportScrollX = 0
+    let waitLayoutViewportScrollY = 0
+    const presenceLayoutHoldAttribute = 'data-presence-layout-hold'
+    const presenceLayoutReleaseEvent = 'svelte-motion:presence-layout-release'
+    const waitEnterBlockedBeforeMount = $derived(
+        context?.mode === 'wait' && !waitEnterReleased && context.isEnterBlocked(presenceKey)
+    )
 
     // Derived attributes to keep both branches in sync (focusability, data flags, style, class)
     const derivedAttrs = $derived<Record<string, unknown>>({
@@ -575,6 +962,16 @@
                   'data-path': dataPath
               }
             : {}),
+        ...(renderedOptimizedAppearScript
+            ? { [optimizedAppearDataAttribute]: optimizedAppearId }
+            : {}),
+        ...(layoutProp
+            ? { 'data-layout': String(layoutProp), 'data-svelte-motion-layout': '' }
+            : {}),
+        ...(scopedLayoutId ? { 'data-layout-id': scopedLayoutId } : {}),
+        ...(waitEnterBlockedBeforeMount || waitHiddenDisplay !== null
+            ? { 'data-presence-wait-hidden': 'true' }
+            : {}),
         // Apply normalized SVG path attributes synchronously on first render to avoid flash
         // Compute via svg utils (no dynamic import in SSR/derived expressions)
         ...(() => {
@@ -588,9 +985,7 @@
             return {}
         })(),
         style: mergeInlineStyles(
-            initialKeyframes && 'pathLength' in initialKeyframes && isLoaded === 'mounting'
-                ? `${styleProp || ''};visibility:hidden`
-                : styleProp,
+            `${initialKeyframes && 'pathLength' in initialKeyframes && isLoaded === 'mounting' ? `${styleProp || ''};visibility:hidden` : (styleProp ?? '')}${waitEnterBlockedBeforeMount || waitHiddenDisplay !== null ? ';display:none' : ''}`,
             // The "from" slot: apply initialKeyframes as inline styles during
             // the mounting/initial phases (before the WAAPI animation locks
             // its from-value and we promote to 'ready' — see the lifecycle
@@ -615,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
     })
@@ -869,7 +1268,17 @@
         }
 
         const transitionAnimate: MotionTransition = mergedTransition ?? {}
-        let payload = $state.snapshot(resolvedAnimate)
+        const rawPayload = filterReducedMotionKeyframes(
+            $state.snapshot(resolvedAnimate) as Record<string, unknown>,
+            reducedMotion
+        ) as Record<string, unknown>
+        const svgPathFinished =
+            isSVGPathElement(element) && hasSVGPathProperties(rawPayload)
+                ? animateSVGPathAttributes(element, rawPayload, transitionAnimate)
+                : []
+        let payload = (
+            svgPathFinished.length > 0 ? stripSVGPathKeyframes(rawPayload) : rawPayload
+        ) as typeof rawPayload
 
         // Transform SVG path properties (pathLength, pathOffset) to their CSS equivalents
         payload = transformSVGPathProperties(
@@ -877,13 +1286,6 @@
             payload as Record<string, unknown>
         ) as typeof payload
 
-        // Strip transform keys when reduced-motion is active so the element
-        // stays in place while opacity / color etc. still animate.
-        payload = filterReducedMotionKeyframes(
-            payload as Record<string, unknown>,
-            reducedMotion
-        ) as typeof payload
-
         // Ensure dash properties aren't pinned as inline styles
         if (element && (element as HTMLElement).style) {
             ;(element as HTMLElement).style.removeProperty('stroke-dasharray')
@@ -897,33 +1299,134 @@
 
         // A fresh run owns the transform again until it completes.
         enterAnimationSettled = false
-        animateWithLifecycle(
-            element,
-            payload as unknown as DOMKeyframesDefinition,
-            transitionAnimate as unknown as AnimationOptions,
-            (def) => onAnimationStartProp?.(def as unknown as DOMKeyframesDefinition | undefined),
-            (def) => {
-                // Now the target is the resting state — promote it to the
-                // inline baseline so it persists after WAAPI surrenders the
-                // property (default fill:'none'). (#377)
-                enterAnimationSettled = true
-                onAnimationCompleteProp?.(def as unknown as DOMKeyframesDefinition | undefined)
-            }
-        )
+        const completeEnterAnimation = (
+            def: DOMKeyframesDefinition | undefined = payload as unknown as DOMKeyframesDefinition
+        ) => {
+            if (enterAnimationSettled) return
+            // Now the target is the resting state — promote it to the
+            // inline baseline so it persists after WAAPI surrenders the
+            // property (default fill:'none'). (#377)
+            applyAnimateRestingStyle()
+            enterAnimationSettled = true
+            onAnimationCompleteProp?.(def)
+        }
+        if (isNotEmpty(payload)) {
+            animateWithLifecycle(
+                element,
+                payload as unknown as DOMKeyframesDefinition,
+                transitionAnimate as unknown as AnimationOptions,
+                (def) =>
+                    onAnimationStartProp?.(def as unknown as DOMKeyframesDefinition | undefined),
+                (def) =>
+                    completeEnterAnimation(def as unknown as DOMKeyframesDefinition | undefined)
+            )
+        } else if (svgPathFinished.length > 0) {
+            onAnimationStartProp?.(rawPayload as unknown as DOMKeyframesDefinition)
+            Promise.all(svgPathFinished)
+                .then(() => completeEnterAnimation(rawPayload as unknown as DOMKeyframesDefinition))
+                .catch(() =>
+                    completeEnterAnimation(rawPayload as unknown as DOMKeyframesDefinition)
+                )
+        }
+        if (isJsdomRuntime()) {
+            window.setTimeout(
+                () => completeEnterAnimation(),
+                getTransitionFallbackMs(transitionAnimate as AnimationOptions)
+            )
+        }
     }
 
-    // Track if we've already registered a wait callback to prevent duplicates
-    let waitCallbackRegistered = $state(false)
-    let waitUnsubscribe: (() => void) | null = null
-
     // Cleanup wait callback on component unmount to prevent memory leaks
     $effect(() => {
         return () => {
+            if (element && waitHiddenDisplay !== null) {
+                element.style.display = waitHiddenDisplay
+                element.removeAttribute('data-presence-wait-hidden')
+                waitHiddenDisplay = null
+            }
+            releaseWaitLayoutHold()
             waitUnsubscribe?.()
             waitUnsubscribe = null
         }
     })
 
+    const getPresenceLayoutParent = (): HTMLElement | null => {
+        let parent = element?.parentElement ?? null
+        const layoutParent = element?.parentElement?.closest<HTMLElement>(
+            '[data-svelte-motion-layout]'
+        )
+        if (layoutParent) return layoutParent
+
+        while (parent && getComputedStyle(parent).display === 'contents') {
+            parent = parent.parentElement
+        }
+        return parent
+    }
+
+    const holdWaitLayout = () => {
+        if (!element || waitLayoutParent) return
+        const parent = getPresenceLayoutParent()
+        if (!parent) return
+
+        const rect = parent.getBoundingClientRect()
+        waitLayoutParent = parent
+        waitLayoutParentWidth = parent.style.width
+        waitLayoutParentHeight = parent.style.height
+        waitLayoutViewportScrollX = typeof window !== 'undefined' ? window.scrollX : 0
+        waitLayoutViewportScrollY = typeof window !== 'undefined' ? window.scrollY : 0
+        parent.setAttribute(presenceLayoutHoldAttribute, 'true')
+        parent.style.width = `${rect.width}px`
+        parent.style.height = `${rect.height}px`
+    }
+
+    function releaseWaitLayoutHold() {
+        if (!waitLayoutParent) return
+        const parent = waitLayoutParent
+        const previousRect = parent.getBoundingClientRect()
+        parent.removeAttribute(presenceLayoutHoldAttribute)
+        if (waitLayoutParentWidth) {
+            parent.style.width = waitLayoutParentWidth
+        } else {
+            parent.style.removeProperty('width')
+        }
+        if (waitLayoutParentHeight) {
+            parent.style.height = waitLayoutParentHeight
+        } else {
+            parent.style.removeProperty('height')
+        }
+        const viewportScrolledDuringHold =
+            typeof window !== 'undefined' &&
+            (window.scrollX !== waitLayoutViewportScrollX ||
+                window.scrollY !== waitLayoutViewportScrollY)
+        parent.dispatchEvent(
+            new CustomEvent(presenceLayoutReleaseEvent, {
+                detail: {
+                    previousRect: domRectToRectLike(previousRect),
+                    viewportScrolledDuringHold
+                }
+            })
+        )
+        waitLayoutParent = null
+        waitLayoutParentWidth = ''
+        waitLayoutParentHeight = ''
+        waitLayoutViewportScrollX = 0
+        waitLayoutViewportScrollY = 0
+    }
+
+    const revealWaitHiddenElement = () => {
+        waitEnterReleased = true
+        if (waitHiddenDisplay !== null && element) {
+            if (waitHiddenDisplay) {
+                element.style.display = waitHiddenDisplay
+            } else {
+                element.style.removeProperty('display')
+            }
+            element.removeAttribute('data-presence-wait-hidden')
+            waitHiddenDisplay = null
+        }
+        releaseWaitLayoutHold()
+    }
+
     /**
      * Run the enter animation, respecting wait mode if inside AnimatePresence.
      * Returns true if animation was deferred (wait mode with blocked enters).
@@ -949,12 +1452,21 @@
                 return true // Still deferred
             }
 
-            const blocked = context.isEnterBlocked?.()
+            const blocked = context.isEnterBlocked?.(presenceKey)
             pwLog('[motion] runAnimation: wait mode', { blocked })
 
             if (blocked) {
                 pwLog('[motion] runAnimation: enters blocked, deferring')
 
+                waitEnterReleased = false
+                if (waitHiddenDisplay === null) {
+                    waitHiddenDisplay =
+                        element.style.display === 'none' ? '' : element.style.display
+                    element.style.display = 'none'
+                    element.setAttribute('data-presence-wait-hidden', 'true')
+                    holdWaitLayout()
+                }
+
                 waitCallbackRegistered = true
 
                 // Register callback to run animation when unblocked
@@ -964,6 +1476,12 @@
                     waitUnsubscribe = null
                     waitCallbackRegistered = false
 
+                    // Reveal synchronously after the exiting placeholder has
+                    // been removed. The parent is fixed-size until the next
+                    // frame, so it measures the final entrant instead of an
+                    // overlap between exiting and entering content.
+                    revealWaitHiddenElement()
+
                     // Snap to initial state first (in case inline styles were removed)
                     if (initialKeyframes && element) {
                         const transformedInitial = transformSVGPathProperties(
@@ -985,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'
                         })
@@ -995,6 +1516,11 @@
                 })
                 return true // Animation was deferred
             }
+
+            if (waitHiddenDisplay !== null || waitEnterBlockedBeforeMount) {
+                pwLog('[motion] runAnimation: wait mode no longer blocked, revealing')
+                revealWaitHiddenElement()
+            }
         }
 
         // Not blocked - run animation immediately
@@ -1018,14 +1544,97 @@
     let objectAnimateRanOnMount = $state(false)
     // Track the serialized animateProp to detect changes for object animate props
     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
     )
 
+    $effect(() => {
+        if (!motionDomProjection) return
+        motionDomProjection.updateOptions({
+            layout: layoutProp,
+            layoutId: scopedLayoutId,
+            layoutScroll: layoutScrollProp,
+            transition: mergedTransition as never,
+            style: styleProp
+        })
+    })
+
+    $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()
+        }
+    })
+
+    let explicitLayoutSnapshot: RectLike | null = null
+    let lastRect: RectLike | null = null
+    const trackLayoutProjectionDependencies = () => [
+        classProp,
+        styleProp,
+        scopedLayoutId,
+        mergedTransition
+    ]
+
+    $effect.pre(() => {
+        const shouldProject = element && layoutProp && isLoaded === 'ready' && hasLayoutFeatures
+        // Track common layout-affecting props so Svelte-owned updates can
+        // snapshot before the DOM patch, matching upstream MeasureLayout.
+        trackLayoutProjectionDependencies()
+
+        if (!shouldProject) {
+            explicitLayoutSnapshot = null
+            return
+        }
+
+        explicitLayoutSnapshot = measureLayoutRect()
+        projection.willUpdate()
+        motionDomProjection?.willUpdate()
+        motionDomProjectionUpdatePending = true
+    })
+
+    $effect(() => {
+        const shouldProject = element && layoutProp && isLoaded === 'ready' && hasLayoutFeatures
+        trackLayoutProjectionDependencies()
+
+        if (!shouldProject || !motionDomProjectionUpdatePending) return
+        motionDomProjectionUpdatePending = false
+        const previous = explicitLayoutSnapshot
+        explicitLayoutSnapshot = null
+        if (previous) {
+            const next = measureLayoutRect()
+            if (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()
+        motionDomProjection?.didUpdate()
+    })
+
     // Projection node lifecycle + the `onProjectionUpdate` listener.
     // Mount once the element binds; seed the baseline layout; unmount on
     // cleanup. Depends ONLY on `element` — the `onProjectionUpdate`
@@ -1053,56 +1662,140 @@
         }
     })
 
-    // Minimal layout animation using FLIP when `layout` is enabled.
-    // When layout === 'position' we only translate.
-    // When layout === true we also scale to smoothly interpolate size changes.
-    let lastRect: RectLike | null = null
+    // Upstream layout projection via motion-dom. Svelte runes mode doesn't
+    // expose the React-style pre/post render hook pair used upstream, so the
+    // component snapshots committed layout changes through DOM observers while
+    // keeping the existing local ProjectionNode event fan-out alive.
     $effect(() => {
         if (!(element && layoutProp && isLoaded === 'ready' && hasLayoutFeatures)) return
 
-        // Initialize last rect on first ready frame. We measure through the
-        // projection node rather than `measureRect` directly so the rect is
-        // ancestor-transform-invariant: the node resets the whole ancestor
-        // chain to its mount-time base while reading, which strips any
-        // motion-applied (FLIP/drag) transform up the tree. Without this a
-        // child re-measures and FLIPs whenever an ancestor's transform
-        // animates, even though the child's own layout never moved. (#379)
+        let rafId: number | null = null
+        let wasViewportOffscreenSinceLastLayout = false
+        let wasViewportScrolledSinceLastLayout = false
+        const flipLayoutMode = layoutProp === 'position' ? 'position' : true
+        motionDomProjection?.seedLayout()
         lastRect = measureLayoutRect()
-        // Hint compositor for smoother FLIP transforms
         setCompositorHints(element!, true)
 
-        let rafId: number | null = null
-        const runFlip = () => {
-            // commitLayoutChange does the ancestor-stripped measure, fans
-            // the delta out to `onProjectionUpdate` listeners, AND returns
-            // the freshly-measured box — so the FLIP reuses that single
-            // measurement as `next` instead of walking + transform-resetting
-            // the ancestor chain a second time per frame. (#379)
+        const rememberOffscreenScroll = () => {
+            wasViewportScrolledSinceLastLayout = true
+            if (motionDomProjection?.isAnimating()) {
+                motionDomProjection.finishAnimation()
+            }
+            if (isViewportOffscreen(element!.getBoundingClientRect())) {
+                wasViewportOffscreenSinceLastLayout = true
+                motionDomProjection?.finishAnimation()
+            }
+        }
+
+        const commitObservedLayout = () => {
+            if (element!.hasAttribute('data-layout-size-animation')) {
+                return
+            }
+
+            const hasPresenceHold = element!.hasAttribute(presenceLayoutHoldAttribute)
+            const hasHiddenWaitEnter = !!element!.querySelector(
+                '[data-presence-wait-hidden="true"]'
+            )
+            const hasPresencePlaceholder = !!element!.querySelector(
+                '[data-presence-placeholder="true"]'
+            )
+
+            if (hasPresenceHold || hasHiddenWaitEnter) {
+                return
+            }
+
+            if (hasPresencePlaceholder) {
+                lastRect = measureLayoutRect()
+                motionDomProjection?.seedLayout()
+                return
+            }
+
+            if (
+                wasViewportScrolledSinceLastLayout ||
+                wasViewportOffscreenSinceLastLayout ||
+                isViewportOffscreen(element!.getBoundingClientRect())
+            ) {
+                lastRect = measureLayoutRect()
+                motionDomProjection?.finishAnimation()
+                wasViewportScrolledSinceLastLayout = false
+                wasViewportOffscreenSinceLastLayout = false
+                return
+            }
+
             const nextBox = projection.commitLayoutChange()
-            if (!nextBox) return
-            const next = boxToRectLike(nextBox)
-            if (!lastRect) {
+            let shouldCommitMotionDomLayout = false
+            if (nextBox && lastRect) {
+                const next = boxToRectLike(nextBox)
+                shouldCommitMotionDomLayout = hasRectChanged(lastRect, next)
+                if (!motionDomProjection) {
+                    const transforms = computeFlipTransforms(lastRect, next, flipLayoutMode)
+                    runFlipAnimation(
+                        element!,
+                        transforms,
+                        (mergedTransition ?? {}) as AnimationOptions
+                    )
+                }
                 lastRect = next
-                return
+                wasViewportScrolledSinceLastLayout = false
+                wasViewportOffscreenSinceLastLayout = false
+            } else if (nextBox) {
+                lastRect = boxToRectLike(nextBox)
+                wasViewportScrolledSinceLastLayout = false
+                wasViewportOffscreenSinceLastLayout = false
+            }
+            if (shouldCommitMotionDomLayout) {
+                motionDomProjection?.commitObservedLayoutChange()
             }
-            const transforms = computeFlipTransforms(lastRect, next, layoutProp ?? false)
-            runFlipAnimation(element!, transforms, (mergedTransition ?? {}) as AnimationOptions)
+        }
+
+        const commitPresenceLayoutRelease = (event: Event) => {
+            const detail = (
+                event as CustomEvent<{
+                    previousRect?: RectLike
+                    viewportScrolledDuringHold?: boolean
+                }>
+            ).detail
+            const previous = detail?.previousRect
+            const viewportRect = element!.getBoundingClientRect()
+            const next = measureLayoutRect()
+            if (!(previous && next)) return
+
             lastRect = next
+            const shouldSkipLayoutAnimation =
+                detail?.viewportScrolledDuringHold ||
+                wasViewportScrolledSinceLastLayout ||
+                wasViewportOffscreenSinceLastLayout ||
+                isViewportOffscreen(viewportRect)
+            if (!shouldSkipLayoutAnimation && !motionDomProjection) {
+                const transforms = computeFlipTransforms(previous, next, flipLayoutMode)
+                runFlipAnimation(element!, transforms, (mergedTransition ?? {}) as AnimationOptions)
+            }
+            wasViewportScrolledSinceLastLayout = false
+            wasViewportOffscreenSinceLastLayout = false
+            if (!shouldSkipLayoutAnimation && hasRectChanged(previous, next)) {
+                motionDomProjection?.commitObservedLayoutChange()
+            } else if (shouldSkipLayoutAnimation) {
+                motionDomProjection?.finishAnimation()
+            }
         }
 
-        const scheduleFlip = () => {
-            if (rafId) cancelAnimationFrame(rafId)
+        const scheduleProjectionCommit = () => {
+            if (rafId) return
+            commitObservedLayout()
             rafId = requestAnimationFrame(() => {
                 rafId = null
-                runFlip()
             })
         }
-        const disconnectObservers = observeLayoutChanges(element!, () => scheduleFlip())
+        const disconnectObservers = observeLayoutChanges(element!, () => scheduleProjectionCommit())
+        window.addEventListener('scroll', rememberOffscreenScroll, { passive: true })
+        element!.addEventListener(presenceLayoutReleaseEvent, commitPresenceLayoutRelease)
 
         return () => {
             disconnectObservers()
+            window.removeEventListener('scroll', rememberOffscreenScroll)
+            element?.removeEventListener(presenceLayoutReleaseEvent, commitPresenceLayoutRelease)
             lastRect = null
-            // Reset compositor hints on teardown
             if (element) {
                 setCompositorHints(element, false)
             }
@@ -1126,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)
@@ -1235,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(() => {
@@ -1343,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
             }
@@ -1358,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
@@ -1398,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
@@ -1423,6 +2140,7 @@
 
     $effect(() => {
         if (!(element && isLoaded === 'mounting')) return
+        markMotionMounted()
 
         pwLog('[motion] main effect running', {
             effectiveAnimate: !!effectiveAnimate,
@@ -1452,6 +2170,30 @@
                 dataPath = 5
                 isLoaded = 'ready'
             } else if (isNotEmpty(initialKeyframes)) {
+                const canHandoffOptimizedAppear = hasOptimizedAppearAnimation(optimizedAppearId)
+                if (canHandoffOptimizedAppear) {
+                    pwLog('[motion] path: optimized appear handoff')
+                    dataPath = 6
+                    isLoaded = 'initial'
+                    initialAnimationTriggered = true
+                    if (declarativeAnimateProp && typeof declarativeAnimateProp !== 'string') {
+                        objectAnimateRanOnMount = true
+                        lastAnimatePropJson = JSON.stringify(declarativeAnimateProp)
+                    }
+                    finishOptimizedAppearAnimation(optimizedAppearId)
+                        .then(() => {
+                            applyAnimateRestingStyle()
+                            enterAnimationSettled = true
+                            isLoaded = 'ready'
+                            onAnimationCompleteProp?.(
+                                resolvedAnimate as DOMKeyframesDefinition | undefined
+                            )
+                        })
+                        .catch(() => {
+                            isLoaded = 'ready'
+                        })
+                    return
+                }
                 pwLog('[motion] path: has initialKeyframes, will animate to target')
                 // Apply initial instantly BEFORE exposing 'initial' state
                 const transformedInitial = transformSVGPathProperties(
@@ -1500,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.
@@ -1572,15 +2314,23 @@
 {#if isVoidTag}
     {#if isSVGTag(String(tag))}
         <svelte:element this={tag} bind:this={element} xmlns={SVG_NAMESPACE} {...derivedAttrs} />
+        <!-- trunk-ignore(eslint/svelte/no-at-html-tags): optimized appear emits a JSON-escaped SSR bootstrap script, not user-authored HTML. -->
+        {@html renderedOptimizedAppearScript}
     {:else}
         <svelte:element this={tag} bind:this={element} {...derivedAttrs} />
+        <!-- trunk-ignore(eslint/svelte/no-at-html-tags): optimized appear emits a JSON-escaped SSR bootstrap script, not user-authored HTML. -->
+        {@html renderedOptimizedAppearScript}
     {/if}
 {:else if isSVGTag(String(tag))}
     <svelte:element this={tag} bind:this={element} xmlns={SVG_NAMESPACE} {...derivedAttrs}>
         {@render children?.()}
     </svelte:element>
+    <!-- trunk-ignore(eslint/svelte/no-at-html-tags): optimized appear emits a JSON-escaped SSR bootstrap script, not user-authored HTML. -->
+    {@html renderedOptimizedAppearScript}
 {:else}
     <svelte:element this={tag} bind:this={element} {...derivedAttrs}>
         {@render children?.()}
     </svelte:element>
+    <!-- trunk-ignore(eslint/svelte/no-at-html-tags): optimized appear emits a JSON-escaped SSR bootstrap script, not user-authored HTML. -->
+    {@html renderedOptimizedAppearScript}
 {/if}