@humanspeak/svelte-motion 0.5.2 → 0.5.4

package/dist/html/_MotionContainer.svelte

@@ -5,6 +5,8 @@
 
 <script lang="ts">
     import { getMotionConfig } from '../components/motionConfig.context'
+    import { getLazyMotionContext } from '../components/lazyMotion.context'
+    import { domMax } from '../features/domMax'
     import {
         filterReducedMotionKeyframes,
         useReducedMotionConfig
@@ -39,10 +41,11 @@
         computeFlipTransforms,
         runFlipAnimation,
         setCompositorHints,
-        observeLayoutChanges
+        observeLayoutChanges,
+        type RectLike
     } from '../utils/layout'
     import type { SvelteHTMLElements } from 'svelte/elements'
-    import { mergeInlineStyles } from '../utils/style'
+    import { mergeInlineStyles, extractTransform } from '../utils/style'
     import { isNativelyFocusable } from '../utils/a11y'
     import {
         getAnimatePresenceContext,
@@ -53,7 +56,15 @@
     import { getInitialKeyframes } from '../utils/initial'
     import { attachDrag } from '../utils/drag'
     import { attachPan, type AttachPanCleanup } from '../utils/pan'
-    import { resolveInitial, resolveAnimate, resolveExit, resolveWhile } from '../utils/variants'
+    import { ProjectionNode } from '../utils/projection'
+    import { getProjectionParent, setProjectionParent } from '../components/projection.context'
+    import {
+        resolveInitial,
+        resolveAnimate,
+        resolveExit,
+        resolveWhile,
+        resolveRestingValues
+    } from '../utils/variants'
     import {
         setVariantContext,
         getVariantContext,
@@ -134,12 +145,24 @@
         layout: layoutProp,
         layoutId: layoutIdProp,
         layoutScroll: layoutScrollProp,
+        onProjectionUpdate: onProjectionUpdateProp,
         ref: element = $bindable(null),
         ...rest
     }: Props = $props()
     let isLoaded = $state<'mounting' | 'initial' | 'ready' | 'animated'>('mounting')
+    // True once the enter/animate animation has COMPLETED. Until then the
+    // WAAPI animation owns the transform; flipping the inline baseline to
+    // the target mid-run causes a one-frame snap (the target shows through
+    // for the frame the inline changes). We therefore only apply the target
+    // as the inline style once settled — see the style derivation. (#377)
+    let enterAnimationSettled = $state(false)
     let dataPath = $state<number>(-1)
     const motionConfig = $derived(getMotionConfig())
+    const lazyMotion = getLazyMotionContext()
+    const activeFeatures = $derived(lazyMotion?.getFeatures() ?? domMax)
+    const hasGestureFeatures = $derived(!!activeFeatures.gestures)
+    const hasDragFeatures = $derived(!!activeFeatures.drag)
+    const hasLayoutFeatures = $derived(!!activeFeatures.layout)
     const reducedMotionState = useReducedMotionConfig()
     // `.current` is $state-backed inside reducedMotionState; tracking it via
     // $derived makes `reducedMotion` re-evaluate whenever the OS preference
@@ -191,6 +214,46 @@
         return refs.filter((el): el is HTMLElement => Boolean(el))
     }
 
+    // Projection tree wiring (#379). Capture the parent node BEFORE
+    // publishing our own — same shadowing trap as layoutScroll above.
+    // The node measures through `resolveLayoutScrollAncestors` so its
+    // boxes share the FLIP coordinate space, and zeros ancestor
+    // transforms during measure so nested layout-animated parents don't
+    // corrupt a child's delta.
+    // The user-authored transform, sourced from the `style` prop rather
+    // than the live inline transform — the latter already carries any
+    // transform-type `initial`/`animate` keyframe by the time the node
+    // measures, which would be mistaken for the user's base.
+    const userBaseTransform = $derived(extractTransform(styleProp))
+
+    const projectionParent = getProjectionParent()
+    const projection = new ProjectionNode({
+        parent: projectionParent,
+        getScrollContainers: resolveLayoutScrollAncestors,
+        getBaseTransform: () => userBaseTransform
+    })
+    setProjectionParent(projection)
+
+    // Convert a projection `Box` (ancestor chain reset to base, self
+    // transform stripped, scroll containers compensated) to the
+    // `RectLike` shape `computeFlipTransforms` consumes.
+    const boxToRectLike = (box: {
+        x: { min: number; max: number }
+        y: { min: number; max: number }
+    }): RectLike => ({
+        left: box.x.min,
+        top: box.y.min,
+        width: box.x.max - box.x.min,
+        height: box.y.max - box.y.min
+    })
+
+    // Ancestor-transform-invariant layout measurement for seeding the
+    // FLIP effect's first rect.
+    const measureLayoutRect = (): RectLike | null => {
+        const box = projection.measure()
+        return box ? boxToRectLike(box) : null
+    }
+
     // Get current presence depth (0 = direct child of AnimatePresence, undefined = not in AnimatePresence)
     const presenceDepth = getPresenceDepth()
 
