@humanspeak/svelte-motion 0.3.4 → 0.3.6

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,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';
 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';
@@ -21,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.
@@ -29,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';
@@ -19,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.
@@ -27,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/drag.js

@@ -1,4 +1,4 @@
-import { pwLog, pwWarn } from './log';
+import { isPlaywrightEnv, pwLog, pwWarn } from './log';
 /**
  * Drag utilities
  *
@@ -16,7 +16,7 @@ import { pwLog, pwWarn } from './log';
  * - For nested drags, set `propagation` as needed to avoid parent-child contention.
  */
 import { isDomElement } from './dom';
-import { applyConstraints as applyFloatConstraints } from './dragMath';
+import { applyConstraints as applyFloatConstraints, parseMatrixTranslate } from './dragMath';
 import { deriveBoundaryPhysics } from './dragParams';
 import { computeHoverBaseline, splitHoverDefinition } from './hover';
 import { createInertiaToBoundary } from './inertia';
@@ -87,6 +87,53 @@ export const applyElastic = (value, min, max, elastic) => {
 };
 /** Prefer high-resolution time in browser; fall back for SSR/tests. */
 const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+/** Sample windows for release-velocity inference (matches motion-dom values). */
+const MAX_VELOCITY_DELTA_MS = 30;
+const MIN_VELOCITY_INTERVAL_MS = 5;
+/**
+ * Compute the release velocity for momentum from a pointer-history window.
+ *
+ * Mirrors motion-dom: walks back from the newest sample, including only
+ * samples within `MAX_VELOCITY_DELTA_MS` (30 ms) of newest, then divides
+ * the displacement by the elapsed time. Returns 0 if the newest sample is
+ * stale, the window has fewer than two samples, or the oldest-newest span
+ * is shorter than `MIN_VELOCITY_INTERVAL_MS` (5 ms — sub-frame).
+ *
+ * @param history Recent pointer samples ordered oldest → newest. Each
+ *   sample is `{ x, y, t }` where `t` is `performance.now()` ms.
+ * @param nowMs Current `performance.now()` ms — used to discard a stale
+ *   newest sample (finger lifted after a pause).
+ * @returns Inferred release velocity in pixels per second on each axis.
+ * @example
+ *   const v = computeReleaseVelocity(
+ *       [{ x: 0, y: 0, t: 1000 }, { x: 20, y: 0, t: 1020 }],
+ *       1020
+ *   )
+ *   // v ≈ { x: 1000, y: 0 } — 20 px over 20 ms → 1000 px/s
+ */
+const computeReleaseVelocity = (history, nowMs) => {
+    if (history.length < 2)
+        return { x: 0, y: 0 };
+    const newest = history[history.length - 1];
+    if (nowMs - newest.t > MAX_VELOCITY_DELTA_MS)
+        return { x: 0, y: 0 };
+    let oldestIdx = history.length - 1;
+    for (let i = history.length - 2; i >= 0; i--) {
+        if (newest.t - history[i].t > MAX_VELOCITY_DELTA_MS)
+            break;
+        oldestIdx = i;
+    }
+    if (oldestIdx === history.length - 1)
+        return { x: 0, y: 0 };
+    const oldest = history[oldestIdx];
+    const dtMs = newest.t - oldest.t;
+    if (dtMs < MIN_VELOCITY_INTERVAL_MS)
+        return { x: 0, y: 0 };
+    return {
+        x: ((newest.x - oldest.x) / dtMs) * 1000,
+        y: ((newest.y - oldest.y) / dtMs) * 1000
+    };
+};
 /**
  * Attach a drag gesture to an element.
  *
@@ -184,25 +231,21 @@ export const attachDrag = (el, opts) => {
             applied.x = x;
         if ('y' in payload)
             applied.y = y;
-        // Verify it's actually applied; if not, retry once (Playwright visibility only)
-        const cs = getComputedStyle(el);
-        let actualTransform = cs.transform;
-        if (actualTransform === 'none' || !actualTransform.includes('matrix')) {
-            pwWarn('⚠️ setXY transform missing; retrying write', {
-                x,
-                y,
-                transform: actualTransform
-            });
-            animate(el, ('x' in payload || 'y' in payload ? payload : { x, y }), {
-                duration: 0
-            });
-            actualTransform = getComputedStyle(el).transform;
+        // Playwright-only sanity check: confirm the transform actually
+        // landed on the element and retry once if not. Forces a style
+        // recalc via getComputedStyle, so we gate it behind the same
+        // playwright env flag pwLog uses so it never fires in prod.
+        if (isPlaywrightEnv()) {
+            let actualTransform = getComputedStyle(el).transform;
             if (actualTransform === 'none' || !actualTransform.includes('matrix')) {
-                pwWarn('⚠️ setXY second attempt still missing transform', {
-                    x,
-                    y,
-                    transform: actualTransform
-                });
+                pwWarn('⚠️ setXY transform missing; retrying write', { x, y });
+                animate(el, ('x' in payload || 'y' in payload
+                    ? payload
+                    : { x, y }), { duration: 0 });
+                actualTransform = getComputedStyle(el).transform;
+                if (actualTransform === 'none' || !actualTransform.includes('matrix')) {
+                    pwWarn('⚠️ setXY second attempt still missing transform', { x, y });
+                }
             }
         }
     };
@@ -404,22 +447,28 @@ export const attachDrag = (el, opts) => {
         });
         if (!dragging)
             return;
-        finishDrag(e);
+        // Pointer was preempted (gesture-nav, palm rejection, scroll
+        // takeover). User did not release intentionally — skip the
+        // inertia/momentum path and force a no-momentum settle so the
+        // card clamps back into constraints without flinging.
+        finishDrag(e, true);
     };
     /**
      * Finish a drag:
      * - If momentum is enabled, decay towards a clamped target with exponential easing
      * - Otherwise, animate back to a clamped position (or origin), then sync `applied`
      */
