@humanspeak/svelte-motion 0.5.1 → 0.5.2

package/dist/html/_MotionContainer.svelte

@@ -17,17 +17,21 @@
         DragControls,
         DragTransition,
         MotionWhileDrag,
-        DragInfo
+        DragInfo,
+        MotionOnPan,
+        MotionOnPanEnd,
+        MotionOnPanSessionStart,
+        MotionOnPanStart
     } from '../types'
     import { isNotEmpty } from '../utils/objects'
     import { sleep } from '../utils/testing'
     import { animate, type AnimationOptions, type DOMKeyframesDefinition } from 'motion'
     import { isPlaywrightEnv, pwLog } from '../utils/log'
-    import { onDestroy, type Snippet } from 'svelte'
+    import { onDestroy, untrack, type Snippet } from 'svelte'
     import { VOID_TAGS } from '../utils/constants'
     import { mergeTransitions, animateWithLifecycle } from '../utils/animation'
     import { attachWhileTap } from '../utils/interaction'
-    import { attachWhileHover } from '../utils/hover'
+    import { attachWhileHover, computeHoverBaseline, splitHoverDefinition } from '../utils/hover'
     import { attachWhileFocus } from '../utils/focus'
     import { attachWhileInView } from '../utils/inView.svelte'
     import {
@@ -48,6 +52,7 @@
     } from '../utils/presence'
     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 {
         setVariantContext,
@@ -97,6 +102,11 @@
         whileInView: whileInViewProp,
         viewport: viewportProp,
         whileDrag: whileDragProp,
+        whilePan: whilePanProp,
+        onPanSessionStart: onPanSessionStartProp,
+        onPanStart: onPanStartProp,
+        onPan: onPanProp,
+        onPanEnd: onPanEndProp,
         onHoverStart: onHoverStartProp,
         onHoverEnd: onHoverEndProp,
         onFocusStart: onFocusStartProp,
@@ -455,6 +465,7 @@
     const resolvedWhileHover = $derived(resolveWhile(whileHoverProp, variantsProp, effectiveCustom))
     const resolvedWhileFocus = $derived(resolveWhile(whileFocusProp, variantsProp, effectiveCustom))
     const resolvedWhileDrag = $derived(resolveWhile(whileDragProp, variantsProp, effectiveCustom))
+    const resolvedWhilePan = $derived(resolveWhile(whilePanProp, variantsProp, effectiveCustom))
     const resolvedWhileInView = $derived(
         resolveWhile(whileInViewProp, variantsProp, effectiveCustom)
     )
@@ -594,6 +605,172 @@
         }
     })
 