@@ -478,6 +541,17 @@
         )
     )
 
+    // Reduced-motion-filtered animate values used as the inline-style
+    // baseline so an animated value (transforms included) persists after
+    // the WAAPI animation completes (#377). Filtered exactly like
+    // `initialKeyframes` so transforms are stripped under reduced motion.
+    const animateKeyframes = $derived(
+        filterReducedMotionKeyframes(
+            resolvedAnimate as Record<string, unknown> | undefined,
+            reducedMotion
+        )
+    )
+
     // Derived attributes to keep both branches in sync (focusability, data flags, style, class)
     const derivedAttrs = $derived<Record<string, unknown>>({
         ...(rest as Record<string, unknown>),
@@ -486,7 +560,8 @@
         // key, empty array) would otherwise add `tabindex=0` for an
         // element that never actually receives a tap gesture — an
         // unintended tab stop. (#349 CR feedback)
-        ...(isNotEmpty(resolvedWhileTap) &&
+        ...(hasGestureFeatures &&
+        isNotEmpty(resolvedWhileTap) &&
         !isNativelyFocusable(tag, rest as Record<string, unknown>) &&
         ((rest as Record<string, unknown>)?.tabindex ??
             (rest as Record<string, unknown>)?.tabIndex ??
@@ -516,20 +591,33 @@
             initialKeyframes && 'pathLength' in initialKeyframes && isLoaded === 'mounting'
                 ? `${styleProp || ''};visibility:hidden`
                 : styleProp,
-            // 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
+            // The "from" slot: apply initialKeyframes as inline styles during
+            // the mounting/initial phases (before the WAAPI animation locks
+            // its from-value and we promote to 'ready' — see the lifecycle
+            // around the enter rAF). mergeInlineStyles prefers this slot when
+            // non-empty, so it wins over the animate slot below in these phases.
             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>)
+            // The "target" slot. Only AFTER the enter animation completes does
+            // the target become the inline baseline, so the element holds it
+            // once WAAPI surrenders the property (default fill:'none' would
+            // otherwise leave transform:none). It must NOT be applied during
+            // the run: flipping the inline value to the target mid-animation
+            // shows the target for the one frame the inline changes (a visible
+            // snap), since WAAPI's composite doesn't override that exact frame.
+            // While the animation runs we keep the original behavior — initial
+            // keyframes own the inline (via the slot above), or, with no
+            // initial, the animate values seed the inline as the from. Resting
+            // values collapse keyframe arrays to their last element
+            // (animate={{x:[0,100,50]}} rests at 50). (#377)
+            enterAnimationSettled
+                ? (resolveRestingValues(
+                      animateKeyframes as DOMKeyframesDefinition | undefined
+                  ) as unknown as Record<string, unknown>)
+                : isNotEmpty(initialKeyframes)
+                  ? undefined
+                  : (animateKeyframes as unknown as Record<string, unknown>)
         ),
         class: classProp
     })
@@ -546,7 +634,7 @@
     //   after any non-zero duration settle animation.
     let teardownDrag: (() => void) | null = null
     $effect(() => {
-        if (!(element && isLoaded === 'ready')) return
+        if (!(element && isLoaded === 'ready' && hasDragFeatures)) return
         // Only attach if drag enabled
         if (!dragProp) return
         // Clean up previous
@@ -707,7 +795,7 @@
                 isLoaded
             })
         }