-    const finishDrag = (e) => {
+    const finishDrag = (e, cancelled = false) => {
         dragging = false;
+        velocity = computeReleaseVelocity(history, now());
         pwLog('[drag] finish', {
             el: EL_ID,
             lastPoint,
             startPoint,
             origin,
             applied,
-            momentum
+            momentum,
+            velocity
         });
         try {
             if ('releasePointerCapture' in el && typeof e.pointerId === 'number')
@@ -434,8 +483,10 @@ export const attachDrag = (el, opts) => {
         window.removeEventListener('pointermove', onPointerMove);
         window.removeEventListener('pointerup', onPointerUp);
         window.removeEventListener('pointercancel', onPointerCancel);
-        // Momentum/inertia with boundary handoff: inertia until crossing, then spring to boundary
-        if (momentum) {
+        // Momentum/inertia with boundary handoff: inertia until crossing, then spring to boundary.
+        // Pointer-cancel forces a no-momentum settle (clamp into constraints, no fling) since the
+        // gesture was preempted rather than intentionally released.
+        if (momentum && !cancelled) {
             pwLog('🚀 STARTING MOMENTUM', {
                 velocityX: velocity.x,
                 velocityY: velocity.y,
@@ -454,6 +505,18 @@ export const attachDrag = (el, opts) => {
                     ...(applyX ? { x: 0 } : {}),
                     ...(applyY ? { y: 0 } : {})
                 }, (mergedTransition ?? {}));
+                // Cancel hook so re-grab / controls.stop() interrupts the snap.
+                stopInertia = () => {
+                    pwLog('❌ snapToOrigin cancelled');
+                    controls.stop?.();
+                    // Sync applied to wherever the snap reached so the next drag origin is correct.
+                    const { tx, ty } = parseMatrixTranslate(getComputedStyle(el).transform);
+                    if (applyX)
+                        applied.x = tx;
+                    if (applyY)
+                        applied.y = ty;
+                    stopInertia = null;
+                };
                 Promise.resolve(controls.finished)
                     .then(() => {
                     // Sync internal applied transform so next drag uses the correct origin
@@ -465,26 +528,31 @@ export const attachDrag = (el, opts) => {
                         el: EL_ID,
                         applied
                     });
+                    if (stopInertia)
+                        stopInertia = null;
                 })
                     .catch(() => { })
                     .finally(() => opts.callbacks?.onTransitionEnd?.());
                 return;
             }
-            // If no constraints, disable boundary springs by setting finite but very wide bounds
+            // Boundary min/max anchor to `constraintsBase` (the absolute
+            // pixel-constraint origin) so the inertia handoff snaps to the
+            // same edge pointermove's elastic clamping uses — not to a
+            // per-drag-shifted `origin` that would drift across drags.
             const noConstraints = !constraints;
             const huge = 1e6;
             const minX = noConstraints
                 ? applied.x - huge
-                : origin.x + (constraints?.left ?? -Infinity);
+                : constraintsBase.x + (constraints?.left ?? -Infinity);
             const maxX = noConstraints
                 ? applied.x + huge
-                : origin.x + (constraints?.right ?? Infinity);
+                : constraintsBase.x + (constraints?.right ?? Infinity);
             const minY = noConstraints
                 ? applied.y - huge
-                : origin.y + (constraints?.top ?? -Infinity);
+                : constraintsBase.y + (constraints?.top ?? -Infinity);
             const maxY = noConstraints
                 ? applied.y + huge
-                : origin.y + (constraints?.bottom ?? Infinity);
+                : constraintsBase.y + (constraints?.bottom ?? Infinity);
             const { timeConstantMs, restDelta, restSpeed, bounceStiffness, bounceDamping } = deriveBoundaryPhysics(elastic, opts.transition);
             pwLog('⚙️ boundary-physics', {
                 timeConstantMs,
@@ -500,6 +568,10 @@ export const attachDrag = (el, opts) => {
             // Respect direction lock on release: only animate the locked axis
             const applyX = (axis === true || axis === 'x') && lockAxis !== 'y';
             const applyY = (axis === true || axis === 'y') && lockAxis !== 'x';
+            // Element-ref constraints can resize / reflow during inertia.
+            // Pixel constraints never change once set. We re-resolve only
+            // for element-ref each frame in the rAF loop below.
+            const isElementRefConstraint = isDomElement(opts.constraints);
             const stepX = applyX
                 ? createInertiaToBoundary({ value: applied.x, velocity: velocity.x }, { min: minX, max: maxX }, { timeConstantMs, restDelta, restSpeed, bounceStiffness, bounceDamping })
                 : null;
@@ -519,9 +591,27 @@ export const attachDrag = (el, opts) => {
                 // Use the precomputed step functions (built once per release)
                 const rx = stepX ? stepX(t) : { value: applied.x, done: true };
                 const ry = stepY ? stepY(t) : { value: applied.y, done: true };
-                // Preserve non-animated axis exactly; don't write y during x-only drags, or vice versa
-                const nextX = rx.value;
-                const nextY = (axis === true || axis === 'y') && lockAxis !== 'x' ? ry.value : applied.y;
+                // Element-ref constraints may have resized / reflowed since
+                // the steppers were built. Re-resolve and clamp the output
+                // so the card never lands outside the now-current container
+                // even if its boundary moved mid-spring. Pixel constraints
+                // don't move so we skip the work.
+                let nextX = rx.value;
+                let nextY = (axis === true || axis === 'y') && lockAxis !== 'x' ? ry.value : applied.y;
+                if (isElementRefConstraint) {
+                    const freshConstraints = resolveConstraints(el, opts.constraints);
+                    if (freshConstraints) {
+                        constraintsBase = { x: applied.x, y: applied.y };
+                        const freshMinX = constraintsBase.x + (freshConstraints.left ?? -Infinity);
+                        const freshMaxX = constraintsBase.x + (freshConstraints.right ?? Infinity);
+                        const freshMinY = constraintsBase.y + (freshConstraints.top ?? -Infinity);
+                        const freshMaxY = constraintsBase.y + (freshConstraints.bottom ?? Infinity);
+                        if (applyX)
+                            nextX = Math.max(freshMinX, Math.min(freshMaxX, nextX));
+                        if (applyY)
+                            nextY = Math.max(freshMinY, Math.min(freshMaxY, nextY));
+                    }
+                }
                 setXY(nextX, nextY);
                 if (frameCount <= 3 || frameCount % 10 === 0) {
                     pwLog(`🔄 FRAME ${frameCount}`, {
@@ -537,15 +627,19 @@ export const attachDrag = (el, opts) => {
                 if ((rx.done || !stepX) && (ry.done || !stepY)) {
                     pwLog('✅ REST REACHED', {
                         frameCount,
-                        finalX: rx.value,
-                        finalY: ry.value,
+                        finalX: nextX,
+                        finalY: nextY,
                         timeConstantMs,
                         restDelta,
                         restSpeed
                     });
-                    // Ensure applied is synced to final values (setXY should have done this, but be explicit)
-                    const finalX = stepX ? rx.value : applied.x;
-                    const finalY = stepY ? ry.value : applied.y;
+                    // Sync `applied` from the post-clamp frame values
+                    // (nextX/nextY), not the raw stepper output. When
+                    // element-ref constraints clamped this frame, raw
+                    // rx.value sits outside the visible bounds and would
+                    // desync the next-drag origin from the rendered transform.
+                    const finalX = stepX ? nextX : applied.x;
+                    const finalY = stepY ? nextY : applied.y;
                     if (axis === true || axis === 'x')
                         applied.x = finalX;
                     if (axis === true || axis === 'y')
@@ -560,14 +654,12 @@ export const attachDrag = (el, opts) => {
             stopInertia = () => {
                 pwLog('❌ MOMENTUM CANCELLED');
                 running = false;
-                // Sync applied to the current visual position so the next drag starts correctly
-                // Use the last computed values from the steppers if available
-                const finalX = stepX ? stepX(now() - startTs).value : applied.x;
-                const finalY = stepY ? stepY(now() - startTs).value : applied.y;
-                if (axis === true || axis === 'x')
-                    applied.x = finalX;
-                if (axis === true || axis === 'y')
-                    applied.y = finalY;
+                // `applied` is already in sync with the last frame rendered
+                // by the rAF loop (setXY updates it on every frame). We
+                // intentionally do NOT call stepX/stepY again here —
+                // they're stateful (mutate lastT/springX/springV) and an
+                // extra call advances them past the visible state, leaving
+                // applied slightly out of sync with what the user sees.
                 pwLog('[drag] inertia cancelled → sync applied', {
                     el: EL_ID,
                     applied: { x: applied.x, y: applied.y }
@@ -624,6 +716,17 @@ export const attachDrag = (el, opts) => {
             const settleTransition = elastic === 0 ? { duration: 0 } : (mergedTransition ?? {});
             // Animate with the merged transition so the settle feels consistent with other motion
             const controls = animate(el, { ...(applyX ? { x } : {}), ...(applyY ? { y } : {}) }, settleTransition);
+            // Cancel hook so re-grab interrupts the settle animation cleanly.
+            stopInertia = () => {
+                pwLog('❌ settle (no momentum) cancelled');
+                controls.stop?.();
+                const { tx, ty } = parseMatrixTranslate(getComputedStyle(el).transform);
+                if (applyX)
+                    applied.x = tx;
+                if (applyY)
+                    applied.y = ty;
+                stopInertia = null;
+            };
             // Fire transition end once settled
             Promise.resolve(controls.finished)
                 .then(() => {
@@ -636,6 +739,8 @@ export const attachDrag = (el, opts) => {
                     el: EL_ID,
                     applied
                 });
+                if (stopInertia)
+                    stopInertia = null;
             })
                 .catch(() => { })
                 .finally(() => opts.callbacks?.onTransitionEnd?.());
@@ -643,10 +748,12 @@ export const attachDrag = (el, opts) => {
         opts.callbacks?.onEnd?.(e, computeInfo());
         endWhileDrag();
     };
-    // Wire dragControls
+    // Wire dragControls. The cancelInertia thunk reads the *current*
+    // stopInertia at call time so the latest in-flight animation is
+    // targeted (stopInertia is re-assigned per finishDrag).
     if (opts.controls) {
         const internal = opts.controls;
-        internal._bind?.(el, beginDrag);
+        internal._bind?.(el, beginDrag, () => stopInertia?.());
         pwLog('[drag] controls bound', { el: EL_ID });
     }
     el.addEventListener('pointerdown', onPointerDown);

package/dist/utils/dragMath.d.ts

@@ -34,3 +34,21 @@ export type ConstraintElastic = {
  * ```
  */
 export declare const applyConstraints: (point: number, range: ConstraintRange, elastic?: ConstraintElastic) => number;
+/**
+ * Parse a CSS `matrix(a, b, c, d, tx, ty)` string into translate components.
+ *
+ * Used to read the rendered translate after Motion writes inline transforms
+ * during drag-cancel hooks.
+ *
+ * @param transform The computed `transform` style — typically `'none'` or
+ *   `'matrix(1, 0, 0, 1, 10, 20)'`. `matrix3d(...)` is not supported.
+ * @returns The 2D translate components `{ tx, ty }`. Defaults to
+ *   `{ tx: 0, ty: 0 }` for `'none'` or any non-matching input.
+ * @example
+ *   parseMatrixTranslate('matrix(1, 0, 0, 1, 10, 20)') // → { tx: 10, ty: 20 }
+ *   parseMatrixTranslate('none')                       // → { tx: 0, ty: 0 }
+ */
+export declare const parseMatrixTranslate: (transform: string) => {
+    tx: number;
+    ty: number;
+};

package/dist/utils/dragMath.js

@@ -42,3 +42,24 @@ export const applyConstraints = (point, range, elastic) => {
     }
     return point;
 };
+/**
+ * Parse a CSS `matrix(a, b, c, d, tx, ty)` string into translate components.
+ *
+ * Used to read the rendered translate after Motion writes inline transforms
+ * during drag-cancel hooks.
+ *
+ * @param transform The computed `transform` style — typically `'none'` or
+ *   `'matrix(1, 0, 0, 1, 10, 20)'`. `matrix3d(...)` is not supported.
+ * @returns The 2D translate components `{ tx, ty }`. Defaults to
+ *   `{ tx: 0, ty: 0 }` for `'none'` or any non-matching input.
+ * @example
+ *   parseMatrixTranslate('matrix(1, 0, 0, 1, 10, 20)') // → { tx: 10, ty: 20 }
+ *   parseMatrixTranslate('none')                       // → { tx: 0, ty: 0 }
+ */
+export const parseMatrixTranslate = (transform) => {
+    const m = transform.match(/matrix\(([^)]+)\)/);
+    if (!m)
+        return { tx: 0, ty: 0 };
+    const parts = m[1].split(',').map((s) => Number.parseFloat(s.trim()));
+    return { tx: parts[4] ?? 0, ty: parts[5] ?? 0 };
+};

package/dist/utils/inertia.js

@@ -80,12 +80,13 @@ export const createInertiaToBoundary = (initial, bounds, opts) => {
     let springX = x;
     let springV = 0;
     let boundaryTarget = null;
-    // If starting OOB, skip inertia
+    // Starting OOB: skip inertia and engage the spring. Drop the
+    // away-from-boundary velocity component so the spring's first frames
+    // don't continue moving the value outward.
     if (x < min || x > max) {
         mode = 'spring';
-        // Set spring start at current value and carry current velocity
         springX = x;
-        springV = v;
+        springV = x < min ? Math.max(0, v) : Math.min(0, v);
         boundaryTarget = x < min ? min : max;
     }
     // Precompute first crossing (if any) from initial state