@humanspeak/svelte-motion 0.5.2 → 0.5.3

package/dist/components/projection.context.d.ts

@@ -0,0 +1,22 @@
+import type { ProjectionNode } from '../utils/projection';
+/**
+ * Publish a `ProjectionNode` as the projection parent for descendant
+ * motion components.
+ *
+ * @param node The current component's ProjectionNode, or `null` to
+ *   explicitly clear (rarely needed — Svelte context auto-clears on
+ *   component unmount).
+ */
+export declare const setProjectionParent: (node: ProjectionNode | null) => void;
+/**
+ * Read the ancestor `ProjectionNode` published by the nearest motion
+ * ancestor. Returns `null` when this component is at the root of the
+ * projection tree (or when no motion ancestor exists).
+ *
+ * Must be called BEFORE the current component publishes its own node
+ * via `setProjectionParent` — see the order-of-operations note in this
+ * file's header.
+ *
+ * @returns The parent ProjectionNode, or `null`.
+ */
+export declare const getProjectionParent: () => ProjectionNode | null;

package/dist/components/projection.context.js

@@ -0,0 +1,56 @@
+import { getContext, setContext } from 'svelte';
+/**
+ * Svelte context plumbing for the projection tree.
+ *
+ * Every `motion.*` element creates a `ProjectionNode` at setup time and
+ * publishes it via `setProjectionParent(node)` so descendant motion
+ * elements can pick it up via `getProjectionParent()` and wire themselves
+ * as `node.parent` + register in `node.parent.children`. The tree shape
+ * mirrors the Svelte component tree exactly because Svelte's
+ * `setContext` propagates down through descendants in component-init
+ * order.
+ *
+ * This is the closest analog we have to framer-motion's depth-sorted
+ * FlatTree (`projection/node/create-projection-node.ts`), but without
+ * the global `root` registry — parent/child pointers are sufficient
+ * for the workflows this PR enables (drag↔swap origin compensation,
+ * ancestor-zeroing measure). A global root would only be needed once we
+ * port shared-element `layoutId` morphing onto projection nodes; the
+ * current `layoutId.ts` registry continues to handle that case
+ * independently.
+ *
+ * Order of operations inside a single `motion.*` component (CRITICAL):
+ * 1. Read parent via `getProjectionParent()` BEFORE creating own node.
+ * 2. Construct own node, set `node.parent = parent`.
+ * 3. Publish own node via `setProjectionParent(node)`.
+ * If steps 1 and 3 are reversed, the component sees ITS OWN node as
+ * the parent (because `setContext` shadows from the call site down)
+ * and the tree collapses to a chain of self-references. Same trap
+ * `layoutScroll.context.ts` documents — don't repeat it.
+ */
+const PROJECTION_CONTEXT_KEY = Symbol('svelte-motion:projection-parent');
+/**
+ * Publish a `ProjectionNode` as the projection parent for descendant
+ * motion components.
+ *
+ * @param node The current component's ProjectionNode, or `null` to
+ *   explicitly clear (rarely needed — Svelte context auto-clears on
+ *   component unmount).
+ */
+export const setProjectionParent = (node) => {
+    setContext(PROJECTION_CONTEXT_KEY, node);
+};
+/**
+ * Read the ancestor `ProjectionNode` published by the nearest motion
+ * ancestor. Returns `null` when this component is at the root of the
+ * projection tree (or when no motion ancestor exists).
+ *
+ * Must be called BEFORE the current component publishes its own node
+ * via `setProjectionParent` — see the order-of-operations note in this
+ * file's header.
+ *
+ * @returns The parent ProjectionNode, or `null`.
+ */
+export const getProjectionParent = () => {
+    return getContext(PROJECTION_CONTEXT_KEY) ?? null;
+};

package/dist/html/_MotionContainer.svelte

@@ -39,10 +39,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 +54,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,10 +143,17 @@
         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 reducedMotionState = useReducedMotionConfig()
@@ -191,6 +207,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 +534,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>),
@@ -516,20 +583,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
     })
@@ -807,12 +887,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 +1018,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())
+        // 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

package/dist/index.d.ts

@@ -6,7 +6,7 @@ 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';

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;

package/dist/utils/drag.js

