@pawells/math-extended 1.0.4 → 1.1.1

package/build/interpolation.js

@@ -3,6 +3,8 @@ import { Clamp } from './clamp.js';
 const CUBIC = 3; // t³ power used in cubic ease, smooth step, etc.
 const QUARTIC = 4; // t⁴ power used in smoother step / catmull-rom
 const QUINTIC = 5; // t⁵ power used in smoother step
+// Perlin's smootherstep formula coefficients: 6t⁵ − 15t⁴ + 10t³
+// These create a smooth curve with zero first and second derivatives at endpoints
 const SMOOTHER_COEFF_A = 6; // 6t⁵ coefficient in SmootherStep
 const SMOOTHER_COEFF_B = 15; // 15t⁴ coefficient in SmootherStep
 const SMOOTHER_COEFF_C = 10; // 10t³ coefficient in SmootherStep
@@ -48,8 +50,18 @@ export function LinearInterpolation(a, b, t) {
     return a + ((b - a) * t);
 }
 /**
- * Smooth step interpolation (3t² - 2t³)
- * Provides smooth acceleration and deceleration with zero derivatives at endpoints
+ * Smooth step interpolation (3t² − 2t³).
+ * Provides smooth acceleration and deceleration with zero first derivatives at both endpoints.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value using cubic smooth-step curve
+ *
+ * @example
+ * SmoothStep(0, 10, 0)    // 0
+ * SmoothStep(0, 10, 1)    // 10
+ * SmoothStep(0, 10, 0.25) // 1.5625 (slower start than LinearInterpolation's 2.5)
  */
 export function SmoothStep(a, b, t) {
     // Allow extrapolation by not clamping t
@@ -57,8 +69,19 @@ export function SmoothStep(a, b, t) {
     return a + ((b - a) * smoothT);
 }
 /**
- * Smoother step interpolation (6t⁵ - 15t⁴ + 10t³)
- * Even smoother than SmoothStep with zero first and second derivatives at endpoints
+ * Smoother step interpolation (6t⁵ − 15t⁴ + 10t³).
+ * Even smoother than SmoothStep with zero first and second derivatives at both endpoints
+ * (Ken Perlin's improvement).
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value using quintic smoother-step curve
+ *
+ * @example
+ * SmootherStep(0, 10, 0)    // 0
+ * SmootherStep(0, 10, 1)    // 10
+ * SmootherStep(0, 10, 0.25) // ~1.04 (smoother start than SmoothStep)
  */
 export function SmootherStep(a, b, t) {
     // Allow extrapolation by not clamping t
@@ -66,40 +89,90 @@ export function SmootherStep(a, b, t) {
     return a + ((b - a) * smoothT);
 }
 /**
- * Quadratic ease-in interpolation (t²)
- * Accelerates slowly at the beginning
+ * Quadratic ease-in interpolation (t²).
+ * Accelerates from rest — starts slowly and gains speed toward the end.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value with quadratic acceleration from start
+ *
+ * @example
+ * QuadraticEaseIn(0, 10, 0)    // 0
+ * QuadraticEaseIn(0, 10, 1)    // 10
+ * QuadraticEaseIn(0, 10, 0.5)  // 2.5 (only 25% progress at the midpoint)
  */
 export function QuadraticEaseIn(a, b, t) {
     // Allow extrapolation by not clamping t
     return a + ((b - a) * t * t);
 }
 /**
- * Quadratic ease-out interpolation (1 - (1-t)²)
- * Decelerates slowly at the end
+ * Quadratic ease-out interpolation (1 − (1−t)²).
+ * Decelerates to rest — starts quickly and slows toward the end.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value with quadratic deceleration toward end
+ *
+ * @example
+ * QuadraticEaseOut(0, 10, 0)   // 0
+ * QuadraticEaseOut(0, 10, 1)   // 10
+ * QuadraticEaseOut(0, 10, 0.5) // 7.5 (already 75% progress at the midpoint)
  */
 export function QuadraticEaseOut(a, b, t) {
     // Allow extrapolation by not clamping t
     return a + ((b - a) * (1 - Math.pow(1 - t, 2)));
 }
 /**
- * Cubic ease-in interpolation (t³)
- * More pronounced acceleration than quadratic
+ * Cubic ease-in interpolation (t³).
+ * More pronounced acceleration than quadratic — starts very slowly.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value with cubic acceleration from start
+ *
+ * @example
+ * CubicEaseIn(0, 10, 0)    // 0
+ * CubicEaseIn(0, 10, 1)    // 10
+ * CubicEaseIn(0, 10, 0.5)  // 1.25 (only 12.5% progress at the midpoint)
  */
 export function CubicEaseIn(a, b, t) {
     // Allow extrapolation by not clamping t
     return a + ((b - a) * t * t * t);
 }
 /**
- * Cubic ease-out interpolation (1 - (1-t)³)
- * More pronounced deceleration than quadratic
+ * Cubic ease-out interpolation (1 − (1−t)³).
+ * More pronounced deceleration than quadratic — slows very gradually at the end.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value with cubic deceleration toward end
+ *
+ * @example
+ * CubicEaseOut(0, 10, 0)   // 0
+ * CubicEaseOut(0, 10, 1)   // 10
+ * CubicEaseOut(0, 10, 0.5) // 8.75 (already 87.5% progress at the midpoint)
  */
 export function CubicEaseOut(a, b, t) {
     // Allow extrapolation by not clamping t
     return a + ((b - a) * (1 - Math.pow(1 - t, CUBIC)));
 }
 /**
- * Cosine interpolation - smooth curve using cosine function
- * Provides natural easing similar to SmoothStep but using trigonometry
+ * Cosine interpolation — smooth curve using the cosine function.
+ * Provides natural easing similar to SmoothStep but using trigonometry.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value using cosine-based easing curve
+ *
+ * @example
+ * CosineInterpolation(0, 10, 0)   // 0
+ * CosineInterpolation(0, 10, 1)   // 10
+ * CosineInterpolation(0, 10, 0.5) // 5 (same as LERP at midpoint; smooth near endpoints)
  */
 export function CosineInterpolation(a, b, t) {
     // Allow extrapolation by not clamping t
@@ -107,24 +180,54 @@ export function CosineInterpolation(a, b, t) {
     return a + ((b - a) * cosT);
 }
 /**
- * Sine ease-in interpolation
- * Slow start with smooth acceleration
+ * Sine ease-in interpolation.
+ * Slow start with smooth sinusoidal acceleration.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value with sine-based acceleration from start
+ *
+ * @example
+ * SineEaseIn(0, 10, 0)   // 0
+ * SineEaseIn(0, 10, 1)   // 10
+ * SineEaseIn(0, 10, 0.5) // ~2.93 (slower than LinearInterpolation's 5 at midpoint)
  */
 export function SineEaseIn(a, b, t) {
     // Allow extrapolation by not clamping t
     return a + ((b - a) * (1 - Math.cos((t * Math.PI) / 2)));
 }
 /**
- * Sine ease-out interpolation
- * Smooth deceleration to the end
+ * Sine ease-out interpolation.
+ * Fast start with smooth sinusoidal deceleration to the end.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value with sine-based deceleration toward end
+ *
+ * @example
+ * SineEaseOut(0, 10, 0)   // 0
+ * SineEaseOut(0, 10, 1)   // 10
+ * SineEaseOut(0, 10, 0.5) // ~7.07 (faster than LinearInterpolation's 5 at midpoint)
  */
 export function SineEaseOut(a, b, t) {
     // Allow extrapolation by not clamping t
     return a + ((b - a) * Math.sin((t * Math.PI) / 2));
 }
 /**
- * Exponential ease-in interpolation
- * Very slow start, then rapid acceleration
+ * Exponential ease-in interpolation (2^(10t−10)).
+ * Very slow start, then rapid exponential acceleration.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value with exponential acceleration from start
+ *
+ * @example
+ * ExponentialEaseIn(0, 10, 0)    // 0
+ * ExponentialEaseIn(0, 10, 1)    // 10
+ * ExponentialEaseIn(0, 10, 0.5)  // ~0.31 (barely moved at midpoint)
  */
 export function ExponentialEaseIn(a, b, t) {
     // Allow extrapolation by not clamping t
@@ -132,8 +235,18 @@ export function ExponentialEaseIn(a, b, t) {
     return a + ((b - a) * expT);
 }
 /**
- * Exponential ease-out interpolation
- * Rapid start, then very slow deceleration
+ * Exponential ease-out interpolation (1 − 2^(−10t)).
+ * Rapid start, then very slow exponential deceleration.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value with exponential deceleration toward end
+ *
+ * @example
+ * ExponentialEaseOut(0, 10, 0)   // 0
+ * ExponentialEaseOut(0, 10, 1)   // 10
+ * ExponentialEaseOut(0, 10, 0.5) // ~9.69 (nearly done at midpoint)
  */
 export function ExponentialEaseOut(a, b, t) {
     // Allow extrapolation by not clamping t
@@ -141,8 +254,18 @@ export function ExponentialEaseOut(a, b, t) {
     return a + ((b - a) * expT);
 }
 /**
- * Elastic ease-out - bouncy spring-like motion
- * Creates an overshoot effect that bounces back
+ * Elastic ease-out — bouncy spring-like motion.
+ * Creates an overshoot effect that oscillates before settling at the endpoint.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — clamped to [0, 1] at t=0 and t=1 boundaries
+ * @returns Interpolated value with elastic overshoot effect toward end
+ *
+ * @example
+ * ElasticEaseOut(0, 10, 0)   // 0
+ * ElasticEaseOut(0, 10, 1)   // 10
+ * ElasticEaseOut(0, 10, 0.8) // ~10.86 (overshoots target before settling)
  */
 export function ElasticEaseOut(a, b, t) {
     // Allow extrapolation by not clamping t
@@ -154,8 +277,18 @@ export function ElasticEaseOut(a, b, t) {
     return a + ((b - a) * elasticT);
 }
 /**
- * Back ease-out - overshoots then settles
- * Creates a slight overshoot before settling at the target
+ * Back ease-out — overshoots then settles.
+ * Creates a slight overshoot beyond the target before settling into place.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value with back overshoot effect toward end
+ *
+ * @example
+ * BackEaseOut(0, 10, 0)    // 0
+ * BackEaseOut(0, 10, 1)    // 10
+ * BackEaseOut(0, 10, 0.75) // ~10.88 (overshoots before settling)
  */
 export function BackEaseOut(a, b, t) {
     // Allow extrapolation by not clamping t
@@ -165,8 +298,18 @@ export function BackEaseOut(a, b, t) {
     return a + ((b - a) * backT);
 }
 /**
- * Bounce ease-out - bouncing ball effect
- * Simulates a ball bouncing to rest
+ * Bounce ease-out — simulates a ball bouncing to rest.
+ * Produces a series of bounces with decreasing amplitude before settling at the endpoint.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value with bouncing effect toward end
+ *
+ * @example
+ * BounceEaseOut(0, 10, 0)   // 0
+ * BounceEaseOut(0, 10, 1)   // 10
+ * BounceEaseOut(0, 10, 0.5) // ~7.65 (mid-bounce)
  */
 export function BounceEaseOut(a, b, t) {
     // Allow extrapolation by not clamping t
@@ -191,8 +334,20 @@ export function BounceEaseOut(a, b, t) {
     return a + ((b - a) * bounceT);
 }
 /**
- * Catmull-Rom spline interpolation between 4 points
- * Useful for smooth curves through multiple points
+ * Catmull-Rom spline interpolation between four control points.
+ * Produces a smooth curve that passes through p1 and p2 with tangents influenced by p0 and p3.
+ *
+ * @param p0 - Previous control point (influences the tangent at p1)
+ * @param p1 - Start point (result when t = 0)
+ * @param p2 - End point (result when t = 1)
+ * @param p3 - Next control point (influences the tangent at p2)
+ * @param t - Interpolation parameter (typically [0, 1], supports extrapolation)
+ * @returns Smoothly interpolated value along the Catmull-Rom spline
+ *
+ * @example
+ * CatmullRomInterpolation(0, 5, 10, 15, 0)   // 5  (at p1)
+ * CatmullRomInterpolation(0, 5, 10, 15, 1)   // 10 (at p2)
+ * CatmullRomInterpolation(0, 5, 10, 15, 0.5) // 7.5
  */
 export function CatmullRomInterpolation(p0, p1, p2, p3, t) {
     // Allow extrapolation by not clamping t
@@ -201,8 +356,20 @@ export function CatmullRomInterpolation(p0, p1, p2, p3, t) {
     return CATMULL_HALF * ((2 * p1) + ((-p0 + p2) * t) + (((2 * p0) - (CATMULL_5 * p1) + (QUARTIC * p2) - p3) * t2) + ((-p0 + (CUBIC * p1) - (CUBIC * p2) + p3) * t3));
 }
 /**
- * Hermite interpolation with tangent control
- * Provides precise control over curve tangents at endpoints
+ * Hermite spline interpolation with explicit tangent control.
+ * Provides precise control over the curve's tangent at both the start and end points.
+ *
+ * @param p0 - Start point (result when t = 0)
+ * @param p1 - End point (result when t = 1)
+ * @param t0 - Tangent (velocity) at the start point
+ * @param t1 - Tangent (velocity) at the end point
+ * @param t - Interpolation parameter (typically [0, 1], supports extrapolation)
+ * @returns Interpolated value along the Hermite spline
+ *
+ * @example
+ * HermiteInterpolation(0, 10, 0, 0, 0)   // 0  (at start)
+ * HermiteInterpolation(0, 10, 0, 0, 1)   // 10 (at end)
+ * HermiteInterpolation(0, 10, 0, 0, 0.5) // 5  (flat tangents → same as LERP at midpoint)
  */
 export function HermiteInterpolation(p0, p1, t0, t1, t) {
     // Allow extrapolation by not clamping t
@@ -215,24 +382,55 @@ export function HermiteInterpolation(p0, p1, t0, t1, t) {
     return (h00 * p0) + (h10 * t0) + (h01 * p1) + (h11 * t1);
 }
 /**
- * Circular ease-in interpolation
- * Creates an accelerating curve based on quarter circle
+ * Circular ease-in interpolation (1 − √(1−t²)).
+ * Creates an accelerating curve based on the first quarter of a circle.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — clamped to [0, 1] for a valid circular arc
+ * @returns Interpolated value with circular acceleration from start
+ *
+ * @example
+ * CircularEaseIn(0, 10, 0)   // 0
+ * CircularEaseIn(0, 10, 1)   // 10
+ * CircularEaseIn(0, 10, 0.5) // ~1.34 (very slow start along circular arc)
  */
 export function CircularEaseIn(a, b, t) {
     // Allow extrapolation by not clamping t
     return a + ((b - a) * (1 - Math.sqrt(1 - (t * t))));
 }
 /**
- * Circular ease-out interpolation
- * Creates a decelerating curve based on quarter circle
+ * Circular ease-out interpolation (√(1−(t−1)²)).
+ * Creates a decelerating curve based on the first quarter of a circle.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — clamped to [0, 1] for a valid circular arc
+ * @returns Interpolated value with circular deceleration toward end
+ *
+ * @example
+ * CircularEaseOut(0, 10, 0)   // 0
+ * CircularEaseOut(0, 10, 1)   // 10
+ * CircularEaseOut(0, 10, 0.5) // ~8.66 (very fast start along circular arc)
  */
 export function CircularEaseOut(a, b, t) {
     // Allow extrapolation by not clamping t
     return a + ((b - a) * Math.sqrt(1 - Math.pow(t - 1, 2)));
 }
 /**
- * Quadratic ease-in-out interpolation (2t² for t<0.5, 1−(−2t+2)²/2 for t≥0.5)
- * Symmetrically accelerates at the start and decelerates at the end
+ * Quadratic ease-in-out interpolation (2t² for t < 0.5, 1 − (−2t+2)²/2 for t ≥ 0.5).
+ * Symmetrically accelerates at the start and decelerates at the end.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter (typically [0, 1])
+ * @returns Interpolated value with quadratic symmetric easing
+ *
+ * @example
+ * QuadraticEaseInOut(0, 10, 0)    // 0
+ * QuadraticEaseInOut(0, 10, 1)    // 10
+ * QuadraticEaseInOut(0, 10, 0.25) // 1.25 (slow start)
+ * QuadraticEaseInOut(0, 10, 0.75) // 8.75 (slow end)
  */
 export function QuadraticEaseInOut(a, b, t) {
     const smoothT = t < EASE_INOUT_HALF
@@ -241,8 +439,19 @@ export function QuadraticEaseInOut(a, b, t) {
     return a + ((b - a) * smoothT);
 }
 /**
- * Cubic ease-in-out interpolation (4t³ for t<0.5, 1−(−2t+2)³/2 for t≥0.5)
- * More pronounced symmetrical acceleration/deceleration than quadratic
+ * Cubic ease-in-out interpolation (4t³ for t < 0.5, 1 − (−2t+2)³/2 for t ≥ 0.5).
+ * More pronounced symmetrical acceleration/deceleration than quadratic ease-in-out.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter (typically [0, 1])
+ * @returns Interpolated value with cubic symmetric easing
+ *
+ * @example
+ * CubicEaseInOut(0, 10, 0)    // 0
+ * CubicEaseInOut(0, 10, 1)    // 10
+ * CubicEaseInOut(0, 10, 0.25) // 0.625 (very slow start)
+ * CubicEaseInOut(0, 10, 0.75) // 9.375 (very slow end)
  */
 export function CubicEaseInOut(a, b, t) {
     const smoothT = t < EASE_INOUT_HALF
@@ -251,16 +460,36 @@ export function CubicEaseInOut(a, b, t) {
     return a + ((b - a) * smoothT);
 }
 /**
- * Sine ease-in-out interpolation (−(cos(πt)−1)/2)
- * Smooth symmetric easing using cosine — gentle and natural feeling
+ * Sine ease-in-out interpolation (−(cos(πt) − 1) / 2).
+ * Smooth symmetric easing using cosine — gentle and natural feeling.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter (typically [0, 1])
+ * @returns Interpolated value with sine-based symmetric easing
+ *
+ * @example
+ * SineEaseInOut(0, 10, 0)   // 0
+ * SineEaseInOut(0, 10, 1)   // 10
+ * SineEaseInOut(0, 10, 0.5) // 5 (symmetric midpoint)
  */
 export function SineEaseInOut(a, b, t) {
     const smoothT = -(Math.cos(t * Math.PI) - 1) / 2;
     return a + ((b - a) * smoothT);
 }
 /**
- * Exponential ease-in-out interpolation
- * Very slow at both ends, extremely rapid in the middle
+ * Exponential ease-in-out interpolation.
+ * Very slow at both ends with an extremely rapid transition in the middle.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter (typically [0, 1])
+ * @returns Interpolated value with exponential symmetric easing
+ *
+ * @example
+ * ExponentialEaseInOut(0, 10, 0)    // 0
+ * ExponentialEaseInOut(0, 10, 1)    // 10
+ * ExponentialEaseInOut(0, 10, 0.25) // ~0.16 (barely moving in the first quarter)
  */
 export function ExponentialEaseInOut(a, b, t) {
     if (t === 0)
@@ -273,8 +502,18 @@ export function ExponentialEaseInOut(a, b, t) {
     return a + ((b - a) * expT);
 }
 /**
- * Circular ease-in-out interpolation
- * Smooth symmetric arc-based easing
+ * Circular ease-in-out interpolation.
+ * Smooth symmetric arc-based easing using a circular curve.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter (typically [0, 1])
+ * @returns Interpolated value with circular symmetric easing
+ *
+ * @example
+ * CircularEaseInOut(0, 10, 0)    // 0
+ * CircularEaseInOut(0, 10, 1)    // 10
+ * CircularEaseInOut(0, 10, 0.25) // ~0.67 (very slow circular start)
  */
 export function CircularEaseInOut(a, b, t) {
     const smoothT = t < EASE_INOUT_HALF
@@ -283,8 +522,18 @@ export function CircularEaseInOut(a, b, t) {
     return a + ((b - a) * smoothT);
 }
 /**
- * Elastic ease-in interpolation
- * Spring-like acceleration from rest — starts with a bounce-back then launches forward
+ * Elastic ease-in interpolation.
+ * Spring-like acceleration from rest — starts with a backward oscillation then launches forward.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — clamped to [0, 1] at t=0 and t=1 boundaries
+ * @returns Interpolated value with elastic spring acceleration from start
+ *
+ * @example
+ * ElasticEaseIn(0, 10, 0)   // 0
+ * ElasticEaseIn(0, 10, 1)   // 10
+ * ElasticEaseIn(0, 10, 0.5) // ~-0.16 (backward oscillation at midpoint before launching)
  */
 export function ElasticEaseIn(a, b, t) {
     if (t === 0 || t === 1)
@@ -294,8 +543,18 @@ export function ElasticEaseIn(a, b, t) {
     return a + ((b - a) * elasticT);
 }
 /**
- * Elastic ease-in-out interpolation
- * Spring-like oscillation at both the start and end
+ * Elastic ease-in-out interpolation.
+ * Spring-like oscillation at both the start and end of the motion.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — clamped to [0, 1] at t=0 and t=1 boundaries
+ * @returns Interpolated value with elastic oscillation at both ends
+ *
+ * @example
+ * ElasticEaseInOut(0, 10, 0)   // 0
+ * ElasticEaseInOut(0, 10, 1)   // 10
+ * ElasticEaseInOut(0, 10, 0.4) // ~-1.17 (backward oscillation before midpoint)
  */
 export function ElasticEaseInOut(a, b, t) {
     if (t === 0 || t === 1)
@@ -307,8 +566,18 @@ export function ElasticEaseInOut(a, b, t) {
     return a + ((b - a) * elasticT);
 }
 /**
- * Back ease-in interpolation (c3t³ − c1t²)
- * Slight backward pull before launching forward
+ * Back ease-in interpolation (c3t³ − c1t²).
+ * Slight backward pull before launching forward — like winding up before a throw.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value with back overshoot at start
+ *
+ * @example
+ * BackEaseIn(0, 10, 0)    // 0
+ * BackEaseIn(0, 10, 1)    // 10
+ * BackEaseIn(0, 10, 0.25) // ~-0.64 (dips below start before accelerating forward)
  */
 export function BackEaseIn(a, b, t) {
     const c1 = 1.70158;
@@ -317,8 +586,18 @@ export function BackEaseIn(a, b, t) {
     return a + ((b - a) * backT);
 }
 /**
- * Back ease-in-out interpolation
- * Slight backward pull at both ends before and after the main motion
+ * Back ease-in-out interpolation.
+ * Slight backward pull at both ends before and after the main forward motion.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value with back overshoot at both start and end
+ *
+ * @example
+ * BackEaseInOut(0, 10, 0)    // 0
+ * BackEaseInOut(0, 10, 1)    // 10
+ * BackEaseInOut(0, 10, 0.25) // ~-1.00 (dips backward at start)
  */
 export function BackEaseInOut(a, b, t) {
     const c1 = 1.70158;
@@ -329,15 +608,35 @@ export function BackEaseInOut(a, b, t) {
     return a + ((b - a) * backT);
 }
 /**
- * Bounce ease-in interpolation
- * Bouncing ball effect with bounces at the start before settling at the target
+ * Bounce ease-in interpolation.
+ * Bouncing ball effect at the start — multiple bounces before launching toward the target.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value with bounce effect at start
+ *
+ * @example
+ * BounceEaseIn(0, 10, 0)   // 0
+ * BounceEaseIn(0, 10, 1)   // 10
+ * BounceEaseIn(0, 10, 0.5) // ~2.34 (still bouncing at midpoint)
  */
 export function BounceEaseIn(a, b, t) {
     return a + ((b - a) * (1 - BounceEaseOut(0, 1, 1 - t)));
 }
 /**
- * Bounce ease-in-out interpolation
- * Bouncing ball effect at both the start and the end
+ * Bounce ease-in-out interpolation.
+ * Bouncing ball effect at both the start and end of the motion.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Interpolated value with bounce effect at both start and end
+ *
+ * @example
+ * BounceEaseInOut(0, 10, 0)    // 0
+ * BounceEaseInOut(0, 10, 1)    // 10
+ * BounceEaseInOut(0, 10, 0.25) // ~1.17 (bouncing at start quarter)
  */
 export function BounceEaseInOut(a, b, t) {
     const bounceT = t < EASE_INOUT_HALF
@@ -346,8 +645,20 @@ export function BounceEaseInOut(a, b, t) {
     return a + ((b - a) * bounceT);
 }
 /**
- * Step interpolation - instant transition at threshold
- * Useful for discrete state changes
+ * Step interpolation — instant transition at a configurable threshold.
+ * Returns `a` when `t` is below the threshold, and `b` at or above it.
+ * Useful for discrete state changes and on/off animations.
+ *
+ * @param a - Start value (returned when t < threshold)
+ * @param b - End value (returned when t ≥ threshold)
+ * @param t - Interpolation parameter (clamped to [0, 1])
+ * @param threshold - Normalized transition point (default: 0.5; clamped to [0, 1])
+ * @returns Either `a` or `b` depending on `t` relative to `threshold`
+ *
+ * @example
+ * StepInterpolation(0, 10, 0.3)        // 0  (below default threshold of 0.5)
+ * StepInterpolation(0, 10, 0.7)        // 10 (at or above default threshold of 0.5)
+ * StepInterpolation(0, 10, 0.3, 0.25)  // 10 (above custom threshold of 0.25)
  */
 export function StepInterpolation(a, b, t, threshold = 0.5) {
     const clampedT = Clamp(t, 0, 1);
@@ -355,9 +666,15 @@ export function StepInterpolation(a, b, t, threshold = 0.5) {
     return clampedT < clampedThreshold ? a : b;
 }
 /**
- * Spherical linear interpolation for scalar values
- * Provides smooth interpolation along a spherical arc
- * Note: For true SLERP with vectors, use VectorSphericalLinearInterpolation
+ * Spherical linear interpolation for scalar values.
+ * For scalar inputs, this is mathematically equivalent to {@link LinearInterpolation}.
+ * For true spherical rotation interpolation, use `QuaternionSLERP` from the quaternions module.
+ *
+ * @param a - Start value (result when t = 0)
+ * @param b - End value (result when t = 1)
+ * @param t - Interpolation parameter — unclamped, allowing extrapolation
+ * @returns Linearly interpolated value (identical to `LinearInterpolation(a, b, t)`)
+ *
  * @deprecated This function is identical to LinearInterpolation and is not a true spherical interpolation. For quaternion spherical interpolation, use QuaternionSLERP from the quaternions module.
  */
 export function SphericalLinearInterpolation(a, b, t) {