+    /**
+     * Pan-gesture wiring. Active whenever any of `onPanSessionStart`,
+     * `onPanStart`, `onPan`, `onPanEnd`, or `whilePan` is set. Unlike
+     * `drag`, Pan has no constraints / momentum / origin-snap — it's a
+     * pure pointer offset+velocity reporter, useful for swipe-to-dismiss
+     * sheets, custom carousels, and any "tell me what the gesture is
+     * doing right now" interaction. Mirrors framer-motion's `PanGesture`
+     * (packages/framer-motion/src/gestures/pan/index.ts).
+     *
+     * Split into TWO effects:
+     *
+     * 1. `attach` — keyed on `element`, `isLoaded === 'ready'`, presence
+     *    of any pan handler/whilePan, and absence of `drag` (drag takes
+     *    precedence — upstream framer-motion routes drag THROUGH the pan
+     *    gesture internally, so co-attaching pan when drag is on would
+     *    fight transforms). Creates / tears down the underlying
+     *    `attachPan` lifetime once per element-bound interval.
+     *
+     * 2. `swap` — keyed on the user's handler/whilePan props. Calls
+     *    `teardownPan.update(next)` to hot-swap the live handler set
+     *    without destroying the in-flight `PanSession`. Without this
+     *    split, every parent re-render that produces a fresh inline
+     *    arrow handler would tear down the live gesture mid-pan —
+     *    pointer listeners removed, no `onPanEnd` ever fires, whilePan
+     *    keyframes leak.
+     */
+    let teardownPan: AttachPanCleanup | null = null
+    let activeWhilePanKeyframes: Record<string, unknown> | null = null
+    let whilePanBaseline: Record<string, unknown> | null = null
+
+    /**
+     * Boolean presence-check for "is any pan surface active?". Derived
+     * so the attach effect below tracks the *boolean value*, not the
+     * individual handler/whilePan reference identities. A consumer
+     * passing `onPan={(e, i) => ...}` (inline arrow — fresh ref every
+     * render) used to re-trigger the attach effect on every parent
+     * render; with this derived in place, the attach effect only
+     * re-runs when overall presence flips (none → some, some → none).
+     * Per-ref changes flow through the hot-swap effect instead.
+     */
+    const hasAnyPanHandler = $derived(
+        !!onPanProp ||
+            !!onPanStartProp ||
+            !!onPanEndProp ||
+            !!onPanSessionStartProp ||
+            !!resolvedWhilePan
+    )
+
+    const buildPanHandlers = (): {
+        onSessionStart?: MotionOnPanSessionStart
+        onStart: NonNullable<MotionOnPanStart>
+        onMove?: MotionOnPan
+        onEnd: NonNullable<MotionOnPanEnd>
+    } => ({
+        onSessionStart: onPanSessionStartProp,
+        onStart: (event, info) => {
+            if (resolvedWhilePan && element) {
+                // Snapshot the values we'll revert to BEFORE applying — same
+                // `computeHoverBaseline` path the other while-* gestures
+                // (whileHover/whileFocus/drag) use. Covers animatable transform
+                // shorthands (scale, rotate, x, y) AND restores non-animatable
+                // inline writes (cursor, pointer-events) since the baseline
+                // sniffs `animate` → `initial` → computed style → inline style.
+                whilePanBaseline = computeHoverBaseline(element, {
+                    initial: (initialKeyframes ?? {}) as Record<string, unknown>,
+                    animate: (resolvedAnimate ?? {}) as Record<string, unknown>,
+                    whileHover: (resolvedWhilePan ?? {}) as Record<string, unknown>
+                })
+                const { keyframes, transition } = splitHoverDefinition(
+                    resolvedWhilePan as Record<string, unknown>
+                )
+                activeWhilePanKeyframes = keyframes
+                animateWithLifecycle(
+                    element,
+                    keyframes as unknown as DOMKeyframesDefinition,
+                    (transition ?? mergedTransition ?? {}) as unknown as AnimationOptions
+                )
+            }
+            onPanStartProp?.(event, info)
+        },
+        onMove: onPanProp,
+        onEnd: (event, info) => {
+            if (activeWhilePanKeyframes && whilePanBaseline && element) {
+                animateWithLifecycle(
+                    element,
+                    whilePanBaseline as unknown as DOMKeyframesDefinition,
+                    (mergedTransition ?? {}) as unknown as AnimationOptions
+                )
+            }
+            activeWhilePanKeyframes = null
+            whilePanBaseline = null
+            onPanEndProp?.(event, info)
+        }
+    })
+
+    $effect(() => {
+        if (isPlaywright) {
+            pwLog('[motion] pan attach effect run', {
+                hasAnyPanHandler,
+                isLoaded
+            })
+        }
+        if (!element) 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,
+        // whileInView). Without this, a pointerdown during the
+        // initial / mounting phase would attach pan listeners against an
+        // element whose enter animation hasn't committed its baseline.
+        if (isLoaded !== 'ready') return
+        // Drag takes precedence — upstream framer-motion's drag gesture is
+        // implemented ON TOP of Pan, not alongside it. Co-attaching here
+        // would create two competing pointer pipelines fighting for the
+        // same transforms.
+        if (dragProp) return
+        if (!hasAnyPanHandler) return
+
+        // `untrack` so the reactive reads inside `buildPanHandlers`
+        // (onPan*Prop, resolvedWhilePan, initialKeyframes, resolvedAnimate,
+        // mergedTransition) don't register as dependencies of this attach
+        // effect. Otherwise every parent re-render that passes a fresh
+        // inline arrow handler would re-run this effect and call
+        // `teardownPan?.()`, killing the live PanSession mid-gesture.
+        // Handler-ref changes flow exclusively through the hot-swap
+        // effect below, which calls `teardownPan.update(next)` — that's
+        // the path that keeps an in-flight gesture alive across re-renders.
+        teardownPan = attachPan(
+            element,
+            untrack(() => buildPanHandlers())
+        )
+
+        return () => {
+            // Synchronous revert of whilePan + lifecycle dispatch lives in
+            // attachPan.teardown() — the cleanup chain there calls
+            // session.dispatchTerminal(rawHandlers) BEFORE flipping isAlive,
+            // so onPanEnd fires (which runs the revert above) before the
+            // listeners go. dispatchTerminal is idempotent (PanSession's
+            // terminalDispatched flag) so a host that tears down after a
+            // natural release won't replay the lifecycle pair.
+            teardownPan?.()
+            teardownPan = null
+            activeWhilePanKeyframes = null
+            whilePanBaseline = null
+        }
+    })
+
+    /**
+     * Hot-swap effect — propagates handler / whilePan changes onto the
+     * existing PanSession via `teardownPan.update(next)`. Tracked
+     * separately from the attach effect so a fresh inline-arrow handler
+     * reference does NOT trigger teardown + re-attach. Without this
+     * split, every parent re-render mid-gesture would silently kill the
+     * live pan session.
+     */
+    $effect(() => {
+        // Track every prop the handler set depends on so this effect
+        // re-runs when any of them change.
+        void onPanSessionStartProp
+        void onPanStartProp
+        void onPanProp
+        void onPanEndProp
+        void resolvedWhilePan
+        if (!teardownPan) return
+        teardownPan.update(buildPanHandlers())
+    })
+
     /**
      * Execute the actual animation without wait mode checks.
      */