@@ -137,23 +137,36 @@ const computeReleaseVelocity = (history, nowMs) => {
 /**
  * Attach a drag gesture to an element.
  *
- * 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.
- */
-/**
- * Attach a drag gesture to an HTMLElement.
+ * 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 const attachDrag = (el, opts) => {
     const EL_ID = el.getAttribute('data-testid') || el.id || el.tagName;
@@ -249,6 +262,83 @@ export const attachDrag = (el, opts) => {
             }
         }
     };
+    /**
+     * Write absolute element-space translation by mutating
+     * `el.style.transform` DIRECTLY — no `animate()`, no epsilon skip,
+     * no Playwright retry. The translate channel is rewritten while any
+     * non-translate transform the element already carries (e.g. a
+     * `whileDrag` scale) is preserved as a suffix.
+     *
+     * Why this exists separately from `setXY`: routing through
+     * `animate(el, _, { duration: 0 })` defers the write to Motion's
+     * scheduler, costing ~1 frame before the new position paints. For
+     * the projection-driven origin compensation (where a layout swap
+     * must keep the dragged element under the cursor in the SAME frame
+     * the swap commits), that frame of lag manifests as a visible
+     * wobble. This path lands synchronously. See #379 / the
+     * `adjustOrigin` hook below.
+     */
+    const setXYImmediate = (x, y) => {
+        const parts = [];
+        if (axis === true || axis === 'x')
+            parts.push(`translateX(${x}px)`);
+        if (axis === true || axis === 'y')
+            parts.push(`translateY(${y}px)`);
+        // Strip existing translate channels, keep the rest (scale/rotate/etc.).
+        const nonTranslate = el.style.transform.replace(/translate[XYZ3d]*\([^)]*\)/g, '').trim();
+        el.style.transform = [...parts, nonTranslate].filter(Boolean).join(' ');
+        if (axis === true || axis === 'x')
+            applied.x = x;
+        if (axis === true || axis === 'y')
+            applied.y = y;
+    };
+    /**
+     * Adjust the drag origin + visual offset by a layout-shift delta,
+     * mid-gesture, keeping the dragged element pinned under the cursor
+     * while its underlying layout slot moves.
+     *
+     * Direct port of framer-motion's projection `didUpdate` handler in
+     * `VisualElementDragControls.ts:742-758`:
+     *
+     * ```ts
+     * this.originPoint[axis] += delta[axis].translate
+     * motionValue.set(motionValue.get() + delta[axis].translate)
+     * ```
+     *
+     * We do the same two-write dance: shift `origin` (the gesture's
+     * reference zero) AND the applied visual transform by the same
+     * delta, so `lastPoint - startPoint + origin` continues to resolve
+     * to the correct on-screen position after the layout slot moved.
+     * Uses `setXYImmediate` so the compensation is visible the same
+     * frame as the layout change.
+     *
+     * Not wired to any projection node in this PR — exposed on the
+     * `attachDrag` return handle for the Reorder PR (#310) to call from
+     * its `ProjectionNode.didUpdate` listener.
+     *
+     * @param dx Layout delta on the x axis (px).
+     * @param dy Layout delta on the y axis (px).
+     */
+    const adjustOrigin = (dx, dy) => {
+        if (!dragging)
+            return;
+        // Compensate the origin on BOTH axes unconditionally — upstream's
+        // didUpdate handler applies the delta per-axis via `eachAxis`
+        // regardless of the drag axis or direction lock, because a layout
+        // slot can shift on either axis.
+        origin.x += dx;
+        origin.y += dy;
+        // The VISUAL write is `setXYImmediate`, which only writes the axis
+        // this drag manages (`opts.axis`). For the dragged axis that pins
+        // the element same-frame; the cross-axis case (e.g. drag="x" + a
+        // y-shift) only updates `origin`, not the transform. Fully
+        // rendering cross-axis compensation needs to route through the
+        // Motion value the move path uses (a direct write here would be
+        // wiped by the next `setXY`), so it's finalized when this hook is
+        // wired in #310. The common Reorder case (drag axis === the shift
+        // axis) is fully compensated today.
+        setXYImmediate(applied.x + dx, applied.y + dy);
+    };
     const startWhileDrag = () => {
         if (!opts.whileDrag)
             return;
@@ -758,7 +848,7 @@ export const attachDrag = (el, opts) => {
     }
     el.addEventListener('pointerdown', onPointerDown);
     pwLog('[drag] pointerdown listener attached', { el: EL_ID });
-    return () => {
+    const teardown = () => {
         pwLog('[drag] detach', { el: EL_ID });
         el.removeEventListener('pointerdown', onPointerDown);
         el.removeEventListener('pointermove', onPointerMove);
@@ -768,4 +858,5 @@ export const attachDrag = (el, opts) => {
         window.removeEventListener('pointerup', onPointerUp);
         window.removeEventListener('pointercancel', onPointerCancel);
     };
+    return Object.assign(teardown, { adjustOrigin });
 };