Motion Animation Library

This plan addresses three specific quality-of-life issues in the drag engine to improve performance and user experience:

1. Inertia Hard-Stop: Replacing the current 'overdamp hack' (using extremely high stiffness and damping values to simulate dragElastic: false) with a native bounce: false option in the inertia generator. This is more efficient and avoids numeric extremes in spring evaluation.
2. Resize Throttling: Preventing layout thrashing caused by unthrottled synchronous scalePositionWithinConstraints calls during window resize events. The goal is to ensure resize measurements and re-renders are throttled within a single frame.
3. Direction-Lock Fairness: Fixing the current Y-axis bias in getCurrentDirection. Currently, the engine checks the Y-axis threshold before the X-axis, which can cause fast diagonal movements to lock to the Y-axis incorrectly. The fix involves comparing magnitudes to lock to the dominant axis.

Note: These improvements are part of the motion-dom package and affect the drag engine used by both React and vanilla JS implementations.

In Motion, the transitionEnd property is intended to apply specific styles only after an animation has successfully completed.

Correct Behavior: If an animation is interrupted (e.g., by starting a new animation on the same value), the transitionEnd values from the interrupted animation should be discarded and not applied.

Bug Context: In versions prior to v12 (specifically starting from 10.6.0 with WAAPI acceleration), interrupting an animation would cause transitionEnd to be applied immediately mid-animation. For example, animate={{ opacity: 0, transitionEnd: { display: "none" } }} would hide the element instantly if the animation was interrupted, rather than waiting for the opacity transition to finish.

v12 Fix: The v12 animation engine rewrite ensures that transitionEnd application is gated by the completion of the animation promises. If an animation is stopped or cancelled, its finished promise does not settle in a way that triggers applyTransitionEnd in visual-element-target.ts.

By default, shared layoutId animations are resolved in page coordinates. If an unrelated content shift occurs (e.g., a sidebar mounting and pushing a tab strip) at the same time a shared element is transitioning, the element may appear to fly in from the wrong direction because it is animating between its old and new boxes in page-space rather than relative to its container.

To fix this, you can use the layoutRoot option on a parent element. This forces the subtree to behave as a layout root, allowing shared animations to resolve relative to that ancestor's box. This ensures that simultaneous content shifts in the parent do not distort the shared element's animation path.

<!-- Conceptual usage pattern -->
<div layout="true" layoutRoot>
  <!-- Shared elements inside this container will resolve animations relative to this div's box -->
  <div layoutId="tab-underline"></div>
</div>

Motion's Reorder components support multidimensional (grid) reordering by moving away from velocity-based or index-based arithmetic and instead using positional collision detection.

Instead of guessing direction based on velocity or assuming a uniform grid via modular arithmetic, the system uses the geometric Box (layout) of every registered item. A reorder (swap) is triggered when the dragged item's projected center enters the bounding box of another item. This allows for:

• Grid layouts: Works with wrapped flex layouts, uneven rows, and mixed item sizes.
• Multi-position jumps: Items can move multiple slots in a single drag event.
• Robustness: Removes reliance on velocity sign, making reordering stable even when the pointer is momentarily still or moving obliquely.

To enable 2D dragging, set the drag prop on the Reorder.Item component.

// Example concept of enabling 2D drag for reordering
<Reorder.Group axis="both">
  <Reorder.Item drag />
  {/* ... items ... */}
</Reorder.Group>

The press() gesture in motion-dom contains a bug where end events (pointerup/pointercancel) are validated after the gesture has already torn down its window listeners and cleared its state. This causes two primary issues:

1. Multi-touch interference: Lifting a secondary finger (where isPrimary: false) triggers a window pointerup that prematurely clears the press state, preventing the primary finger's end event from ever being processed. This leaves whileTap visually stuck and prevents onTap/onTapCancel from firing.
2. Swallowed Drag Cancels: If a drag starts during a press, the subsequent pointerup is rejected by the current validity check. This prevents the press from being explicitly 'cancelled', leaving the whileTap state active indefinitely.

To fix this, the onPointerEnd logic must be restructured to:

• Ignore non-primary pointer events before any teardown occurs.
• Ensure the end callback always fires for primary events, passing success: false if isDragActive() is true.

In Motion, overdamped springs (where damping ratio $\zeta > 1$) can exhibit a 'snap' behavior where they visibly jump to the target mid-animation. This is caused by a safety cap on sinh/cosh inputs to prevent Infinity overflows, which breaks the mathematical cancellation required for a smooth decay.

To resolve this, the spring implementation should use an exponential form instead of hyperbolic functions. This form is algebraically identical but uses only negative exponents ($e^{\lambda t}$ where $\lambda < 0$), which prevents overflow and removes the need for input capping.

Mathematical Implementation for $\zeta > 1$

Given:

• $D$ = initialDelta
• $V$ = initialVelocity + ω₀D
• $ω_d = ω_0√(ζ^2 - 1)$

Coefficients:

• $\lambda_{slow} = -\u03c9_0 / (\zeta + \sqrt{\zeta^2 - 1})$ (Use this form to avoid catastrophic cancellation at large $\zeta$)
• $\lambda_{fast} = -\u03c9_0(\zeta + \sqrt{\zeta^2 - 1})$
• $c_{slow} = (V + \u03c9_d \cdot D) / (2\u03c9_d)$
• $c_{fast} = D - c_{slow}$

Equations:

• Position: $x(t) = target - (c_{slow} \cdot e^{\lambda_{slow} \cdot t} + c_{fast} \cdot e^{\lambda_{fast} \cdot t})$
• Velocity (px/ms): $v(t) = -(c_{slow} \cdot \lambda_{slow} \cdot e^{\lambda_{slow} \cdot t} + c_{fast} \cdot \lambda_{fast} \cdot e^{\lambda_{fast} \cdot t})$