-        if (!element) return
+        if (!element || !hasGestureFeatures) return
         // Defer attachment until the element has settled out of the enter
         // animation phase — matches the gate every other gesture effect
         // in this file uses (drag, whileTap, whileHover, whileFocus,
@@ -807,12 +895,20 @@
             transitionAnimate
         })
 
+        // A fresh run owns the transform again until it completes.
+        enterAnimationSettled = false
         animateWithLifecycle(
             element,
             payload as unknown as DOMKeyframesDefinition,
             transitionAnimate as unknown as AnimationOptions,
             (def) => onAnimationStartProp?.(def as unknown as DOMKeyframesDefinition | undefined),
-            (def) => onAnimationCompleteProp?.(def as unknown as DOMKeyframesDefinition | undefined)
+            (def) => {
+                // Now the target is the resting state — promote it to the
+                // inline baseline so it persists after WAAPI surrenders the
+                // property (default fill:'none'). (#377)
+                enterAnimationSettled = true
+                onAnimationCompleteProp?.(def as unknown as DOMKeyframesDefinition | undefined)
+            }
         )
     }
 
@@ -930,26 +1026,65 @@
               : undefined
     )
 
+    // Projection node lifecycle + the `onProjectionUpdate` listener.
+    // Mount once the element binds; seed the baseline layout; unmount on
+    // cleanup. Depends ONLY on `element` — the `onProjectionUpdate`
+    // subscription lives in its own effect below so a change to the
+    // callback's identity re-subscribes WITHOUT tearing the node down
+    // (an unmount would clear latestLayout/children and re-seed the
+    // first commit instead of emitting a real delta).
+    $effect(() => {
+        if (!element) return
+        projection.mount(element)
+        projection.measure() // seed latestLayout so the first commit can diff
+        return () => {
+            projection.unmount()
+        }
+    })
+
+    // Subscribe the consumer's `onProjectionUpdate` callback. Separate
+    // from the mount effect so re-subscribing on a callback-identity
+    // change never unmounts the node.
+    $effect(() => {
+        if (!(element && onProjectionUpdateProp)) return
+        const off = projection.addEventListener('didUpdate', (data) => onProjectionUpdateProp(data))
+        return () => {
+            off()
+        }
+    })
+
     // Minimal layout animation using FLIP when `layout` is enabled.
     // When layout === 'position' we only translate.
     // When layout === true we also scale to smoothly interpolate size changes.
