@humanspeak/svelte-motion 0.3.3 → 0.3.5

package/dist/components/PresenceChild.svelte

@@ -0,0 +1,124 @@
+<script lang="ts">
+    import type { Snippet } from 'svelte'
+    import {
+        getAnimatePresenceContext,
+        getPresenceDepth,
+        setPresenceChildContext,
+        setPresenceDepth
+    } from '../utils/presence'
+
+    /**
+     * Holds its `children` snippet rendered until the consumer signals the
+     * exit is complete via `safeToRemove()`. Lets a child run its own (non-
+     * `motion.*`) exit animation — fade via CSS transition, canvas effect,
+     * GSAP, etc — while still participating in `AnimatePresence`'s
+     * `onExitComplete` accounting and `mode='wait'` enter blocking.
+     *
+     * Children read `useIsPresent()` or `usePresence()` to observe the
+     * exit-phase flip.
+     *
+     * @prop present Bind to the same boolean that conditionally rendered this
+     *     wrapper. When it flips to `false`, the wrapper holds children
+     *     mounted with `isPresent = false` until `safeToRemove` fires.
+     * @prop children Snippet rendered while present or held.
+     */
+    const { present = true, children } = $props<{
+        present?: boolean
+        children?: Snippet
+    }>()
+
+    const animatePresence = getAnimatePresenceContext()
+    const presenceDepth = getPresenceDepth()
+
+    // Descendants of PresenceChild are no longer at depth 0, so any motion.*
+    // children inside don't trip the "direct children of AnimatePresence need
+    // a key" check in _MotionContainer.
+    if (presenceDepth !== undefined) {
+        setPresenceDepth(presenceDepth + 1)
+    }
+
+    // Three-phase exit lifecycle:
+    //   'idle'      — no exit in progress; render iff `present`.
+    //   'holding'   — `present` flipped false; we're still rendering with
+    //                 isPresent=false, waiting for the consumer to call
+    //                 safeToRemove.
+    //   'completed' — consumer signaled completion. Stop rendering. Returning
+    //                 to 'idle' only happens if `present` flips back to true.
+    type ExitPhase = 'idle' | 'holding' | 'completed'
+    let phase = $state<ExitPhase>('idle')
+    // Track the prior `present` value so we only start an exit on a true→false
+    // transition, not when mounted with `present=false` (a no-op steady state).
+    // Using a closure variable inside $effect.pre below — see initial value
+    // capture there.
+    let prevPresent: boolean | undefined = undefined
+
+    // Each exit start mints a fresh `safeToRemove` closure bound to the cycle
+    // it was minted for. Re-entry / completion invalidates older closures so a
+    // captured-then-late-fired callback (setTimeout, external lib, stray
+    // listener after cleanup) from cycle A cannot complete cycle B.
+    let currentSafeToRemove: () => void = noopSafeToRemove
+
+    function noopSafeToRemove() {}
+
+    function mintSafeToRemove(): () => void {
+        // Closure compares against its own identity (`self`) to detect
+        // whether it's still the active cycle's callback. After re-entry or
+        // completion, `currentSafeToRemove` no longer points at `self`, so
+        // this branch no-ops — a stale capture cannot complete a later exit.
+        const self: () => void = () => {
+            if (currentSafeToRemove !== self || phase !== 'holding') return
+            phase = 'completed'
+            currentSafeToRemove = noopSafeToRemove
+            animatePresence?.notifyExitComplete()
+        }
+        return self
+    }
+
+    const isPresent = $derived(present && phase === 'idle')
+
+    setPresenceChildContext({
+        get isPresent() {
+            return isPresent
+        },
+        get safeToRemove() {
+            return currentSafeToRemove
+        }
+    })
+
+    // $effect.pre runs before DOM updates so the phase transition lands in
+    // the same render pass as the `present` prop flip — otherwise the {#if}
+    // below re-evaluates with stale phase and unmounts/remounts the children,
+    // which (a) breaks any CSS transition the consumer relies on for exit and
+    // (b) makes `bind:this` references go stale.
+    $effect.pre(() => {
+        // Read `present` reactively first; assignments to module locals
+        // happen inside the branches below.
+        const current = present
+        // First run: just record the steady state. Don't fire any exit/enter
+        // signal — there's no transition to react to yet.
+        if (prevPresent === undefined) {
+            prevPresent = current
+            return
+        }
+        if (prevPresent && !current && phase === 'idle') {
+            phase = 'holding'
+            currentSafeToRemove = mintSafeToRemove()
+            animatePresence?.notifyExitStart()
+        } else if (!prevPresent && current && phase === 'holding') {
+            // Re-entry mid-hold cancels the exit accounting. Replacing the
+            // slot invalidates the cycle's `safeToRemove` for any consumer
+            // that captured it.
+            phase = 'idle'
+            currentSafeToRemove = noopSafeToRemove
+            animatePresence?.notifyExitComplete()
+        } else if (!prevPresent && current && phase === 'completed') {
+            // Re-mounted after a previous exit fully completed.
+            phase = 'idle'
+        }
+        prevPresent = current
+    })
+</script>
+
+{#if present || phase === 'holding'}
+    {@render children?.()}
+{/if}

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

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    present?: boolean;
+    children?: Snippet;
+};
+declare const PresenceChild: import("svelte").Component<$$ComponentProps, {}, "">;
+type PresenceChild = ReturnType<typeof PresenceChild>;
+export default PresenceChild;

