@humanspeak/svelte-motion 0.1.14 → 0.1.16

package/README.md

@@ -117,7 +117,7 @@ This package carefully selects its dependencies to provide a robust and maintain
 | [Fancy Like Button](https://github.com/DRlFTER/fancyLikeButton)                                          | `/tests/random/fancy-like-button`        | [View Example](https://svelte.dev/playground/c34b7e53d41c48b0ab1eaf21ca120c6e?version=5.38.10) |
 | [Keyframes (square → circle → square; scale 1→2→1)](https://motion.dev/docs/react-animation#keyframes)   | `/tests/motion/keyframes`                | [View Example](https://svelte.dev/playground/05595ce0db124c1cbbe4e74fda68d717?version=5.38.10) |
 | [Animated Border Gradient (conic-gradient rotate)](https://www.youtube.com/watch?v=OgQI1-9T6ZA)          | `/tests/random/animated-border-gradient` | [View Example](https://svelte.dev/playground/6983a61b4c35441b8aa72a971de01a23?version=5.38.10) |
-| [Exit Animation](https://motion.dev/docs/react#exit-animations)                                          | `/tests/motion/animate-presence`         | [View Example](https://svelte.dev/playground/ef277e283d864653ace54e7453801601?version=5.38.10) |
+| [Exit Animation](https://motion.dev/docs/react#exit-animations)                                          | `/tests/animate-presence/basic`          | [View Example](https://svelte.dev/playground/ef277e283d864653ace54e7453801601?version=5.38.10) |
 
 ## Interactions
 

package/dist/components/AnimatePresence.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
     import type { Snippet } from 'svelte'
     import { createAnimatePresenceContext, setAnimatePresenceContext } from '../utils/presence'
+    import { pwLog } from '../utils/log'
 
     /**
      * Provide `AnimatePresence` context to descendants.
@@ -10,14 +11,21 @@
      * styled clone is animated out before being removed from the DOM.
      *
      * @prop children Slotted content participating in presence.
+     * @prop initial When false, children skip their enter animation on initial mount.
      * @prop onExitComplete Optional callback invoked once all exits complete.
      */
-    const { children, onExitComplete } = $props<{
+    const {
+        children,
+        initial = true,
+        onExitComplete
+    } = $props<{
         children?: Snippet
+        initial?: boolean
         onExitComplete?: () => void
     }>()
 
-    const context = createAnimatePresenceContext({ onExitComplete })
+    pwLog('[AnimatePresence] mounting', { initial, hasOnExitComplete: !!onExitComplete })
+    const context = createAnimatePresenceContext({ initial, onExitComplete })
     setAnimatePresenceContext(context)
 </script>
 

package/dist/components/AnimatePresence.svelte.d.ts

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte';
 type $$ComponentProps = {
     children?: Snippet;
+    initial?: boolean;
     onExitComplete?: () => void;
 };
 declare const AnimatePresence: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/html/_MotionContainer.svelte

@@ -1,3 +1,8 @@
+<script lang="ts" module>
+    // Module-level counter for deterministic key generation (avoids SSR hydration mismatch)
+    let keyCounter = 0
+</script>
+
 <script lang="ts">
     import { getMotionConfig } from '../components/motionConfig.context'
     import type {
@@ -20,6 +25,7 @@
     import { attachWhileTap } from '../utils/interaction'
     import { attachWhileHover } from '../utils/hover'
     import { attachWhileFocus } from '../utils/focus'
+    import { attachWhileInView } from '../utils/inView'
     import {
         measureRect,
         computeFlipTransforms,
@@ -52,6 +58,7 @@
     let {
         children,
         tag = 'div',
+        key: keyProp,
         variants: variantsProp,
         initial: initialProp,
         animate: animateProp,
@@ -64,11 +71,14 @@
         whileTap: whileTapProp,
         whileHover: whileHoverProp,
         whileFocus: whileFocusProp,
+        whileInView: whileInViewProp,
         whileDrag: whileDragProp,
         onHoverStart: onHoverStartProp,
         onHoverEnd: onHoverEndProp,
         onFocusStart: onFocusStartProp,
         onFocusEnd: onFocusEndProp,
+        onInViewStart: onInViewStartProp,
+        onInViewEnd: onInViewEndProp,
         onTapStart: onTapStartProp,
         onTap: onTapProp,
         onTapCancel: onTapCancelProp,
@@ -95,8 +105,20 @@
     let dataPath = $state<number>(-1)
     const motionConfig = $derived(getMotionConfig())
 
-    // Generate unique key for presence tracking
-    const presenceKey = `motion-${Math.random().toString(36).slice(2)}`
+    // Get presence context to check if we're inside AnimatePresence
+    const context = getAnimatePresenceContext()
+
+    // Validate key prop when inside AnimatePresence
+    if (context && !keyProp) {
+        throw new Error(
+            'motion elements inside AnimatePresence must have a `key` prop. ' +
+                'Example: <motion.div key="unique-id" />'
+        )
+    }
+
+    // Use the provided key for presence tracking
+    // When not inside AnimatePresence, use a stable identifier based on component instance
+    const presenceKey = keyProp ?? `motion-${++keyCounter}`
 
     // Compute merged transition without mutating props to avoid effect write loops
     const mergedTransition = $derived<AnimationOptions>(
@@ -118,12 +140,10 @@
         }
     })
 
-    const context = getAnimatePresenceContext()
     // Update presence context with current state when element is ready and has size
     $effect(() => {
         if (!(context && element && isLoaded === 'ready')) return
 
-        let rafId: number | null = null
         let lastWidth = 0
         let lastHeight = 0
         let stopped = false
@@ -132,11 +152,6 @@
             if (stopped || !element || !element.isConnected) return
             const rect = element.getBoundingClientRect()
             const style = getComputedStyle(element)
-            pwLog('[motion][measure]', {
-                w: rect.width,
-                h: rect.height,
-                transform: style.transform
-            })
             if (
                 Math.abs(rect.width - lastWidth) > 0.5 ||
                 Math.abs(rect.height - lastHeight) > 0.5
@@ -149,6 +164,7 @@
 
         // Observe size changes
         const resizeObserver = new ResizeObserver(() => {
+            pwLog('[motion][resize]', { key: presenceKey })
             measureAndUpdate()
         })
         try {
@@ -157,15 +173,8 @@
             // Ignore
         }
 
-        // Also poll on RAF to catch transform/layout-driven changes
-        const tick = () => {
-            if (stopped) return
-            measureAndUpdate()
-            rafId = requestAnimationFrame(tick)
-        }
-        rafId = requestAnimationFrame(tick)
-
         // Initial measure once
+        pwLog('[motion][initial-measure]', { key: presenceKey })
         measureAndUpdate()
 
         return () => {
@@ -175,7 +184,6 @@
             } catch {
                 // Ignore
             }
-            if (rafId) cancelAnimationFrame(rafId)
         }
     })
 
@@ -217,13 +225,23 @@
     )
 
     // Propagate initial={false} to children BEFORE setting variant context
+    // AnimatePresence initial={false} only applies on first render - check shouldAnimateEnter(key)
     const parentInitialFalse = getInitialFalseContext()
-    const effectiveInitialProp =
-        initialProp !== undefined
-            ? initialProp
-            : parentInitialFalse && variantsProp
-              ? false
-              : undefined
+    const presenceSkipEnter = context ? !context.shouldAnimateEnter(presenceKey) : false
+    const effectiveInitialProp = presenceSkipEnter
+        ? false
+        : initialProp !== undefined
+          ? initialProp
+          : parentInitialFalse && variantsProp
+            ? false
+            : undefined
+
+    pwLog('[motion] mount', {
+        presenceSkipEnter,
+        effectiveInitialProp,
+        initialProp,
+        animateProp
+    })
 
     if (initialProp === false) {
         setInitialFalseContext(true)
@@ -279,8 +297,20 @@
             initialKeyframes && 'pathLength' in initialKeyframes && isLoaded === 'mounting'
                 ? `${styleProp || ''};visibility:hidden`
                 : styleProp,
-            initialKeyframes as unknown as Record<string, unknown>,
-            resolvedAnimate as unknown as Record<string, unknown>
+            // Apply initialKeyframes as inline styles during mounting and initial phases
+            // The animation starts in RAF after 'initial' phase, so we need styles until then
+            // When ready AND we have initialKeyframes: DON'T set any animated properties!
+            // WAAPI is controlling them and inline styles can override the animation
+            isLoaded === 'mounting' || isLoaded === 'initial'
+                ? (initialKeyframes as unknown as Record<string, unknown>)
+                : undefined,
+            // Only use resolvedAnimate as fallback when we DON'T have initialKeyframes
+            // If we have initialKeyframes, the enter animation is running - setting
+            // inline styles to the target values will override the WAAPI animation
+            // Use isNotEmpty to handle empty initial objects (initial: {}) which should fallback
+            isNotEmpty(initialKeyframes)
+                ? undefined
+                : (resolvedAnimate as unknown as Record<string, unknown>)
         ),
         class: classProp
     })
@@ -357,7 +387,16 @@
     })
 
     const runAnimation = () => {
-        if (!element || !resolvedAnimate) return
+        pwLog('[motion] runAnimation called', {
+            hasElement: !!element,
+            resolvedAnimate,
+            mergedTransition
+        })
+        if (!element || !resolvedAnimate) {
+            pwLog('[motion] runAnimation bailing - no element or resolvedAnimate')
+            return
+        }
+
         const transitionAnimate: MotionTransition = mergedTransition ?? {}
         let payload = $state.snapshot(resolvedAnimate)
 
@@ -373,6 +412,11 @@
             ;(element as HTMLElement).style.removeProperty('stroke-dashoffset')
         }
 
+        pwLog('[motion] runAnimation animating', {
+            payload,
+            transitionAnimate
+        })
+
         animateWithLifecycle(
             element,
             payload as unknown as DOMKeyframesDefinition,
@@ -385,6 +429,12 @@
     // Track the last variant key we ran to avoid re-running on mount
     let lastRanVariantKey = $state<string | undefined>(undefined)
     let mountedWithInitialFalse = $state(false)
+    // Track if the initial->animate transition has already been triggered by main effect
+    let initialAnimationTriggered = $state(false)
+    // Track if we've run the animation for object animateProp on this mount
+    let objectAnimateRanOnMount = $state(false)
+    // Track the serialized animateProp to detect changes for object animate props
+    let lastAnimatePropJson = $state<string | undefined>(undefined)
     const currentAnimateKey = $derived(
         typeof animateProp === 'string'
             ? animateProp
@@ -487,6 +537,25 @@
         )
     })
 
+    // whileInView handling for viewport intersection
+    $effect(() => {
+        if (!(element && isLoaded === 'ready' && isNotEmpty(whileInViewProp))) return
+        return attachWhileInView(
+            element!,
+            (whileInViewProp ?? {}) as Record<string, unknown>,
+            (mergedTransition ?? {}) as AnimationOptions,
+            {
+                onStart: onInViewStartProp,
+                onEnd: onInViewEndProp,
+                onAnimationComplete: onAnimationCompleteProp
+            },
+            {
+                initial: (resolvedInitial ?? {}) as Record<string, unknown>,
+                animate: (resolvedAnimate ?? {}) as Record<string, unknown>
+            }
+        )
+    })
+
     // Re-run animate when animateProp changes while ready
     $effect(() => {
         if (!(element && isLoaded === 'ready')) return
@@ -500,15 +569,39 @@
             // Variant has changed, so we should animate
             mountedWithInitialFalse = false
         }
+        // Skip if the initial animation was already triggered by the main effect
+        if (initialAnimationTriggered) {
+            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') {
+                objectAnimateRanOnMount = true
+            }
+            return
+        }
         if (typeof animateProp === 'string') {
             if (lastRanVariantKey !== animateProp) {
                 lastRanVariantKey = animateProp
                 runAnimation()
             }
         } else if (animateProp) {
-            // Object animate props - always run
-            lastRanVariantKey = undefined
-            runAnimation()
+            // Object animate props - detect if the prop actually changed
+            const currentJson = JSON.stringify(animateProp)
+            const propChanged = lastAnimatePropJson !== currentJson
+
+            // Reset flag if animate prop changed
+            if (propChanged) {
+                objectAnimateRanOnMount = false
+                lastAnimatePropJson = currentJson
+            }
+
+            // Only run if we haven't already animated on this mount (or prop changed)
+            // This prevents duplicate animations when Svelte re-triggers the effect
+            if (!objectAnimateRanOnMount) {
+                objectAnimateRanOnMount = true
+                lastRanVariantKey = undefined
+                runAnimation()
+            }
         }
     })
 