-    let lastRect: DOMRect | null = null
+    let lastRect: RectLike | null = null
     $effect(() => {
-        if (!(element && layoutProp && isLoaded === 'ready')) return
-
-        // Initialize last rect on first ready frame
-        lastRect = measureRect(element!, resolveLayoutScrollAncestors())
+        if (!(element && layoutProp && isLoaded === 'ready' && hasLayoutFeatures)) return
+
+        // Initialize last rect on first ready frame. We measure through the
+        // projection node rather than `measureRect` directly so the rect is
+        // ancestor-transform-invariant: the node resets the whole ancestor
+        // chain to its mount-time base while reading, which strips any
+        // motion-applied (FLIP/drag) transform up the tree. Without this a
+        // child re-measures and FLIPs whenever an ancestor's transform
+        // animates, even though the child's own layout never moved. (#379)
+        lastRect = measureLayoutRect()
         // Hint compositor for smoother FLIP transforms
         setCompositorHints(element!, true)
 
         let rafId: number | null = null
         const runFlip = () => {
-            const scrollContainers = resolveLayoutScrollAncestors()
+            // commitLayoutChange does the ancestor-stripped measure, fans
+            // the delta out to `onProjectionUpdate` listeners, AND returns
+            // the freshly-measured box — so the FLIP reuses that single
+            // measurement as `next` instead of walking + transform-resetting
+            // the ancestor chain a second time per frame. (#379)
+            const nextBox = projection.commitLayoutChange()
+            if (!nextBox) return
+            const next = boxToRectLike(nextBox)
             if (!lastRect) {
-                lastRect = measureRect(element!, scrollContainers)
+                lastRect = next
                 return
             }
-            const next = measureRect(element!, scrollContainers)
             const transforms = computeFlipTransforms(lastRect, next, layoutProp ?? false)
             runFlipAnimation(element!, transforms, (mergedTransition ?? {}) as AnimationOptions)
             lastRect = next
@@ -978,7 +1113,16 @@
     // Shared layout animation via layoutId.
     // On mount, consume the previous snapshot and FLIP from its position.
     $effect(() => {
-        if (!(element && scopedLayoutId && layoutIdRegistry && isLoaded === 'ready')) return
+        if (
+            !(
+                element &&
+                scopedLayoutId &&
+                layoutIdRegistry &&
+                isLoaded === 'ready' &&
+                hasLayoutFeatures
+            )
+        )
+            return
 
         const prev = layoutIdRegistry.consume(scopedLayoutId)
         if (!prev) return // First appearance, no animation needed
@@ -996,7 +1140,10 @@
 
     // whileTap handling via motion-dom's press()
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileTap))) return
+        if (
+            !(element && isLoaded === 'ready' && hasGestureFeatures && isNotEmpty(resolvedWhileTap))
+        )
+            return
         return attachWhileTap(
             element!,
             (resolvedWhileTap ?? {}) as Record<string, unknown>,
@@ -1016,7 +1163,15 @@
 
     // whileHover handling, gated to true-hover devices to avoid sticky states on touch
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileHover))) return
+        if (
+            !(
+                element &&
+                isLoaded === 'ready' &&
+                hasGestureFeatures &&
+                isNotEmpty(resolvedWhileHover)
+            )
+        )
+            return
         return attachWhileHover(
             element!,
             (resolvedWhileHover ?? {}) as Record<string, unknown>,
@@ -1031,7 +1186,15 @@
 
     // whileFocus handling for keyboard focus interactions
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileFocus))) return
+        if (
+            !(
+                element &&
+                isLoaded === 'ready' &&
+                hasGestureFeatures &&
+                isNotEmpty(resolvedWhileFocus)
+            )
+        )
+            return
         return attachWhileFocus(
             element!,
             (resolvedWhileFocus ?? {}) as Record<string, unknown>,
@@ -1046,7 +1209,15 @@
 
     // whileInView handling for viewport intersection
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileInView))) return
+        if (
+            !(
+                element &&
+                isLoaded === 'ready' &&
+                hasGestureFeatures &&
+                isNotEmpty(resolvedWhileInView)
+            )
+        )
+            return
         return attachWhileInView(
             element!,
             (resolvedWhileInView ?? {}) as Record<string, unknown>,

package/dist/index.d.ts

@@ -1,12 +1,18 @@
 import AnimatePresence from './components/AnimatePresence.svelte';
 import LayoutGroup from './components/LayoutGroup.svelte';
+import LazyMotion from './components/LazyMotion.svelte';
 import MotionConfig from './components/MotionConfig.svelte';
 import PresenceChild from './components/PresenceChild.svelte';
+export type { FeatureBundle, LazyFeatureBundle } from './features';
+export { domAnimation } from './features/domAnimation';
+export { domMax } from './features/domMax';
+export { domMin } from './features/domMin';
+export { m } from './m';
 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 type { DragAxis, DragConstraints, DragControls, DragInfo, DragTransition, MotionAnimate, MotionInitial, MotionOnDirectionLock, MotionOnDragTransitionEnd, MotionOnInViewEnd, MotionOnInViewStart, MotionOnProjectionUpdate, MotionTransition, MotionWhileDrag, MotionWhileFocus, MotionWhileHover, MotionWhileInView, MotionWhileTap, ProjectionUpdatePayload, ReducedMotionConfig, Variants } from './types';
 export { useAnimate } from './utils/animate.svelte';
 export type { AnimationScope } from './utils/animate.svelte';
 export { useAnimationFrame } from './utils/animationFrame';
@@ -42,7 +48,7 @@ export { styleString } from './utils/styleObject.svelte';
 export { useTime } from './utils/time.svelte';
 export { useTransform } from './utils/transform.svelte';
 export type { MultiTransformer, SingleTransformer, TransformOptions, TransformOutputMap, TransformSource } from './utils/transform.svelte';
-export { AnimatePresence, LayoutGroup, MotionConfig, PresenceChild };
+export { AnimatePresence, LayoutGroup, LazyMotion, 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,7 +1,12 @@
 import AnimatePresence from './components/AnimatePresence.svelte';
 import LayoutGroup from './components/LayoutGroup.svelte';
+import LazyMotion from './components/LazyMotion.svelte';
 import MotionConfig from './components/MotionConfig.svelte';
 import PresenceChild from './components/PresenceChild.svelte';
+export { domAnimation } from './features/domAnimation';
+export { domMax } from './features/domMax';
+export { domMin } from './features/domMin';
+export { m } from './m';
 export { motion } from './motion';
 // Re-export core animation functions from motion
 export { animate, delay, hover, inView, press, resize, scroll, stagger, transform } from 'motion';
@@ -31,7 +36,7 @@ export { stringifyStyleObject } from './utils/styleObject';
 export { styleString } from './utils/styleObject.svelte';
 export { useTime } from './utils/time.svelte';
 export { useTransform } from './utils/transform.svelte';
-export { AnimatePresence, LayoutGroup, MotionConfig, PresenceChild };
+export { AnimatePresence, LayoutGroup, LazyMotion, 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/m.d.ts

@@ -0,0 +1,9 @@
+import type { MotionComponents } from './html/index';
+/**
+ * Lazy motion component namespace used with `<LazyMotion>`.
+ *
+ * The namespace mirrors the default `motion` object API (`m.div`, `m.button`,
+ * `m.svg`, etc.) while reading feature availability from the nearest
+ * LazyMotion provider.
+ */
+export declare const m: MotionComponents;

package/dist/m.js

@@ -0,0 +1,9 @@
+import * as html from './html/index';
+/**
+ * Lazy motion component namespace used with `<LazyMotion>`.
+ *
+ * The namespace mirrors the default `motion` object API (`m.div`, `m.button`,
+ * `m.svg`, etc.) while reading feature availability from the nearest
+ * LazyMotion provider.
+ */
+export const m = Object.fromEntries(Object.entries(html).map(([key, component]) => [key.toLowerCase(), component]));

package/dist/types.d.ts

@@ -255,6 +255,59 @@ export type MotionOnPanSessionStart = ((event: PointerEvent, info: DragInfo) =>
 export type MotionOnPanStart = ((event: PointerEvent, info: DragInfo) => void) | undefined;
 export type MotionOnPan = ((event: PointerEvent, info: DragInfo) => void) | undefined;
 export type MotionOnPanEnd = ((event: PointerEvent, info: DragInfo) => void) | undefined;
+/**
+ * Payload delivered to `onProjectionUpdate`. Re-declared structurally
+ * here (rather than imported from `projection.ts`) so `types.ts`
+ * stays dependency-free at the type layer. `delta.x/y.translate` is the
+ * px shift the element's layout box moved between the pre-change
+ * snapshot and the post-change measurement; `hasLayoutChanged` is false
+ * only when the delta is within a tight float epsilon (±0.01px
+ * translate), so even a sub-pixel real move is reported as a change.
+ */
+export type ProjectionUpdatePayload = {
+    layout: {
+        x: {
+            min: number;
+            max: number;
+        };
+        y: {
+            min: number;
+            max: number;
+        };
+    };
+    snapshot: {
+        x: {
+            min: number;
+            max: number;
+        };
+        y: {
+            min: number;
+            max: number;
+        };
+    };
+    delta: {
+        x: {
+            translate: number;
+            scale: number;
+            origin: number;
+            originPoint: number;
+        };
+        y: {
+            translate: number;
+            scale: number;
+            origin: number;
+            originPoint: number;
+        };
+    };
+    hasLayoutChanged: boolean;
+};
+/**
+ * Fires after each layout change to a `motion.*` element that has
+ * `layout` enabled, with the FLIP delta between the pre- and
+ * post-change layout boxes. Mirrors framer-motion's `onLayoutMeasure`
+ * surface. Wired through the element's internal `ProjectionNode`.
+ */
+export type MotionOnProjectionUpdate = ((data: ProjectionUpdatePayload) => void) | undefined;
 export type DragAxis = boolean | 'x' | 'y';
 export type DragConstraints = {
     top?: number;
@@ -380,6 +433,12 @@ export type MotionProps = {
     class?: string;
     /** Enable FLIP layout animations; "position" limits to translation only */
     layout?: boolean | 'position';
+    /**
+     * Fires after each `layout`-driven change with the FLIP delta from
+     * the element's internal projection node. Mirrors framer-motion's
+     * `onLayoutMeasure`. Requires `layout` to be enabled.
+     */
+    onProjectionUpdate?: MotionOnProjectionUpdate;
     /** Shared layout animation identifier. Elements with matching layoutId animate between positions. */
     layoutId?: string;
     /**

package/dist/utils/drag.d.ts

@@ -66,24 +66,55 @@ export declare const resolveConstraints: (el: HTMLElement | null, constraints: D
  */
 export declare const applyElastic: (value: number, min: number, max: number, elastic: number) => number;
 /**
- * Attach a drag gesture to an element.
+ * Cleanup handle returned by {@link attachDrag}. Invoke it to detach the
+ * gesture's pointer/resize listeners. It does NOT cancel an in-flight
+ * momentum/settle animation — matching framer-motion, whose drag teardown
+ * removes listeners only and deliberately lets motion continue across an
+ * unmount/remount (e.g. reorder reconciliation); the animation is cleaned
+ * up by the element/motion-value lifecycle.
  *
- * Captures the pointer, updates x/y transforms with axis and optional direction lock,
- * applies elastic overflow against constraints, emits lifecycle callbacks with DragInfo,
- * and runs a momentum animation on release when enabled.
+ * The handle also carries `adjustOrigin(dx, dy)`, which shifts the LIVE
+ * gesture's origin + visual offset by a layout-shift delta mid-drag — used
+ * for projection-driven cursor pinning when a layout slot moves under the
+ * dragged element (#379 / #310). It is a no-op when not currently dragging
+ * and compensates on both axes (mirroring upstream's per-axis `eachAxis`
+ * compensation).
  */
+export type AttachDragCleanup = (() => void) & {
+    adjustOrigin: (dx: number, dy: number) => void;
+};
 /**
- * Attach a drag gesture to an HTMLElement.
+ * Attach a drag gesture to an element.
+ *
+ * Captures the pointer and updates x/y transforms with axis and optional
+ * direction lock, applies elastic overflow against constraints, emits
+ * lifecycle callbacks with `DragInfo`, and runs a momentum animation on
+ * release when enabled.
  *
  * Lifecycle:
  * - pointerdown → capture pointer, snapshot origin, start velocity history, enter whileDrag
  * - pointermove → compute deltas, direction lock, apply constraints + elastic, write x/y
  * - pointerup/cancel → either run momentum decay to a target or settle/clamp instantly
  *
- * Important invariants:
- * - `applied` tracks the currently applied transform (x/y). Always keep it in sync when
- *   writing transforms or finishing animations so a second drag starts from the right origin.
- * - If you see a "jump" at the start of a second drag, it usually means `applied` wasn't
- *   updated after a non-0-duration settle animation.
+ * Invariant: `applied` tracks the currently applied x/y transform — it
+ * must stay in sync when writing transforms or finishing animations, or a
+ * second drag "jumps" from a stale origin (commonly a missed update after
+ * a non-zero-duration settle animation).
+ *
+ * @param el The element to make draggable.
+ * @param opts Drag options — `axis`, `constraints`, `elastic`,
+ *   `momentum`, `whileDrag`, and the `onDrag*` lifecycle callbacks.
+ * @returns A callable cleanup handle ({@link AttachDragCleanup}): call it
+ *   to detach the gesture's listeners (in-flight momentum is not
+ *   cancelled — see the type docs), or call its `adjustOrigin(dx, dy)` to
+ *   reposition the live gesture mid-drag.
+ * @example
+ * ```ts
+ * const cleanup = attachDrag(el, { axis: 'x', momentum: true })
+ * // …when a layout swap shifts the slot under the cursor mid-drag:
+ * cleanup.adjustOrigin(10, -5)
+ * // on teardown:
+ * cleanup()
+ * ```
  */
-export declare const attachDrag: (el: HTMLElement, opts: AttachDragOptions) => (() => void);
+export declare const attachDrag: (el: HTMLElement, opts: AttachDragOptions) => AttachDragCleanup;