package/dist/html/_MotionContainer.svelte

@@ -42,6 +42,7 @@
     import { isNativelyFocusable } from '../utils/a11y'
     import {
         getAnimatePresenceContext,
+        getPresenceChildContext,
         getPresenceDepth,
         setPresenceDepth
     } from '../utils/presence'
@@ -127,6 +128,12 @@
 
     // Get presence context to check if we're inside AnimatePresence
     const context = getAnimatePresenceContext()
+    // Inside a <PresenceChild>, the wrapper drives the exit. Skip the
+    // clone-based exit registration on this element so we don't double-fire
+    // (custom exit, then clone of a node the wrapper already let go).
+    // Enter-side coordination (shouldAnimateEnter, mode='wait' blocking)
+    // remains active so the element still slots into the outer presence flow.
+    const inPresenceChild = !!getPresenceChildContext()
 
     // Get layoutId registry (provided by AnimatePresence or a parent LayoutGroup)
     const layoutIdRegistry = getLayoutIdRegistry()
@@ -168,9 +175,8 @@
     )
 
     // Register onDestroy at component level (guaranteed to work in Svelte 5)
-    // usePresence() cannot be called inside $effect because it uses getContext() and onDestroy(),
-    // which must be called during component initialization.
-    if (context) {
+    // — getContext()/onDestroy() must run during component initialization.
+    if (context && !inPresenceChild) {
         onDestroy(() => {
             pwLog('[presence] onDestroy triggered', { key: presenceKey })
             context.unregisterChild(presenceKey)
@@ -181,8 +187,9 @@
     // from the correct visual state. Without this, interrupting an enter animation
     // causes the exit to snap (the element is disconnected before onDestroy, so
     // getAnimations()/commitStyles() can't work at clone time).
+    // Skipped inside <PresenceChild>: the wrapper drives exit, no clone path.
     $effect(() => {
-        if (!(element && context)) return
+        if (!(element && context) || inPresenceChild) return
         let rafId: number
         const capture = () => {
             if (element && element.isConnected && element.getAnimations().length > 0) {
@@ -227,7 +234,7 @@
 
     // Reactively update registration when element/exit/transition props change
     $effect(() => {
-        if (element && context && resolvedExit) {
+        if (element && context && !inPresenceChild && resolvedExit) {
             const filteredExit = filterReducedMotionKeyframes(
                 resolvedExit as Record<string, unknown>,
                 reducedMotion
@@ -241,9 +248,10 @@
         }
     })
 
-    // Update presence context with current state when element is ready and has size
+    // Update presence context with current state when element is ready and has size.
+    // Skipped inside <PresenceChild> — the rect/style snapshot only feeds the clone path.
     $effect(() => {
-        if (!(context && element && isLoaded === 'ready')) return
+        if (!(context && element && isLoaded === 'ready') || inPresenceChild) return
 
         let lastWidth = 0
         let lastHeight = 0

package/dist/index.d.ts

@@ -1,10 +1,13 @@
 import AnimatePresence from './components/AnimatePresence.svelte';
 import MotionConfig from './components/MotionConfig.svelte';
+import PresenceChild from './components/PresenceChild.svelte';
 export { motion } from './motion';
 export { animate, delay, hover, inView, press, resize, scroll, stagger, transform } from 'motion';
 export { anticipate, backIn, backInOut, backOut, circIn, circInOut, circOut, cubicBezier, easeIn, easeInOut, easeOut } from 'motion';
 export { clamp, distance, distance2D, interpolate, mix, pipe, progress, wrap } from 'motion';
 export type { DragAxis, DragConstraints, DragControls, DragInfo, DragTransition, MotionAnimate, MotionInitial, MotionOnDirectionLock, MotionOnDragTransitionEnd, MotionOnInViewEnd, MotionOnInViewStart, MotionTransition, MotionWhileDrag, MotionWhileFocus, MotionWhileHover, MotionWhileInView, MotionWhileTap, ReducedMotionConfig, Variants } from './types';
+export { useAnimate } from './utils/animate.svelte';
+export type { AnimationScope } from './utils/animate.svelte';
 export { useAnimationFrame } from './utils/animationFrame';
 export { useCycle } from './utils/cycle';
 export type { Cycle, CycleState } from './utils/cycle';
@@ -19,6 +22,8 @@ export { useReducedMotion } from './utils/reducedMotion';
 export { useReducedMotionConfig } from './utils/reducedMotionConfig';
 export { useScroll } from './utils/scroll';
 export { useSpring } from './utils/spring';
+export { useIsPresent, usePresence } from './utils/usePresence';
+export type { UsePresenceState } from './utils/usePresence';
 export { useVelocity } from './utils/velocity';
 /**
  * @deprecated Use `styleString` instead for reactive styles with automatic unit handling.
@@ -27,7 +32,7 @@ export { stringifyStyleObject } from './utils/styleObject';
 export { styleString } from './utils/styleObject.svelte';
 export { useTime } from './utils/time';
 export { useTransform } from './utils/transform';
-export { AnimatePresence, MotionConfig };
+export { AnimatePresence, MotionConfig, PresenceChild };
 export { default as MotionA } from './html/A.svelte';
 export { default as MotionAbbr } from './html/Abbr.svelte';
 export { default as MotionAddress } from './html/Address.svelte';

package/dist/index.js

@@ -1,5 +1,6 @@
 import AnimatePresence from './components/AnimatePresence.svelte';
 import MotionConfig from './components/MotionConfig.svelte';
+import PresenceChild from './components/PresenceChild.svelte';
 export { motion } from './motion';
 // Re-export core animation functions from motion
 export { animate, delay, hover, inView, press, resize, scroll, stagger, transform } from 'motion';
@@ -7,6 +8,7 @@ export { animate, delay, hover, inView, press, resize, scroll, stagger, transfor
 export { anticipate, backIn, backInOut, backOut, circIn, circInOut, circOut, cubicBezier, easeIn, easeInOut, easeOut } from 'motion';
 // Re-export utility functions
 export { clamp, distance, distance2D, interpolate, mix, pipe, progress, wrap } from 'motion';
+export { useAnimate } from './utils/animate.svelte';
 export { useAnimationFrame } from './utils/animationFrame';
 export { useCycle } from './utils/cycle';
 export { createDragControls } from './utils/dragControls';
@@ -18,6 +20,7 @@ export { useReducedMotion } from './utils/reducedMotion';
 export { useReducedMotionConfig } from './utils/reducedMotionConfig';
 export { useScroll } from './utils/scroll';
 export { useSpring } from './utils/spring';
+export { useIsPresent, usePresence } from './utils/usePresence';
 export { useVelocity } from './utils/velocity';
 /**
  * @deprecated Use `styleString` instead for reactive styles with automatic unit handling.
@@ -26,7 +29,7 @@ export { stringifyStyleObject } from './utils/styleObject';
 export { styleString } from './utils/styleObject.svelte';
 export { useTime } from './utils/time';
 export { useTransform } from './utils/transform';
-export { AnimatePresence, MotionConfig };
+export { AnimatePresence, MotionConfig, PresenceChild };
 // Named component exports — tree-shakeable alternative to the `motion` object
 export { default as MotionA } from './html/A.svelte';
 export { default as MotionAbbr } from './html/Abbr.svelte';

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

@@ -0,0 +1,66 @@
+import { createScopedAnimate } from 'motion';
+import type { AnimationPlaybackControlsWithThen } from 'motion-dom';
+/**
+ * The scope returned by {@link useAnimate}. Functions as a Svelte 5
+ * attachment — pass it as `{@attach scope}` on the parent element so the
+ * scoped `animate` function can resolve string selectors against it.
+ *
+ * Mirrors framer-motion's `AnimationScope`. `current` is hydrated once the
+ * attachment runs; `animations` tracks every in-flight animation started
+ * through the scoped `animate` so they can be stopped together when the
+ * element detaches.
+ */
+export type AnimationScope<T extends Element = HTMLElement> = ((node: T) => () => void) & {
+    /** The parent element, populated when the attachment fires. `undefined` before mount or after detach. */
+    current: T | undefined;
+    /** Animations currently scoped to this element. */
+    animations: AnimationPlaybackControlsWithThen[];
+};
+/**
+ * Imperative animation API mirroring framer-motion's `useAnimate`. Returns a
+ * tuple `[scope, animate]`:
+ *
+ * - `scope` is a Svelte 5 attachment: spread it on the parent element with
+ *   `{@attach scope}`. Once mounted, `scope.current` is the element and
+ *   `animate('selector', ...)` resolves selectors against it.
+ * - `animate(target, keyframes, transition)` accepts the same overloads as
+ *   motion's standalone `animate` — strings, elements, motion values, and
+ *   sequences.
+ *
+ * When the attached element detaches, every animation started through the
+ * scoped `animate` is stopped and `scope.animations` is cleared.
+ *
+ * `animate` ignores calls before the attachment fires — `scope.current` is
+ * still `undefined`, and motion throws when asked to query selectors against
+ * a missing root. Trigger animations from user events or `$effect` after
+ * mount.
+ *
+ * @template T The parent element type. Defaults to `HTMLElement`.
+ * @returns A `[scope, animate]` tuple.
+ * @see https://motion.dev/docs/react-use-animate
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useAnimate } from '@humanspeak/svelte-motion'
+ *
+ *   const [scope, animate] = useAnimate()
+ *
+ *   const run = () =>
+ *     animate(
+ *       [
+ *         ['li', { opacity: 1, x: 0 }, { delay: stagger(0.1) }],
+ *         ['button', { scale: 1.05 }, { at: '-0.2' }]
+ *       ]
+ *     )
+ * </script>
+ *
+ * <ul {@attach scope}>
+ *   <li>One</li>
+ *   <li>Two</li>
+ *   <li>Three</li>
+ * </ul>
+ * <button onclick={run}>Animate</button>
+ * ```
+ */
+export declare const useAnimate: <T extends Element = HTMLElement>() => [AnimationScope<T>, ReturnType<typeof createScopedAnimate>];

package/dist/utils/animate.svelte.js

@@ -0,0 +1,66 @@
+import { createScopedAnimate } from 'motion';
+/**
+ * Imperative animation API mirroring framer-motion's `useAnimate`. Returns a
+ * tuple `[scope, animate]`:
+ *
+ * - `scope` is a Svelte 5 attachment: spread it on the parent element with
+ *   `{@attach scope}`. Once mounted, `scope.current` is the element and
+ *   `animate('selector', ...)` resolves selectors against it.
+ * - `animate(target, keyframes, transition)` accepts the same overloads as
+ *   motion's standalone `animate` — strings, elements, motion values, and
+ *   sequences.
+ *
+ * When the attached element detaches, every animation started through the
+ * scoped `animate` is stopped and `scope.animations` is cleared.
+ *
+ * `animate` ignores calls before the attachment fires — `scope.current` is
+ * still `undefined`, and motion throws when asked to query selectors against
+ * a missing root. Trigger animations from user events or `$effect` after
+ * mount.
+ *
+ * @template T The parent element type. Defaults to `HTMLElement`.
+ * @returns A `[scope, animate]` tuple.
+ * @see https://motion.dev/docs/react-use-animate
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useAnimate } from '@humanspeak/svelte-motion'
+ *
+ *   const [scope, animate] = useAnimate()
+ *
+ *   const run = () =>
+ *     animate(
+ *       [
+ *         ['li', { opacity: 1, x: 0 }, { delay: stagger(0.1) }],
+ *         ['button', { scale: 1.05 }, { at: '-0.2' }]
+ *       ]
+ *     )
+ * </script>
+ *
+ * <ul {@attach scope}>
+ *   <li>One</li>
+ *   <li>Two</li>
+ *   <li>Three</li>
+ * </ul>
+ * <button onclick={run}>Animate</button>
+ * ```
+ */
+export const useAnimate = () => {
+    const scope = ((node) => {
+        scope.current = node;
+        return () => {
+            for (const animation of scope.animations) {
+                animation.stop();
+            }
+            scope.animations.length = 0;
+            scope.current = undefined;
+        };
+    });
+    scope.current = undefined;
+    scope.animations = [];
+    const animate = createScopedAnimate({
+        scope: scope
+    });
+    return [scope, animate];
+};

package/dist/utils/presence.d.ts

@@ -35,6 +35,19 @@ export type AnimatePresenceContext = {
     updateChildAnimatedStyle: (key: string, opacity: string, transform: string) => void;
     /** Unregister a child. If it has an exit, clone and animate it out. */
     unregisterChild: (key: string) => void;
+    /**
+     * @internal Used by `PresenceChild` to participate in the same exit
+     * accounting as the clone-based motion-element exit path. Increments the
+     * in-flight exit counter and applies mode='wait' enter blocking. Not
+     * intended for direct consumer use.
+     */
+    notifyExitStart: () => void;
+    /**
+     * @internal Pairs with `notifyExitStart`. Decrements the in-flight exit
+     * counter, fires `onExitComplete` once it reaches zero, and unblocks
+     * pending enters in mode='wait'. Not intended for direct consumer use.
+     */
+    notifyExitComplete: () => void;
 };
 /**
  * Create a new `AnimatePresence` context instance.
@@ -113,20 +126,34 @@ export declare const getPresenceDepth: () => number | undefined;
  */
 export declare const setPresenceDepth: (depth: number) => void;
 /**
- * Hook used by motion elements to participate in presence.
- * Registers the element and ensures its exit animation runs on teardown.
+ * Per-`PresenceChild` Svelte context payload. Read by the `useIsPresent` and
+ * `usePresence` hooks (and consulted by motion elements so they can opt out of
+ * the outer `AnimatePresence` clone path when a `PresenceChild` is driving
+ * the exit themselves).
  *
- * Note: Svelte lifecycle wrapper - ignored for coverage.
+ * `isPresent` is exposed as a getter so consumers see live updates as the
+ * wrapper toggles between mounted, exiting, and re-entered states.
  */
+export type PresenceChildContext = {
+    /** Reactive flag — `true` while present, `false` once the exit hold begins. */
+    readonly isPresent: boolean;
+    /**
+     * Signal that the consumer's exit work is complete. Triggers actual
+     * unmount and decrements the parent `AnimatePresenceContext` exit count.
+     * Idempotent and versioned (calls from a canceled exit cycle are no-ops).
+     */
+    safeToRemove: () => void;
+};
 /**
- * Hook used by motion elements to participate in presence.
+ * Get the nearest `PresenceChild` context from Svelte component context, or
+ * `undefined` if the caller is not wrapped in one.
  *
- * Registers the element with the presence context and guarantees that the
- * exit animation is scheduled on teardown.
+ * Note: Trivial wrapper - ignored for coverage.
+ */
+export declare const getPresenceChildContext: () => PresenceChildContext | undefined;
+/**
+ * Install a `PresenceChild` context for descendants.
  *
- * @param key Unique identifier for the presence child.
- * @param element The DOM element to track.
- * @param exit The exit keyframes definition.
- * @param mergedTransition The element's merged transition for precedence.
+ * Note: Trivial wrapper - ignored for coverage.
  */
-export declare const usePresence: (key: string, element: HTMLElement | null, exit: MotionExit, mergedTransition?: MotionTransition) => void;
+export declare const setPresenceChildContext: (context: PresenceChildContext) => void;

package/dist/utils/presence.js

@@ -1,7 +1,7 @@
 import { mergeTransitions } from './animation';
 import { pwLog } from './log';
 import { animate } from 'motion';
-import { getContext, onDestroy, setContext } from 'svelte';
+import { getContext, setContext } from 'svelte';
 /**
  * Context key for `AnimatePresence`.
  *
@@ -195,6 +195,66 @@ export const createAnimatePresenceContext = (context) => {
     const children = new Map();
     // Track number of in-flight exit animations to invoke onExitComplete once
     let inFlightExits = 0;
+    /**
+     * Begin tracking an exit.
+     *
+     * Increments the `inFlightExits` counter and, in `mode='wait'`, raises the
+     * `enterBlocked` flag so sibling motion-element enters defer until every
+     * exit reports back via {@link finishExit}. Shared by the clone-based exit
+     * path in {@link unregisterChild} and the user-driven `PresenceChild` hold.
+     *
+     * Must be paired with exactly one {@link finishExit} call per invocation.
+     *
+     * @returns void
+     * @example
+     * ```ts
+     * // unregisterChild (clone path)
+     * startExit()
+     * requestAnimationFrame(() => {
+     *   animate(clone, exitKeyframes, transition).finished.finally(finishExit)
+     * })
+     *
+     * // PresenceChild (user-driven path) — exposed as `notifyExitStart`
+     * presenceContext.notifyExitStart()
+     * // ... later, on transitionend or user signal ...
+     * presenceContext.notifyExitComplete()
+     * ```
+     */
+    const startExit = () => {
+        if (mode === 'wait') {
+            enterBlocked = true;
+        }
+        inFlightExits += 1;
+    };
+    /**
+     * Mark an exit as finished.
+     *
+     * Decrements the `inFlightExits` counter. When the count reaches zero,
+     * fires the consumer's `onExitComplete` callback and, in `mode='wait'`,
+     * lowers `enterBlocked` plus notifies any deferred-enter callbacks
+     * registered via {@link onEnterUnblocked}.
+     *
+     * Must be called exactly once per matching {@link startExit}; double-fires
+     * underflow the counter and can permanently mis-route subsequent exits.
+     *
+     * @returns void
+     * @example
+     * ```ts
+     * startExit()
+     * // ... exit work ...
+     * finishExit() // fires onExitComplete if the last exit, unblocks waiters
+     * ```
+     */
+    const finishExit = () => {
+        inFlightExits -= 1;
+        if (inFlightExits === 0) {
+            context.onExitComplete?.();
+            if (mode === 'wait' && enterBlocked) {
+                enterBlocked = false;
+                notifyEnterUnblocked();
+            }
+        }
+    };
     /**
      * Register a child element and snapshot its initial rect/styles.
      */
@@ -275,11 +335,6 @@ export const createAnimatePresenceContext = (context) => {
             children.delete(key);
             return;
         }
-        // For mode='wait': block new enters while exit is in progress
-        if (mode === 'wait') {
-            enterBlocked = true;
-            pwLog('[presence] mode=wait: blocking enters during exit');
-        }
         const rect = child.lastRect;
         const computed = child.lastComputedStyle;
         // For sync/wait, preserve layout by inserting a hidden placeholder.
@@ -415,8 +470,8 @@ export const createAnimatePresenceContext = (context) => {
         // 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;
+        // Start exit and track in-flight count (handles wait-mode blocking)
+        startExit();
         requestAnimationFrame(() => {
             animate(clone, exitKeyframes, finalTransition)
                 .finished.catch(() => { })
@@ -459,17 +514,7 @@ export const createAnimatePresenceContext = (context) => {
                     inFlightExits: inFlightExits - 1,
                     clonesInDOM: document.querySelectorAll('[data-clone="true"]').length
                 });
-                inFlightExits -= 1;
-                if (inFlightExits === 0) {
-                    pwLog('[presence] all exits complete, calling onExitComplete');
-                    context.onExitComplete?.();
-                    // For mode='wait': unblock enters now that all exits are complete
-                    if (mode === 'wait' && enterBlocked) {
-                        enterBlocked = false;
-                        pwLog('[presence] mode=wait: unblocking enters, notifying callbacks');
-                        notifyEnterUnblocked();
-                    }
-                }
+                finishExit();
             });
         });
     };
@@ -483,7 +528,9 @@ export const createAnimatePresenceContext = (context) => {
         registerChild,
         updateChildState,
         updateChildAnimatedStyle,
-        unregisterChild
+        unregisterChild,
+        notifyExitStart: startExit,
+        notifyExitComplete: finishExit
     };
 };
 /**
@@ -547,44 +594,23 @@ export const getPresenceDepth = () => getContext(PRESENCE_DEPTH_CONTEXT);
 export const setPresenceDepth = (depth) => {
     setContext(PRESENCE_DEPTH_CONTEXT, depth);
 };
+const PRESENCE_CHILD_CONTEXT = Symbol('presence-child-context');
 /**
- * Hook used by motion elements to participate in presence.
- * Registers the element and ensures its exit animation runs on teardown.
+ * Get the nearest `PresenceChild` context from Svelte component context, or
+ * `undefined` if the caller is not wrapped in one.
  *
- * Note: Svelte lifecycle wrapper - ignored for coverage.
+ * Note: Trivial wrapper - ignored for coverage.
  */
-/* c8 ignore start */
+/* c8 ignore next 3 */
+export const getPresenceChildContext = () => {
+    return getContext(PRESENCE_CHILD_CONTEXT);
+};
 /**
- * Hook used by motion elements to participate in presence.
- *
- * Registers the element with the presence context and guarantees that the
- * exit animation is scheduled on teardown.
+ * Install a `PresenceChild` context for descendants.
  *
- * @param key Unique identifier for the presence child.
- * @param element The DOM element to track.
- * @param exit The exit keyframes definition.
- * @param mergedTransition The element's merged transition for precedence.
+ * Note: Trivial wrapper - ignored for coverage.
  */
-export const 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 next 3 */
+export const setPresenceChildContext = (context) => {
+    setContext(PRESENCE_CHILD_CONTEXT, context);
 };
-/* c8 ignore end */

package/dist/utils/usePresence.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Tuple returned by {@link usePresence}, matching framer-motion's shape:
+ * `[true, null]` while present (or when not inside a `PresenceChild`), and
+ * `[false, () => void]` after the wrapper enters its exit hold.
+ */
+export type UsePresenceState = [true, null] | [false, () => void];
+/**
+ * Returns whether the calling component is currently present in its parent
+ * `<PresenceChild>`. While the wrapper holds the component for an exit, this
+ * flips to `false` so the consumer can branch (render different markup, run
+ * a custom exit animation, etc.).
+ *
+ * Outside of a `<PresenceChild>` always returns `true`.
+ *
+ * Reactivity note: the boolean tracks the wrapper's state and updates in
+ * Svelte 5 reactive contexts (`$derived`, `$effect`, template). For non-
+ * reactive snapshots, prefer `usePresence()` which exposes the same state
+ * alongside the `safeToRemove` callback.
+ *
+ * @returns `true` while present, `false` while exiting.
+ * @see https://motion.dev/docs/react-use-is-present
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useIsPresent } from '@humanspeak/svelte-motion'
+ *   const isPresent = $derived(useIsPresent())
+ * </script>
+ * <div class:exiting={!isPresent}>{isPresent ? 'live' : 'goodbye'}</div>
+ * ```
+ */
+export declare const useIsPresent: () => boolean;
+/**
+ * Returns `[isPresent, safeToRemove]`. `isPresent` reflects the wrapper's
+ * presence state; `safeToRemove` is the callback to invoke once a custom exit
+ * animation finishes. Calling it triggers the actual unmount and decrements
+ * the parent `<AnimatePresence>` exit-completion count.
+ *
+ * Outside of a `<PresenceChild>` returns `[true, null]` — the consumer is
+ * effectively always present and there is nothing to safely remove.
+ *
+ * `safeToRemove` is idempotent and versioned: a stale callback from a
+ * canceled exit cycle (re-entry before the consumer signaled completion) is
+ * a no-op.
+ *
+ * @returns `[true, null]` while present (or outside any `PresenceChild`),
+ *     `[false, () => void]` while the wrapper holds the component for exit.
+ * @see https://motion.dev/docs/react-use-presence
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { usePresence } from '@humanspeak/svelte-motion'
+ *
+ *   let node: HTMLElement | undefined = $state()
+ *   const presence = $derived(usePresence())
+ *
+ *   $effect(() => {
+ *     const [isPresent, safeToRemove] = presence
+ *     if (isPresent || !node) return
+ *     const onEnd = () => safeToRemove()
+ *     node.addEventListener('transitionend', onEnd, { once: true })
+ *     node.classList.add('exiting')
+ *     return () => node?.removeEventListener('transitionend', onEnd)
+ *   })
+ * </script>
+ *
+ * <div bind:this={node}>…</div>
+ * ```
+ */
+export declare const usePresence: () => UsePresenceState;

package/dist/utils/usePresence.js

@@ -0,0 +1,74 @@
+import { getPresenceChildContext } from './presence';
+/**
+ * Returns whether the calling component is currently present in its parent
+ * `<PresenceChild>`. While the wrapper holds the component for an exit, this
+ * flips to `false` so the consumer can branch (render different markup, run
+ * a custom exit animation, etc.).
+ *
+ * Outside of a `<PresenceChild>` always returns `true`.
+ *
+ * Reactivity note: the boolean tracks the wrapper's state and updates in
+ * Svelte 5 reactive contexts (`$derived`, `$effect`, template). For non-
+ * reactive snapshots, prefer `usePresence()` which exposes the same state
+ * alongside the `safeToRemove` callback.
+ *
+ * @returns `true` while present, `false` while exiting.
+ * @see https://motion.dev/docs/react-use-is-present
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useIsPresent } from '@humanspeak/svelte-motion'
+ *   const isPresent = $derived(useIsPresent())
+ * </script>
+ * <div class:exiting={!isPresent}>{isPresent ? 'live' : 'goodbye'}</div>
+ * ```
+ */
+export const useIsPresent = () => {
+    const context = getPresenceChildContext();
+    return context ? context.isPresent : true;
+};
+/**
+ * Returns `[isPresent, safeToRemove]`. `isPresent` reflects the wrapper's
+ * presence state; `safeToRemove` is the callback to invoke once a custom exit
+ * animation finishes. Calling it triggers the actual unmount and decrements
+ * the parent `<AnimatePresence>` exit-completion count.
+ *
+ * Outside of a `<PresenceChild>` returns `[true, null]` — the consumer is
+ * effectively always present and there is nothing to safely remove.
+ *
+ * `safeToRemove` is idempotent and versioned: a stale callback from a
+ * canceled exit cycle (re-entry before the consumer signaled completion) is
+ * a no-op.
+ *
+ * @returns `[true, null]` while present (or outside any `PresenceChild`),
+ *     `[false, () => void]` while the wrapper holds the component for exit.
+ * @see https://motion.dev/docs/react-use-presence
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { usePresence } from '@humanspeak/svelte-motion'
+ *
+ *   let node: HTMLElement | undefined = $state()
+ *   const presence = $derived(usePresence())
+ *
+ *   $effect(() => {
+ *     const [isPresent, safeToRemove] = presence
+ *     if (isPresent || !node) return
+ *     const onEnd = () => safeToRemove()
+ *     node.addEventListener('transitionend', onEnd, { once: true })
+ *     node.classList.add('exiting')
+ *     return () => node?.removeEventListener('transitionend', onEnd)
+ *   })
+ * </script>
+ *
+ * <div bind:this={node}>…</div>
+ * ```
+ */
+export const usePresence = () => {
+    const context = getPresenceChildContext();
+    if (!context)
+        return [true, null];
+    return context.isPresent ? [true, null] : [false, context.safeToRemove];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "A Framer Motion-compatible 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",