@@ -539,9 +632,18 @@
     $effect(() => {
         if (!(element && isLoaded === 'mounting')) return
 
+        pwLog('[motion] main effect running', {
+            effectiveAnimate: !!effectiveAnimate,
+            effectiveInitialProp,
+            resolvedAnimate,
+            initialKeyframes,
+            hasInitialKeyframes: isNotEmpty(initialKeyframes)
+        })
+
         if (effectiveAnimate) {
             // If initial={false}, render at animate state immediately with no transition
             if (effectiveInitialProp === false && resolvedAnimate) {
+                pwLog('[motion] path: initial=false, skip to animate')
                 // Use Motion's animate() with duration:0 so it takes control of these properties
                 // This prevents inline styles from pinning the properties during future animations
                 let snapshot = $state.snapshot(resolvedAnimate) as Record<string, unknown>
@@ -555,6 +657,7 @@
                 dataPath = 5
                 isLoaded = 'ready'
             } else if (isNotEmpty(initialKeyframes)) {
+                pwLog('[motion] path: has initialKeyframes, will animate to target')
                 // Apply initial instantly BEFORE exposing 'initial' state
                 const transformedInitial = transformSVGPathProperties(
                     element!,
@@ -598,11 +701,29 @@
                     if (isPlaywright) {
                         await sleep(10)
                     }
-                    isLoaded = 'ready'
+                    pwLog('[motion] RAF: promoting to ready and running animation')
+
+                    // Mark that we're triggering the initial animation to prevent duplicate runs
+                    initialAnimationTriggered = true
 
+                    // IMPORTANT: Start the animation BEFORE changing isLoaded.
+                    // When isLoaded changes to 'ready', Svelte will reactively remove the
+                    // initial inline styles. We need the animation to capture the current
+                    // state (from inline styles) before they're removed.
                     runAnimation()
+
+                    // CRITICAL: Wait for the next animation frame before changing isLoaded.
+                    // This gives WAAPI time to:
+                    // 1. Parse and create the animation
+                    // 2. Start the animation layer
+                    // 3. Lock in the "from" values from current computed style
+                    // Only THEN can we safely clear inline styles without killing the animation
+                    requestAnimationFrame(() => {
+                        isLoaded = 'ready'
+                    })
                 })
             } else {
+                pwLog('[motion] path: no initialKeyframes, skip to ready')
                 dataPath = 2
                 isLoaded = 'ready'
                 // If we're inheriting a variant and parent had initial={false}, apply the variant instantly

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import MotionConfig from './components/MotionConfig.svelte';
 import type { MotionComponents } from './html/index';
 export declare const motion: MotionComponents;
 export { animate, hover } from 'motion';
-export type { DragAxis, DragConstraints, DragControls, DragInfo, DragTransition, MotionAnimate, MotionInitial, MotionOnDirectionLock, MotionOnDragTransitionEnd, MotionTransition, MotionWhileDrag, MotionWhileFocus, MotionWhileHover, MotionWhileTap, Variants } from './types';
+export type { DragAxis, DragConstraints, DragControls, DragInfo, DragTransition, MotionAnimate, MotionInitial, MotionOnDirectionLock, MotionOnDragTransitionEnd, MotionOnInViewEnd, MotionOnInViewStart, MotionTransition, MotionWhileDrag, MotionWhileFocus, MotionWhileHover, MotionWhileInView, MotionWhileTap, Variants } from './types';
 export { useAnimationFrame } from './utils/animationFrame';
 export { createDragControls } from './utils/dragControls';
 export { useSpring } from './utils/spring';

package/dist/types.d.ts

@@ -121,6 +121,18 @@ export type MotionWhileFocus = (Record<string, unknown> & {
 export type MotionWhileDrag = (Record<string, unknown> & {
     transition?: AnimationOptions;
 }) | DOMKeyframesDefinition | undefined;
+/**
+ * Animation properties for in-view interactions.
+ * When the element enters the viewport, it animates to this state; when it leaves,
+ * it animates back to its baseline (from animate/initial), restoring only the changed keys.
+ * @example
+ * ```svelte
+ * <motion.div whileInView={{ opacity: 1, y: 0 }} />
+ * ```
+ */
+export type MotionWhileInView = (Record<string, unknown> & {
+    transition?: AnimationOptions;
+}) | DOMKeyframesDefinition | undefined;
 /**
  * Animation transition configuration for hover interactions.
  * Overrides the global transition when provided.
@@ -136,6 +148,9 @@ export type MotionOnHoverEnd = (() => void) | undefined;
 /** Focus lifecycle callbacks */
 export type MotionOnFocusStart = (() => void) | undefined;
 export type MotionOnFocusEnd = (() => void) | undefined;
+/** InView lifecycle callbacks */
+export type MotionOnInViewStart = (() => void) | undefined;
+export type MotionOnInViewEnd = (() => void) | undefined;
 /** Tap lifecycle callbacks */
 export type MotionOnTapStart = (() => void) | undefined;
 export type MotionOnTap = (() => void) | undefined;
@@ -190,6 +205,21 @@ export type DragControls = {
  * Base motion props shared by all motion components.
  */
 export type MotionProps = {
+    /**
+     * Unique key for AnimatePresence tracking.
+     * Required when inside an AnimatePresence component.
+     * Used to track enter/exit state and determine whether to animate.
+     *
+     * @example
+     * ```svelte
+     * <AnimatePresence>
+     *   {#if isVisible}
+     *     <motion.div key="box" exit={{ opacity: 0 }} />
+     *   {/if}
+     * </AnimatePresence>
+     * ```
+     */
+    key?: string;
     /** Variants define named animation states */
     variants?: Variants;
     /** Initial state of the animation (object or variant key) */
@@ -208,6 +238,8 @@ export type MotionProps = {
     whileFocus?: MotionWhileFocus;
     /** Drag interaction animation */
     whileDrag?: MotionWhileDrag;
+    /** In-view interaction animation - animates when element enters viewport */
+    whileInView?: MotionWhileInView;
     /** Called right before a main animate transition starts */
     onAnimationStart?: MotionAnimationStart;
     /** Called after a main animate transition completes */
@@ -220,6 +252,10 @@ export type MotionProps = {
     onFocusStart?: MotionOnFocusStart;
     /** Called when element loses keyboard focus */
     onFocusEnd?: MotionOnFocusEnd;
+    /** Called when element enters viewport */
+    onInViewStart?: MotionOnInViewStart;
+    /** Called when element leaves viewport */
+    onInViewEnd?: MotionOnInViewEnd;
     /** Called when a tap gesture starts (pointerdown recognized) */
     onTapStart?: MotionOnTapStart;
     /** Called when a tap gesture ends successfully (pointerup) */

package/dist/utils/animation.js

@@ -1,3 +1,4 @@
+import { pwLog } from './log';
 import { hasFinishedPromise, isPromiseLike } from './promise';
 import { animate } from 'motion';
 /**
@@ -32,12 +33,17 @@ export const mergeTransitions = (...args) => {
  * @param onStart Optional lifecycle fired before animation starts.
  * @param onComplete Optional lifecycle fired after animation completes.
  */
-export const animateWithLifecycle = (el, keyframes, transition, 
-/* trunk-ignore(eslint/no-unused-vars) */
-onStart, 
-/* trunk-ignore(eslint/no-unused-vars) */
-onComplete) => {
+export const animateWithLifecycle = (el, keyframes, transition, onStart, onComplete) => {
     const payload = keyframes;
+    const computed = getComputedStyle(el);
+    pwLog('[animateWithLifecycle] starting', {
+        keyframes: payload,
+        transition,
+        currentOpacity: el.style.opacity,
+        currentTransform: el.style.transform,
+        computedOpacity: computed.opacity,
+        computedTransform: computed.transform
+    });
     onStart?.(payload);
     const controls = animate(el, payload, transition);
     if (hasFinishedPromise(controls)) {

package/dist/utils/inView.d.ts

@@ -0,0 +1,79 @@
+import { type AnimationOptions, type DOMKeyframesDefinition } from 'motion';
+/**
+ * Split a whileInView definition into keyframes and an optional nested transition.
+ *
+ * @param def While-in-view record that may include a nested `transition`.
+ * @returns Object with `keyframes` (no `transition`) and optional `transition`.
+ * @example
+ * // With transition
+ * splitInViewDefinition({ opacity: 1, y: 0, transition: { duration: 0.5 } })
+ * // => { keyframes: { opacity: 1, y: 0 }, transition: { duration: 0.5 } }
+ *
+ * @example
+ * // Without transition
+ * splitInViewDefinition({ opacity: 1, scale: 1 })
+ * // => { keyframes: { opacity: 1, scale: 1 }, transition: undefined }
+ */
+export declare const splitInViewDefinition: (def: Record<string, unknown>) => {
+    keyframes: Record<string, unknown>;
+    transition?: AnimationOptions;
+};
+/**
+ * Compute the baseline values to restore to when element leaves viewport.
+ *
+ * Preference order per key: `animate` → `initial` → neutral transform defaults
+ * → computed style value if present.
+ *
+ * @param el Target element.
+ * @param opts Source records for baseline computation.
+ * @returns Minimal baseline record to restore when element leaves viewport.
+ * @example
+ * computeInViewBaseline(element, {
+ *   initial: { opacity: 0, y: 50 },
+ *   animate: { opacity: 1, y: 0 },
+ *   whileInView: { opacity: 1, scale: 1.1 }
+ * })
+ * // => { opacity: 1, scale: 1 } (scale defaults to 1, opacity from animate)
+ */
+export declare const computeInViewBaseline: (el: HTMLElement, opts: {
+    initial?: Record<string, unknown>;
+    animate?: Record<string, unknown>;
+    whileInView?: Record<string, unknown>;
+}) => Record<string, unknown>;
+/**
+ * Attach whileInView interactions to an element using IntersectionObserver.
+ *
+ * On intersection (element enters viewport), animates to `whileInView` state
+ * (using nested `transition` if provided). On un-intersection, restores changed
+ * keys to the baseline using the merged root/component transition.
+ *
+ * Critical fix for issue #230: Checks `entry.isIntersecting` immediately on
+ * first callback to handle elements already in viewport on mount.
+ *
+ * @param el Target element.
+ * @param whileInView While-in-view definition.
+ * @param mergedTransition Root/component merged transition.
+ * @param callbacks Optional lifecycle callbacks for in-view start/end and animation completion.
+ * @param baselineSources Optional sources used to compute baseline.
+ * @returns Cleanup function to disconnect the IntersectionObserver.
+ * @example
+ * const cleanup = attachWhileInView(
+ *   element,
+ *   { opacity: 1, y: 0, transition: { duration: 0.5 } },
+ *   { duration: 0.3 },
+ *   {
+ *     onStart: () => console.log('Entered viewport'),
+ *     onEnd: () => console.log('Left viewport')
+ *   },
+ *   { initial: { opacity: 0, y: 50 } }
+ * )
+ * // Later: cleanup() to disconnect observer
+ */
+export declare const attachWhileInView: (el: HTMLElement, whileInView: Record<string, unknown> | undefined, mergedTransition: AnimationOptions, callbacks?: {
+    onStart?: () => void;
+    onEnd?: () => void;
+    onAnimationComplete?: (definition: DOMKeyframesDefinition | undefined) => void;
+}, baselineSources?: {
+    initial?: Record<string, unknown>;
+    animate?: Record<string, unknown>;
+}) => (() => void);

package/dist/utils/inView.js

@@ -0,0 +1,179 @@
+import { animate } from 'motion';
+/**
+ * Split a whileInView definition into keyframes and an optional nested transition.
+ *
+ * @param def While-in-view record that may include a nested `transition`.
+ * @returns Object with `keyframes` (no `transition`) and optional `transition`.
+ * @example
+ * // With transition
+ * splitInViewDefinition({ opacity: 1, y: 0, transition: { duration: 0.5 } })
+ * // => { keyframes: { opacity: 1, y: 0 }, transition: { duration: 0.5 } }
+ *
+ * @example
+ * // Without transition
+ * splitInViewDefinition({ opacity: 1, scale: 1 })
+ * // => { keyframes: { opacity: 1, scale: 1 }, transition: undefined }
+ */
+export const splitInViewDefinition = (def) => {
+    const { transition, ...rest } = (def ?? {});
+    return { keyframes: rest, transition };
+};
+/**
+ * Compute the baseline values to restore to when element leaves viewport.
+ *
+ * Preference order per key: `animate` → `initial` → neutral transform defaults
+ * → computed style value if present.
+ *
+ * @param el Target element.
+ * @param opts Source records for baseline computation.
+ * @returns Minimal baseline record to restore when element leaves viewport.
+ * @example
+ * computeInViewBaseline(element, {
+ *   initial: { opacity: 0, y: 50 },
+ *   animate: { opacity: 1, y: 0 },
+ *   whileInView: { opacity: 1, scale: 1.1 }
+ * })
+ * // => { opacity: 1, scale: 1 } (scale defaults to 1, opacity from animate)
+ */
+export const computeInViewBaseline = (el, opts) => {
+    const baseline = {};
+    const initialRecord = (opts.initial ?? {});
+    const animateRecord = (opts.animate ?? {});
+    const whileInViewRecordRaw = (opts.whileInView ?? {});
+    const whileInViewRecord = { ...whileInViewRecordRaw };
+    delete whileInViewRecord.transition;
+    const neutralTransformDefaults = {
+        x: 0,
+        y: 0,
+        translateX: 0,
+        translateY: 0,
+        scale: 1,
+        scaleX: 1,
+        scaleY: 1,
+        rotate: 0,
+        rotateX: 0,
+        rotateY: 0,
+        rotateZ: 0,
+        skewX: 0,
+        skewY: 0,
+        opacity: 1
+    };
+    const cs = getComputedStyle(el);
+    const inlineStyle = el.getAttribute('style') || '';
+    // Helper to escape regex metacharacters to prevent ReDoS and ensure literal matching
+    const escapeRegExp = (str) => {
+        return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    };
+    // Helper to extract CSS function (var, calc, min, max, etc.) from inline style if present
+    const getInlineStyleValue = (propName) => {
+        const kebabCase = propName.replace(/([A-Z])/g, '-$1').toLowerCase();
+        const escapedKebabCase = escapeRegExp(kebabCase);
+        // Match property name at start of string or after semicolon
+        const regex = new RegExp(`(?:^|;)\\s*${escapedKebabCase}\\s*:\\s*([^;]+)`, 'i');
+        const match = inlineStyle.match(regex);
+        if (match) {
+            const value = match[1].trim();
+            // Preserve CSS functions: var(), calc(), min(), max(), clamp(), rgb(), hsl(), url(), etc.
+            if (/\b(var|calc|min|max|clamp|rgb|rgba|hsl|hsla|url)\s*\(/.test(value)) {
+                return value;
+            }
+        }
+        return null;
+    };
+    for (const key of Object.keys(whileInViewRecord)) {
+        if (Object.prototype.hasOwnProperty.call(animateRecord, key)) {
+            baseline[key] = animateRecord[key];
+        }
+        else if (Object.prototype.hasOwnProperty.call(initialRecord, key)) {
+            baseline[key] = initialRecord[key];
+        }
+        else if (key in neutralTransformDefaults) {
+            baseline[key] = neutralTransformDefaults[key];
+        }
+        else {
+            // Check if inline style has a CSS variable for this property
+            const inlineValue = getInlineStyleValue(key);
+            if (inlineValue) {
+                baseline[key] = inlineValue;
+            }
+            else if (key in cs) {
+                baseline[key] = cs[key];
+            }
+        }
+    }
+    return baseline;
+};
+/**
+ * Attach whileInView interactions to an element using IntersectionObserver.
+ *
+ * On intersection (element enters viewport), animates to `whileInView` state
+ * (using nested `transition` if provided). On un-intersection, restores changed
+ * keys to the baseline using the merged root/component transition.
+ *
+ * Critical fix for issue #230: Checks `entry.isIntersecting` immediately on
+ * first callback to handle elements already in viewport on mount.
+ *
+ * @param el Target element.
+ * @param whileInView While-in-view definition.
+ * @param mergedTransition Root/component merged transition.
+ * @param callbacks Optional lifecycle callbacks for in-view start/end and animation completion.
+ * @param baselineSources Optional sources used to compute baseline.
+ * @returns Cleanup function to disconnect the IntersectionObserver.
+ * @example
+ * const cleanup = attachWhileInView(
+ *   element,
+ *   { opacity: 1, y: 0, transition: { duration: 0.5 } },
+ *   { duration: 0.3 },
+ *   {
+ *     onStart: () => console.log('Entered viewport'),
+ *     onEnd: () => console.log('Left viewport')
+ *   },
+ *   { initial: { opacity: 0, y: 50 } }
+ * )
+ * // Later: cleanup() to disconnect observer
+ */
+export const attachWhileInView = (el, whileInView, mergedTransition, callbacks, baselineSources) => {
+    if (!whileInView)
+        return () => { };
+    let hasAnimated = false;
+    let inViewBaseline = null;
+    const observer = new IntersectionObserver((entries) => {
+        for (const entry of entries) {
+            if (entry.isIntersecting && !hasAnimated) {
+                // Element entered viewport: animate to whileInView state
+                hasAnimated = true;
+                inViewBaseline = computeInViewBaseline(el, {
+                    initial: baselineSources?.initial,
+                    animate: baselineSources?.animate,
+                    whileInView
+                });
+                callbacks?.onStart?.();
+                const { keyframes, transition } = splitInViewDefinition(whileInView);
+                const animation = animate(el, keyframes, (transition ?? mergedTransition));
+                // Call onAnimationComplete when animation finishes
+                animation.finished
+                    .then(() => {
+                    callbacks?.onAnimationComplete?.(keyframes);
+                })
+                    .catch(() => {
+                    // Animation was cancelled, don't call completion callback
+                });
+            }
+            else if (!entry.isIntersecting && hasAnimated) {
+                // Element left viewport: animate back to baseline
+                if (inViewBaseline && Object.keys(inViewBaseline).length > 0) {
+                    animate(el, inViewBaseline, mergedTransition);
+                }
+                callbacks?.onEnd?.();
+                hasAnimated = false;
+            }
+        }
+    }, { threshold: 0 } // Fire as soon as any part is visible
+    );
+    // Start observing - IntersectionObserver fires immediately for already-visible elements
+    observer.observe(el);
+    // Return cleanup function
+    return () => {
+        observer.disconnect();
+    };
+};

package/dist/utils/presence.d.ts

@@ -5,6 +5,14 @@ import type { MotionExit, MotionTransition } from '../types';
  * so we can clone and animate them out after removal.
  */
 export type AnimatePresenceContext = {
+    /** When false, children skip their enter animation on initial mount. */
+    initial: boolean;
+    /**
+     * Returns true if a child with the given key should animate its enter.
+     * Returns false only during first render when initial={false} AND the key has never been seen.
+     * Re-entries (after exit) always animate.
+     */
+    shouldAnimateEnter: (key: string) => boolean;
     /** Called when all exit animations complete (optional). */
     onExitComplete?: () => void;
     /** Register a child element and its exit definition. */
@@ -35,6 +43,7 @@ export type AnimatePresenceContext = {
  * @returns A presence context with register/update/unregister APIs.
  */
 export declare function createAnimatePresenceContext(context: {
+    initial?: boolean;
     onExitComplete?: () => void;
 }): AnimatePresenceContext;
 /**

package/dist/utils/presence.js

@@ -1,4 +1,5 @@
 import { mergeTransitions } from './animation';
+import { pwLog } from './log';
 import { animate } from 'motion';
 import { getContext, onDestroy, setContext } from 'svelte';
 /**
@@ -44,6 +45,67 @@ const resetTransforms = (element) => {
  * @returns A presence context with register/update/unregister APIs.
  */
 export function createAnimatePresenceContext(context) {
+    // Default initial to true (animate on first mount) unless explicitly false
+    const initial = context.initial !== false;
+    // Track whether we're still in the initial render phase
+    // This is true only when initial={false} and we haven't completed the first frame
+    let isInitialRenderPhase = context.initial === false;
+    // Track keys that have been seen (registered at least once)
+    const seenKeys = new Set();
+    // Track keys that have exited (unregistered after being registered)
+    const exitedKeys = new Set();
+    // After first frame, mark initial render phase as complete
+    // Guard for SSR - requestAnimationFrame only exists in browser
+    if (isInitialRenderPhase && typeof window !== 'undefined') {
+        requestAnimationFrame(() => {
+            requestAnimationFrame(() => {
+                pwLog('[presence] initial render phase complete, enabling animations for new keys');
+                isInitialRenderPhase = false;
+            });
+        });
+    }
+    /**
+     * Determine if a child with the given key should animate its enter.
+     *
+     * - If we're past the initial render phase → always animate
+     * - If key has previously exited → animate (re-entry)
+     * - If key has never been seen AND we're in initial render phase → skip animation
+     */
+    const shouldAnimateEnter = (key) => {
+        // If the key has previously exited, it's a re-entry - always animate
+        if (exitedKeys.has(key)) {
+            pwLog('[presence] shouldAnimateEnter', {
+                key,
+                result: true,
+                reason: 're-entry after exit'
+            });
+            return true;
+        }
+        // If we're past the initial render phase, all new entries animate
+        if (!isInitialRenderPhase) {
+            pwLog('[presence] shouldAnimateEnter', {
+                key,
+                result: true,
+                reason: 'past initial render phase'
+            });
+            return true;
+        }
+        // We're in initial render phase and key hasn't exited before
+        // Check if key has been seen - if not, skip animation (initial={false} behavior)
+        const hasBeenSeen = seenKeys.has(key);
+        const shouldAnimate = hasBeenSeen; // Only animate if we've seen it before (shouldn't happen in initial phase)
+        pwLog('[presence] shouldAnimateEnter', {
+            key,
+            result: shouldAnimate,
+            reason: shouldAnimate ? 'previously seen' : 'first appearance during initial render'
+        });
+        return shouldAnimate;
+    };
+    pwLog('[presence] createContext', {
+        initial,
+        isInitialRenderPhase,
+        onExitComplete: !!context.onExitComplete
+    });
     const children = new Map();
     // Track number of in-flight exit animations to invoke onExitComplete once
     let inFlightExits = 0;
@@ -53,6 +115,20 @@ export function createAnimatePresenceContext(context) {
     const registerChild = (key, element, exit, mergedTransition) => {
         const initialRect = element.getBoundingClientRect();
         const initialStyle = getComputedStyle(element);
+        // Mark this key as seen
+        const wasExited = exitedKeys.has(key);
+        seenKeys.add(key);
+        // If this key was previously exited, remove it from exitedKeys (it's re-entering)
+        if (wasExited) {
+            exitedKeys.delete(key);
+        }
+        pwLog('[presence] registerChild', {
+            key,
+            hasExit: !!exit,
+            exit,
+            wasExited,
+            rect: { w: initialRect.width, h: initialRect.height }
+        });
         children.set(key, {
             element,
             exit,
@@ -77,7 +153,21 @@ export function createAnimatePresenceContext(context) {
      */
     const unregisterChild = (key) => {
         const child = children.get(key);
-        if (!child || !child.exit) {
+        pwLog('[presence] unregisterChild', {
+            key,
+            found: !!child,
+            hasExit: !!child?.exit,
+            exit: child?.exit
+        });
+        // Only process if child was actually registered
+        if (!child) {
+            pwLog('[presence] unregisterChild - child not found, ignoring');
+            return;
+        }
+        // Mark this key as exited so re-entry will animate
+        exitedKeys.add(key);
+        if (!child.exit) {
+            pwLog('[presence] unregisterChild - no exit animation, removing immediately');
             children.delete(key);
             return;
         }
@@ -143,6 +233,10 @@ export function createAnimatePresenceContext(context) {
         }
         clone.setAttribute('data-clone', 'true');
         clone.setAttribute('data-exiting', 'true');
+        pwLog('[presence] clone created', {
+            key,
+            rect: { w: rect.width, h: rect.height, top: rect.top, left: rect.left }
+        });
         parent.appendChild(clone);
         // Merge transitions: default < mergedTransition < exit.transition (last wins)
         const exitObj = (child.exit ?? {});
@@ -151,12 +245,22 @@ export function createAnimatePresenceContext(context) {
         const rawExit = (child.exit ?? {});
         /* trunk-ignore(eslint/@typescript-eslint/no-unused-vars) */
         const { transition: _ignoredTransition, ...exitKeyframes } = rawExit;
+        pwLog('[presence] starting exit animation', {
+            key,
+            exitKeyframes,
+            finalTransition
+        });
+        // Capture the element reference for this specific exit animation
+        // This prevents race conditions where re-entry registers a new element with the same key
+        // before this exit animation completes
+        const exitingElement = child.element;
         // Start exit and track in-flight count
         inFlightExits += 1;
         requestAnimationFrame(() => {
             animate(clone, exitKeyframes, finalTransition)
                 .finished.catch(() => { })
                 .finally(() => {
+                pwLog('[presence] exit animation complete', { key });
                 // Reset elevated styles then remove
                 try {
                     clone.style.zIndex = '';
@@ -165,16 +269,45 @@ export function createAnimatePresenceContext(context) {
                     // ignore
                 }
                 clone.remove();
-                children.delete(key);
+                // Log clone removal and element counts for debugging rapid toggle
+                pwLog('[presence] clone REMOVED from DOM', {
+                    key,
+                    clonesInDOM: document.querySelectorAll('[data-clone="true"]').length,
+                    boxesInDOM: document.querySelectorAll('[data-testid="box"]').length
+                });
+                // Only delete from children map if the current registration is for the SAME element
+                // If a re-entry happened while we were animating, a new element is registered
+                // and we should NOT delete it
+                const currentChild = children.get(key);
+                if (currentChild && currentChild.element === exitingElement) {
+                    children.delete(key);
+                    pwLog('[presence] child deleted from map (same element)', { key });
+                }
+                else {
+                    pwLog('[presence] child NOT deleted (re-entry registered new element)', {
+                        key,
+                        hasCurrentChild: !!currentChild,
+                        isSameElement: currentChild?.element === exitingElement
+                    });
+                }
+                // Log final state
+                pwLog('[presence] element count after exit', {
+                    childrenMapSize: children.size,
+                    inFlightExits: inFlightExits - 1,
+                    clonesInDOM: document.querySelectorAll('[data-clone="true"]').length
+                });
                 inFlightExits -= 1;
                 if (inFlightExits === 0) {
+                    pwLog('[presence] all exits complete, calling onExitComplete');
                     context.onExitComplete?.();
                 }
             });
         });
     };
     return {
-        ...context,
+        initial,
+        shouldAnimateEnter,
+        onExitComplete: context.onExitComplete,
         registerChild,
         updateChildState,
         unregisterChild
@@ -218,11 +351,24 @@ export function setAnimatePresenceContext(context) {
  */
 export function usePresence(key, element, exit, mergedTransition) {
     const context = getAnimatePresenceContext();
+    pwLog('[presence] usePresence called', {
+        key,
+        hasElement: !!element,
+        hasContext: !!context,
+        hasExit: !!exit,
+        exit
+    });
     if (element && context && exit) {
         context.registerChild(key, element, exit, mergedTransition);
         onDestroy(() => {
+            pwLog('[presence] onDestroy triggered', { key });
             context.unregisterChild(key);
         });
     }
+    else {
+        pwLog('[presence] usePresence - skipping registration', {
+            reason: !element ? 'no element' : !context ? 'no context' : 'no exit'
+        });
+    }
 }
 /* c8 ignore end */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "A lightweight animation library for Svelte 5 that provides smooth, hardware-accelerated animations. Features include spring physics, custom easing, and fluid transitions. Built on top of the motion library, it offers a simple API for creating complex animations with minimal code. Perfect for interactive UIs, micro-interactions, and engaging user experiences.",
   "keywords": [
     "svelte",
@@ -53,18 +53,18 @@
     }
   },
   "dependencies": {
-    "motion": "^12.24.7",
-    "motion-dom": "^12.24.3"
+    "motion": "^12.29.2",
+    "motion-dom": "^12.29.2"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
-    "@eslint/compat": "^2.0.0",
+    "@eslint/compat": "^2.0.2",
     "@eslint/js": "^9.39.2",
-    "@playwright/test": "^1.57.0",
+    "@playwright/test": "^1.58.1",
     "@sveltejs/adapter-auto": "^7.0.0",
-    "@sveltejs/kit": "^2.49.3",
+    "@sveltejs/kit": "^2.50.1",
     "@sveltejs/package": "^2.5.7",
-    "@sveltejs/vite-plugin-svelte": "^6.2.2",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@tailwindcss/aspect-ratio": "^0.4.2",
     "@tailwindcss/container-queries": "^0.1.1",
     "@tailwindcss/forms": "^0.5.11",
@@ -72,29 +72,29 @@
     "@tailwindcss/typography": "^0.5.19",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/svelte": "^5.3.1",
-    "@types/node": "^25.0.3",
-    "@vitest/coverage-v8": "^4.0.16",
+    "@types/node": "^25.1.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "concurrently": "^9.2.1",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-import": "2.32.0",
-    "eslint-plugin-svelte": "3.13.1",
+    "eslint-plugin-svelte": "3.14.0",
     "eslint-plugin-unused-imports": "4.3.0",
     "esm-env": "^1.2.2",
-    "globals": "^17.0.0",
+    "globals": "^17.2.0",
     "html-tags": "^5.1.0",
     "html-void-elements": "^3.0.0",
     "husky": "^9.1.7",
     "jsdom": "^27.4.0",
-    "prettier": "^3.7.4",
+    "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
-    "prettier-plugin-sort-json": "^4.1.1",
+    "prettier-plugin-sort-json": "^4.2.0",
     "prettier-plugin-svelte": "^3.4.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
-    "publint": "^0.3.16",
+    "publint": "^0.3.17",
     "runed": "0.37.1",
-    "svelte": "^5.46.1",
-    "svelte-check": "^4.3.5",
+    "svelte": "^5.49.1",
+    "svelte-check": "^4.3.6",
     "svg-tags": "^1.0.0",
     "tailwind-merge": "^3.4.0",
     "tailwind-variants": "^3.2.2",
@@ -102,16 +102,16 @@
     "tailwindcss-animate": "^1.0.7",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.52.0",
-    "vite": "^7.3.0",
-    "vite-tsconfig-paths": "^6.0.3",
-    "vitest": "^4.0.16"
+    "typescript-eslint": "^8.54.0",
+    "vite": "^7.3.1",
+    "vite-tsconfig-paths": "^6.0.5",
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"
   },
   "volta": {
-    "node": "22.21.1"
+    "node": "24.12.0"
   },
   "publishConfig": {
     "access": "public"