package/dist/types.d.ts

@@ -246,6 +246,15 @@ export type MotionOnDrag = ((event: PointerEvent, info: DragInfo) => void) | und
 export type MotionOnDragEnd = ((event: PointerEvent, info: DragInfo) => void) | undefined;
 export type MotionOnDirectionLock = ((axis: 'x' | 'y') => void) | undefined;
 export type MotionOnDragTransitionEnd = (() => void) | undefined;
+/**
+ * Pan-gesture callbacks. PanInfo is structurally identical to DragInfo
+ * (`{ point, delta, offset, velocity }`), so we re-use the type rather
+ * than ship a parallel alias.
+ */
+export type MotionOnPanSessionStart = ((event: PointerEvent, info: DragInfo) => void) | undefined;
+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;
 export type DragAxis = boolean | 'x' | 'y';
 export type DragConstraints = {
     top?: number;
@@ -319,6 +328,8 @@ export type MotionProps = {
     whileFocus?: MotionWhileFocus;
     /** Drag interaction animation */
     whileDrag?: MotionWhileDrag;
+    /** Pan interaction animation — applied while a pan gesture is active */
+    whilePan?: MotionWhileDrag;
     /** In-view interaction animation - animates when element enters viewport */
     whileInView?: MotionWhileInView;
     /** IntersectionObserver options for `whileInView` (once / root / margin / amount) */
@@ -355,6 +366,14 @@ export type MotionProps = {
     onDirectionLock?: MotionOnDirectionLock;
     /** Called when the post-drag transition finishes on all axes */
     onDragTransitionEnd?: MotionOnDragTransitionEnd;
+    /** Pan gesture: fires once per pointerdown, before threshold */
+    onPanSessionStart?: MotionOnPanSessionStart;
+    /** Pan gesture: fires the first frame after offset crosses threshold */
+    onPanStart?: MotionOnPanStart;
+    /** Pan gesture: fires once per frame while panning */
+    onPan?: MotionOnPan;
+    /** Pan gesture: fires on pointerup if onPanStart ever fired */
+    onPanEnd?: MotionOnPanEnd;
     /** Inline styles */
     style?: string;
     /** CSS classes */

package/dist/utils/pan.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Pan gesture session.
+ *
+ * Direct port of framer-motion's `PanSession`
+ * (`packages/framer-motion/src/gestures/pan/PanSession.ts`) and `PanGesture`
+ * (`packages/framer-motion/src/gestures/pan/index.ts`). Pan is the
+ * primitive that powers swipe-to-dismiss drawers, swipe-to-delete rows,
+ * carousels, and any gesture that tracks pointer offset/velocity without
+ * the constraint/momentum/snap-to-origin baggage of `drag`.
+ *
+ * Critical design notes (mirrors upstream):
+ *
+ * - `pointermove`, `pointerup`, `pointercancel` subscribe on the
+ *   `contextWindow` (defaults to `window`), NOT the source element. This
+ *   keeps the gesture alive even when the pointer leaves the element's
+ *   bounds during a fast swipe — the original element is only used for
+ *   the initial `pointerdown` and for scroll-compensation tracking.
+ *
+ * - `distanceThreshold` (default `3`px) gates the `onStart` callback so
+ *   a steady press without movement doesn't fire a pan. `onSessionStart`
+ *   fires immediately on pointerdown for setup work.
+ *
+ * - Per-frame throttling via `frame.update(updatePoint, true)` so a flood
+ *   of pointermove events doesn't run handlers more than once per render
+ *   frame. On top of that, individual handlers are routed onto motion-dom's
+ *   step lanes (see `wrapUpdate` / `wrapPostRender` above):
+ *   `onSessionStart` / `onStart` / `onMove` land on `update`,
+ *   `onEnd` / `onSessionEnd` on `postRender`. Matches upstream's
+ *   `asyncHandler` + `frame.postRender` split byte-for-byte.
+ *
+ * - `getPanInfo` returns `{ point, delta, offset, velocity }` — identical
+ *   shape to motion-dom's `DragInfo` / framer-motion's `PanInfo`.
+ *
+ * - Velocity uses a 100ms history window with the "skip the pointer-down
+ *   origin if it's too stale" tweak upstream added for hold-then-flick
+ *   gestures.
+ */
+import type { DragInfo } from '../types';
+export interface PanHandlers {
+    /** Fires on `pointerdown` regardless of whether movement follows. */
+    onSessionStart?: (event: PointerEvent, info: DragInfo) => void;
+    /** Fires the first time pointer offset crosses `distanceThreshold`. */
+    onStart?: (event: PointerEvent, info: DragInfo) => void;
+    /** Fires on every per-frame-throttled pointermove past threshold. */
+    onMove?: (event: PointerEvent, info: DragInfo) => void;
+    /** Fires on `pointerup` / `pointercancel` if `onStart` ever fired. */
+    onEnd?: (event: PointerEvent, info: DragInfo) => void;
+    /** Fires on `pointerup` / `pointercancel` always (paired with `onSessionStart`). */
+    onSessionEnd?: (event: PointerEvent, info: DragInfo) => void;
+}
+export interface AttachPanOptions {
+    /**
+     * Movement distance (in pixels) required before `onStart`/`onMove`
+     * fire. Default `3` — same as framer-motion. A steady press with
+     * sub-threshold drift is reported via `onSessionStart` / `onSessionEnd`
+     * only.
+     */
+    distanceThreshold?: number;
+    /**
+     * Window to attach the move/up/cancel listeners to. Defaults to the
+     * source element's owner window. Override for iframe / shadow-root
+     * scenarios.
+     */
+    contextWindow?: Window | null;
+}
+/**
+ * Cleanup function returned by `attachPan`. Carries an `update` method
+ * that hot-swaps the live handler set without tearing down the active
+ * `PanSession` — call this when a consumer's `onPan` reference changes
+ * mid-gesture (the canonical Svelte 5 pattern of inline arrow handlers
+ * passes a fresh closure every render). Without this, the host
+ * `$effect` would have to teardown + re-attach and the user's in-flight
+ * pan would silently die.
+ */
+export type AttachPanCleanup = (() => void) & {
+    update: (next: PanHandlers) => void;
+};
+/**
+ * Attach a pan gesture session to `el`. Returns a cleanup function that
+ * tears down the pointerdown listener and ends any in-flight session,
+ * with a `.update(next)` method for hot-swapping handlers mid-gesture.
+ *
+ * Internally a fresh `PanSession` spawns on each pointerdown — the
+ * outer attachment just keeps the pointerdown listener alive across the
+ * element's lifetime.
+ *
+ * SSR-safe: returns a no-op cleanup if `window` is undefined. The Svelte
+ * `$effect` consumer never fires on the server anyway, but defending the
+ * boundary lets the module load cleanly in node-only test runners.
+ *
+ * Lifecycle guarantee: when the returned cleanup runs mid-gesture, the
+ * session synthesizes `onEnd` + `onSessionEnd` against the raw handlers
+ * BEFORE removing listeners (see `PanSession.dispatchTerminal`). Hosts
+ * (e.g. `_MotionContainer`'s pan `$effect`) can put their `whilePan`
+ * revert logic inside the user-supplied `onEnd` and rely on it firing
+ * exactly once per gesture — whether the user released or the host
+ * forced teardown.
+ *
+ * @param el Target element to bind `pointerdown` on. Move/up/cancel
+ *   events are listened for on the element's owning window so a fast
+ *   swipe past the element's bounds keeps the gesture alive.
+ * @param handlers Pan lifecycle handlers. Any subset of
+ *   `onSessionStart` (fires on pointerdown), `onStart` (fires the first
+ *   time the cumulative offset crosses `distanceThreshold`), `onMove`
+ *   (per-frame-throttled on every pointermove past threshold), `onEnd`
+ *   (fires on pointerup/cancel if `onStart` ever fired), `onSessionEnd`
+ *   (fires on every pointerup/cancel where a pointermove occurred).
+ * @param options Per-session config. `distanceThreshold` (default 3px)
+ *   gates the start callback; `contextWindow` overrides the owning
+ *   window (use for shadow-root / iframe scenarios).
+ * @returns A cleanup function with an attached `.update(next)` method.
+ *   Calling the cleanup ends the session + removes the pointerdown
+ *   listener. Calling `.update(next)` swaps handlers in place on the
+ *   live session without rebuilding it — the canonical Svelte pattern
+ *   for inline arrow handlers that change identity each render.
+ *
+ * @example
+ * ```ts
+ * const cleanup = attachPan(node, {
+ *   onStart: (_event, info) => console.log('start', info.offset),
+ *   onMove: (_event, info) => x.set(info.offset.x),
+ *   onEnd: (_event, info) => {
+ *     if (Math.abs(info.velocity.x) > 600) commit()
+ *     else animate(x, 0, { type: 'spring' })
+ *   }
+ * })
+ *
+ * // Later, swap handlers without ending the live gesture:
+ * cleanup.update({ onMove: (_e, info) => x.set(info.offset.x * 2) })
+ *
+ * // On unmount:
+ * cleanup()
+ * ```
+ */
+export declare const attachPan: (el: HTMLElement, handlers: PanHandlers, options?: AttachPanOptions) => AttachPanCleanup;

package/dist/utils/pan.js

@@ -0,0 +1,426 @@
+import { cancelFrame, frame, frameData, isPrimaryPointer } from 'motion-dom';
+/**
+ * Brand we stamp on already-wrapped handlers so passing them back through
+ * `wrapHandlers` (e.g. by a future middleware layer) doesn't double-defer
+ * — that would compound frame latency invisibly per wrap depth. Symbol
+ * scoping keeps it private to this module.
+ */
+const WRAPPED_BRAND = Symbol('svelte-motion:pan:wrapped');
+const wrapUpdate = (handler, isAlive) => {
+    if (!handler)
+        return undefined;
+    if (handler[WRAPPED_BRAND])
+        return handler;
+    const wrapped = (event, info) => {
+        frame.update(() => {
+            // `isAlive` flips false on teardown; any frame.update closure
+            // queued before teardown but not yet flushed will see this and
+            // short-circuit — that's our cancellation path for the
+            // otherwise-uncancellable anonymous closures `frame.update`
+            // accepts.
+            if (!isAlive())
+                return;
+            handler(event, info);
+        }, false, true);
+    };
+    Object.defineProperty(wrapped, WRAPPED_BRAND, { value: true });
+    return wrapped;
+};
+const wrapPostRender = (handler, isAlive) => {
+    if (!handler)
+        return undefined;
+    if (handler[WRAPPED_BRAND])
+        return handler;
+    const wrapped = (event, info) => {
+        frame.postRender(() => {
+            if (!isAlive())
+                return;
+            handler(event, info);
+        });
+    };
+    Object.defineProperty(wrapped, WRAPPED_BRAND, { value: true });
+    return wrapped;
+};
+const wrapHandlers = (handlers, isAlive) => ({
+    onSessionStart: wrapUpdate(handlers.onSessionStart, isAlive),
+    onStart: wrapUpdate(handlers.onStart, isAlive),
+    onMove: wrapUpdate(handlers.onMove, isAlive),
+    onEnd: wrapPostRender(handlers.onEnd, isAlive),
+    onSessionEnd: wrapPostRender(handlers.onSessionEnd, isAlive)
+});
+const overflowStyles = new Set(['auto', 'scroll']);
+const millisecondsToSeconds = (ms) => ms / 1000;
+const secondsToMilliseconds = (s) => s * 1000;
+const subtractPoint = (a, b) => ({
+    x: a.x - b.x,
+    y: a.y - b.y
+});
+const distance2D = (a, b) => Math.sqrt((a.x - b.x) ** 2 + (a.y - b.y) ** 2);
+/**
+ * Compute velocity (px/s) from the history of timestamped points,
+ * looking back `timeDelta` seconds for stability. Matches upstream's
+ * `getVelocity` including the hold-then-flick safeguard (skip
+ * history[0] if it's > 2× timeDelta old AND there are alternatives).
+ */
+const getVelocity = (history, timeDelta) => {
+    if (history.length < 2)
+        return { x: 0, y: 0 };
+    let i = history.length - 1;
+    let timestampedPoint = null;
+    const lastPoint = history[history.length - 1];
+    while (i >= 0) {
+        timestampedPoint = history[i];
+        if (lastPoint.timestamp - timestampedPoint.timestamp > secondsToMilliseconds(timeDelta)) {
+            break;
+        }
+        i--;
+    }
+    if (!timestampedPoint)
+        return { x: 0, y: 0 };
+    if (timestampedPoint === history[0] &&
+        history.length > 2 &&
+        lastPoint.timestamp - timestampedPoint.timestamp > secondsToMilliseconds(timeDelta) * 2) {
+        timestampedPoint = history[1];
+    }
+    const time = millisecondsToSeconds(lastPoint.timestamp - timestampedPoint.timestamp);
+    if (time === 0)
+        return { x: 0, y: 0 };
+    const v = {
+        x: (lastPoint.x - timestampedPoint.x) / time,
+        y: (lastPoint.y - timestampedPoint.y) / time
+    };
+    if (v.x === Infinity)
+        v.x = 0;
+    if (v.y === Infinity)
+        v.y = 0;
+    return v;
+};
+const getPanInfo = (point, history) => ({
+    point,
+    delta: subtractPoint(point, history[history.length - 1]),
+    offset: subtractPoint(point, history[0]),
+    velocity: getVelocity(history, 0.1)
+});
+const extractEventPoint = (event) => ({
+    x: event.pageX,
+    y: event.pageY
+});
+/**
+ * Attach a pan gesture session to `el`. Returns a cleanup function that
+ * tears down the pointerdown listener and ends any in-flight session,
+ * with a `.update(next)` method for hot-swapping handlers mid-gesture.
+ *
+ * Internally a fresh `PanSession` spawns on each pointerdown — the
+ * outer attachment just keeps the pointerdown listener alive across the
+ * element's lifetime.
+ *
+ * SSR-safe: returns a no-op cleanup if `window` is undefined. The Svelte
+ * `$effect` consumer never fires on the server anyway, but defending the
+ * boundary lets the module load cleanly in node-only test runners.
+ *
+ * Lifecycle guarantee: when the returned cleanup runs mid-gesture, the
+ * session synthesizes `onEnd` + `onSessionEnd` against the raw handlers
+ * BEFORE removing listeners (see `PanSession.dispatchTerminal`). Hosts
+ * (e.g. `_MotionContainer`'s pan `$effect`) can put their `whilePan`
+ * revert logic inside the user-supplied `onEnd` and rely on it firing
+ * exactly once per gesture — whether the user released or the host
+ * forced teardown.
+ *
+ * @param el Target element to bind `pointerdown` on. Move/up/cancel
+ *   events are listened for on the element's owning window so a fast
+ *   swipe past the element's bounds keeps the gesture alive.
+ * @param handlers Pan lifecycle handlers. Any subset of
+ *   `onSessionStart` (fires on pointerdown), `onStart` (fires the first
+ *   time the cumulative offset crosses `distanceThreshold`), `onMove`
+ *   (per-frame-throttled on every pointermove past threshold), `onEnd`
+ *   (fires on pointerup/cancel if `onStart` ever fired), `onSessionEnd`
+ *   (fires on every pointerup/cancel where a pointermove occurred).
+ * @param options Per-session config. `distanceThreshold` (default 3px)
+ *   gates the start callback; `contextWindow` overrides the owning
+ *   window (use for shadow-root / iframe scenarios).
+ * @returns A cleanup function with an attached `.update(next)` method.
+ *   Calling the cleanup ends the session + removes the pointerdown
+ *   listener. Calling `.update(next)` swaps handlers in place on the
+ *   live session without rebuilding it — the canonical Svelte pattern
+ *   for inline arrow handlers that change identity each render.
+ *
+ * @example
+ * ```ts
+ * const cleanup = attachPan(node, {
+ *   onStart: (_event, info) => console.log('start', info.offset),
+ *   onMove: (_event, info) => x.set(info.offset.x),
+ *   onEnd: (_event, info) => {
+ *     if (Math.abs(info.velocity.x) > 600) commit()
+ *     else animate(x, 0, { type: 'spring' })
+ *   }
+ * })
+ *
+ * // Later, swap handlers without ending the live gesture:
+ * cleanup.update({ onMove: (_e, info) => x.set(info.offset.x * 2) })
+ *
+ * // On unmount:
+ * cleanup()
+ * ```
+ */
+export const attachPan = (el, handlers, options = {}) => {
+    if (typeof window === 'undefined') {
+        const noop = () => { };
+        return Object.assign(noop, { update: () => { } });
+    }
+    const contextWindow = options.contextWindow ?? el.ownerDocument?.defaultView ?? window;
+    const distanceThreshold = options.distanceThreshold ?? 3;
+    let session = null;
+    let rawHandlers = handlers;
+    // Liveness flag the wrapped handler closures consult before invoking
+    // the user callback. Flips false at teardown so any frame.update /
+    // frame.postRender callbacks queued before teardown — but not yet
+    // flushed — see the flag and skip dispatch. This is our only way to
+    // cancel the anonymous closures the wrappers schedule (frame.update
+    // doesn't return a handle we can store per call).
+    let isAlive = true;
+    const aliveGuard = () => isAlive;
+    // Frame-scheduled mirror of the live handlers — onSessionStart / onStart /
+    // onMove are queued onto motion-dom's `update` step, onEnd / onSessionEnd
+    // onto `postRender`. This is the wrap upstream applies via `asyncHandler`
+    // + `frame.postRender` in PanGesture.createPanHandlers; see the
+    // wrapUpdate / wrapPostRender helpers at the top of this file for the
+    // rationale. PanSession itself stays scheduler-unaware (and synchronous,
+    // for testability) — the scheduling lives at the `attachPan` boundary.
+    let liveHandlers = wrapHandlers(handlers, aliveGuard);
+    const onPointerDown = (event) => {
+        // Match upstream: ignore non-primary pointers (multi-touch, right-click).
+        if (!isPrimaryPointer(event))
+            return;
+        // Defensively end any prior session before overwriting the reference.
+        // Without this, a second primary pointerdown that arrives before the
+        // first pointerup orphans the prior session's contextWindow listeners.
+        session?.end();
+        session = new PanSession(event, liveHandlers, {
+            distanceThreshold,
+            contextWindow,
+            element: el
+        });
+    };
+    el.addEventListener('pointerdown', onPointerDown);
+    const update = (next) => {
+        rawHandlers = next;
+        liveHandlers = wrapHandlers(next, aliveGuard);
+        session?.updateHandlers(liveHandlers);
+    };
+    const teardown = () => {
+        // Synthesize the gesture's terminal lifecycle BEFORE flipping
+        // `isAlive`, so a host that tears us down mid-pan (effect re-run,
+        // component unmount) still sees a balanced onPanEnd / onPanSessionEnd
+        // pair. Dispatched against the *raw* (unwrapped) handlers so the
+        // delivery is synchronous — the wrapped lane would otherwise queue
+        // the callbacks onto frame.postRender just for them to be cancelled
+        // by the `isAlive = false` line immediately below.
+        if (session) {
+            session.dispatchTerminal(rawHandlers);
+            session.end();
+            session = null;
+        }
+        isAlive = false;
+        el.removeEventListener('pointerdown', onPointerDown);
+    };
+    return Object.assign(teardown, { update });
+};
+class PanSession {
+    history = [];
+    startEvent = null;
+    lastMoveEvent = null;
+    lastMovePoint = null;
+    handlers = {};
+    contextWindow = window;
+    distanceThreshold = 3;
+    element = null;
+    scrollPositions = new Map();
+    /**
+     * Idempotency flag — set the first time the gesture's terminal
+     * lifecycle pair (`onEnd` + `onSessionEnd`) fires. Both
+     * `handlePointerUp` (the natural release path) and
+     * `dispatchTerminal` (the forced-teardown path called by
+     * `attachPan.teardown`) check this and bail if already dispatched.
+     * Without it, a normal pointerup followed by a host-side teardown
+     * (e.g. `$effect` cleanup, component unmount) would replay
+     * `onEnd`/`onSessionEnd` against handlers that already saw them.
+     */
+    terminalDispatched = false;
+    removeScrollListeners = null;
+    removeListeners = null;
+    constructor(event, handlers, opts) {
+        // Bail on non-primary pointers. Properties keep their declared
+        // defaults so TypeScript sees them initialized regardless of which
+        // constructor branch ran.
+        if (!isPrimaryPointer(event))
+            return;
+        this.handlers = handlers;
+        this.contextWindow = opts.contextWindow;
+        this.distanceThreshold = opts.distanceThreshold;
+        this.element = opts.element;
+        const point = extractEventPoint(event);
+        this.history = [{ ...point, timestamp: frameData.timestamp }];
+        this.handlers.onSessionStart?.(event, getPanInfo(point, this.history));
+        const moveHandler = (e) => this.handlePointerMove(e);
+        const upHandler = (e) => this.handlePointerUp(e);
+        this.contextWindow.addEventListener('pointermove', moveHandler);
+        this.contextWindow.addEventListener('pointerup', upHandler);
+        this.contextWindow.addEventListener('pointercancel', upHandler);
+        this.removeListeners = () => {
+            this.contextWindow.removeEventListener('pointermove', moveHandler);
+            this.contextWindow.removeEventListener('pointerup', upHandler);
+            this.contextWindow.removeEventListener('pointercancel', upHandler);
+        };
+        if (this.element)
+            this.startScrollTracking(this.element);
+    }
+    updateHandlers(handlers) {
+        this.handlers = handlers;
+    }
+    end() {
+        this.removeListeners?.();
+        this.removeListeners = null;
+        this.removeScrollListeners?.();
+        this.removeScrollListeners = null;
+        this.scrollPositions.clear();
+        cancelFrame(this.updatePoint);
+    }
+    /**
+     * Synthesize the gesture's terminal lifecycle pair (`onEnd` then
+     * `onSessionEnd`) against the supplied *raw* (unwrapped) handlers,
+     * using the last observed event + point as the synthetic terminal
+     * sample. Called by `attachPan.teardown` when a host kills the
+     * session mid-gesture — without this, an `$effect` re-run that
+     * tears down the attachment silently strands the consumer's state
+     * machine in an "in-progress" state (whilePan keyframes never
+     * revert, threshold-based commit decisions never run).
+     *
+     * Bypasses the frame-loop wrappers deliberately: the wrapped
+     * handlers would queue to `frame.postRender` only for the
+     * about-to-flip `isAlive` flag in attachPan to cancel them. Raw
+     * dispatch keeps the lifecycle synchronous with teardown.
+     *
+     * No-op when no pointermove ever fired — matches the
+     * `handlePointerUp` no-movement contract upstream uses.
+     */
+    dispatchTerminal(rawHandlers) {
+        if (this.terminalDispatched)
+            return;
+        if (!(this.lastMoveEvent && this.lastMovePoint))
+            return;
+        const info = getPanInfo(this.lastMovePoint, this.history);
+        if (this.startEvent)
+            rawHandlers.onEnd?.(this.lastMoveEvent, info);
+        rawHandlers.onSessionEnd?.(this.lastMoveEvent, info);
+        this.terminalDispatched = true;
+    }
+    handlePointerMove = (event) => {
+        this.lastMoveEvent = event;
+        this.lastMovePoint = extractEventPoint(event);
+        // Per-frame throttle so a 1000hz mouse doesn't drown handlers.
+        frame.update(this.updatePoint, true);
+    };
+    handlePointerUp = (event) => {
+        this.end();
+        if (this.terminalDispatched)
+            return;
+        if (!(this.lastMoveEvent && this.lastMovePoint)) {
+            // No pointermove ever fired — match upstream framer-motion
+            // (`packages/framer-motion/src/gestures/pan/PanSession.ts`
+            // ~line 320) and return WITHOUT firing onEnd / onSessionEnd.
+            // Consumers that want a "tap" signal should use the press /
+            // tap gesture instead. This prevents a spurious
+            // onPanSessionStart → onPanSessionEnd pair on every plain
+            // click of a pan-enabled element.
+            return;
+        }
+        const finalPoint = event.type === 'pointercancel' ? this.lastMovePoint : extractEventPoint(event);
+        const info = getPanInfo(finalPoint, this.history);
+        if (this.startEvent)
+            this.handlers.onEnd?.(event, info);
+        this.handlers.onSessionEnd?.(event, info);
+        // Mark idempotent so a later forced teardown via
+        // `dispatchTerminal` doesn't replay this pair.
+        this.terminalDispatched = true;
+    };
+    updatePoint = () => {
+        if (!(this.lastMoveEvent && this.lastMovePoint))
+            return;
+        const info = getPanInfo(this.lastMovePoint, this.history);
+        const panAlreadyStarted = this.startEvent !== null;
+        const pastThreshold = distance2D(info.offset, { x: 0, y: 0 }) >= this.distanceThreshold;
+        if (!panAlreadyStarted && !pastThreshold)
+            return;
+        this.history.push({ ...this.lastMovePoint, timestamp: frameData.timestamp });
+        if (!panAlreadyStarted) {
+            this.handlers.onStart?.(this.lastMoveEvent, info);
+            this.startEvent = this.lastMoveEvent;
+        }
+        this.handlers.onMove?.(this.lastMoveEvent, info);
+    };
+    /**
+     * Track scrollable ancestors so we can compensate for scroll deltas
+     * during the gesture — mirrors upstream's `startScrollTracking`.
+     * For element scrolls: adjust `history[0]` so offset stays sane
+     * (pageX/pageY unaffected by element scroll). For window scrolls:
+     * adjust `lastMovePoint` (pageX/pageY shift with window scroll).
+     */
+    startScrollTracking(element) {
+        let current = element.parentElement;
+        while (current) {
+            const style = getComputedStyle(current);
+            if (overflowStyles.has(style.overflowX) || overflowStyles.has(style.overflowY)) {
+                this.scrollPositions.set(current, {
+                    x: current.scrollLeft,
+                    y: current.scrollTop
+                });
+            }
+            current = current.parentElement;
+        }
+        this.scrollPositions.set(this.contextWindow, {
+            x: this.contextWindow.scrollX,
+            y: this.contextWindow.scrollY
+        });
+        const onElementScroll = (event) => {
+            this.handleScroll(event.target);
+        };
+        const onWindowScroll = () => {
+            this.handleScroll(this.contextWindow);
+        };
+        this.contextWindow.addEventListener('scroll', onElementScroll, { capture: true });
+        this.contextWindow.addEventListener('scroll', onWindowScroll);
+        this.removeScrollListeners = () => {
+            this.contextWindow.removeEventListener('scroll', onElementScroll, {
+                capture: true
+            });
+            this.contextWindow.removeEventListener('scroll', onWindowScroll);
+        };
+    }
+    handleScroll(target) {
+        const initial = this.scrollPositions.get(target);
+        if (!initial)
+            return;
+        const isWindow = target === this.contextWindow;
+        const current = isWindow
+            ? { x: this.contextWindow.scrollX, y: this.contextWindow.scrollY }
+            : {
+                x: target.scrollLeft,
+                y: target.scrollTop
+            };
+        const delta = { x: current.x - initial.x, y: current.y - initial.y };
+        if (delta.x === 0 && delta.y === 0)
+            return;
+        if (isWindow) {
+            if (this.lastMovePoint) {
+                this.lastMovePoint.x += delta.x;
+                this.lastMovePoint.y += delta.y;
+            }
+        }
+        else if (this.history.length > 0) {
+            this.history[0].x -= delta.x;
+            this.history[0].y -= delta.y;
+        }
+        this.scrollPositions.set(target, current);
+        frame.update(this.updatePoint, true);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Framer Motion for Svelte 5. Declarative motion.<tag> components with AnimatePresence exit animations, gestures (hover, tap, drag, focus, in-view), variants, FLIP layout animations, shared-layout transitions, spring physics, and scroll-linked motion values. The drop-in Framer Motion alternative for Svelte and SvelteKit.",
   "keywords": [
     "svelte",
@@ -104,7 +104,7 @@
     "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.60.0",
     "@sveltejs/adapter-auto": "^7.0.1",
-    "@sveltejs/kit": "^2.60.1",
+    "@sveltejs/kit": "^2.61.1",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^7.1.2",
     "@tailwindcss/aspect-ratio": "^0.4.2",
@@ -131,7 +131,7 @@
     "prettier": "^3.8.3",
     "prettier-plugin-organize-imports": "^4.3.0",
     "prettier-plugin-sort-json": "^4.2.0",
-    "prettier-plugin-svelte": "^3.5.2",
+    "prettier-plugin-svelte": "^4.0.1",
     "prettier-plugin-tailwindcss": "^0.8.0",
     "publint": "^0.3.21",
     "runed": "0.37.1",
@@ -144,7 +144,7 @@
     "tailwindcss-animate": "^1.0.7",
     "tsx": "^4.22.3",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.4",
+    "typescript-eslint": "^8.60.0",
     "vite": "^8.0.14",
     "vite-tsconfig-paths": "^6.1.1",
     "vitest": "^4.1.7"