Skip to content

Create polished demo videos without editing skills. Mac/Windows/Linux

8.2 KB
Raw Blame
// Friendly reminder: Recordly is licensed under AGPL-3.0, author @webadderall, repo-> https://github.com/webadderall/Recordly
// Please use this code with the right attribution.

export interface SpringState {
	value: number;
	velocity: number;
	initialized: boolean;
}

export interface SpringConfig {
	stiffness: number;
	damping: number;
	mass: number;
	restDelta?: number;
	restSpeed?: number;
}

export interface CursorSpringTuning {
	stiffnessMultiplier?: number;
	dampingMultiplier?: number;
	massMultiplier?: number;
}

const CURSOR_SMOOTHING_MIN = 0;
const CURSOR_SMOOTHING_MAX = 2;
const CURSOR_SMOOTHING_LEGACY_MAX = 0.5;
const DEFAULT_CURSOR_STIFFNESS_BOOST = 1.12;

function clampSpringMultiplier(value: number | undefined) {
	if (typeof value !== "number" || !Number.isFinite(value)) {
		return 1;
	}

	const numericValue = value;
	return Math.min(3, Math.max(0.25, numericValue));
}

function applyCursorSpringTuning(config: SpringConfig, tuning?: CursorSpringTuning): SpringConfig {
	return {
		...config,
		stiffness: config.stiffness * clampSpringMultiplier(tuning?.stiffnessMultiplier),
		damping: config.damping * clampSpringMultiplier(tuning?.dampingMultiplier),
		mass: config.mass * clampSpringMultiplier(tuning?.massMultiplier),
	};
}

export function createSpringState(initialValue = 0): SpringState {
	return {
		value: initialValue,
		velocity: 0,
		initialized: false,
	};
}

export function resetSpringState(state: SpringState, initialValue?: number) {
	if (typeof initialValue === "number") {
		state.value = initialValue;
	}

	state.velocity = 0;
	state.initialized = false;
}

export function clampDeltaMs(deltaMs: number, fallbackMs = 1000 / 60) {
	if (!Number.isFinite(deltaMs) || deltaMs <= 0) {
		return fallbackMs;
	}

	return Math.min(80, Math.max(1, deltaMs));
}

/**
 * Damped harmonic oscillator spring solver.
 *
 * Implements Hooke's law  F = −kx − cv  (stiffness k, damping c, mass m)
 * with the closed-form analytic solution for the three damping regimes:
 *   ζ < 1  →  underdamped  (oscillates then settles)
 *   ζ = 1  →  critically damped  (fastest non-oscillating convergence)
 *   ζ > 1  →  overdamped  (exponential decay, no oscillation)
 *
 * where  ζ = c / (2√(km))  and  ω₀ = √(k/m).
 *
 * All time inputs are in seconds internally.
 */

function msToSec(ms: number) {
	return ms / 1000;
}

function resolveSpringPosition(
	t: number,
	target: number,
	initialDelta: number,
	initialVelocity: number,
	dampingRatio: number,
	undampedAngularFreq: number,
): number {
	if (dampingRatio < 1) {
		// Underdamped — oscillatory envelope
		const dampedFreq = undampedAngularFreq * Math.sqrt(1 - dampingRatio * dampingRatio);
		const envelope = Math.exp(-dampingRatio * undampedAngularFreq * t);
		return (
			target -
			envelope *
				(((initialVelocity + dampingRatio * undampedAngularFreq * initialDelta) /
					dampedFreq) *
					Math.sin(dampedFreq * t) +
					initialDelta * Math.cos(dampedFreq * t))
		);
	}

	if (dampingRatio === 1) {
		// Critically damped — no oscillation, fastest convergence
		return (
			target -
			Math.exp(-undampedAngularFreq * t) *
				(initialDelta + (initialVelocity + undampedAngularFreq * initialDelta) * t)
		);
	}

	// Overdamped — exponential decay, no oscillation
	const dampedFreq = undampedAngularFreq * Math.sqrt(dampingRatio * dampingRatio - 1);
	const envelope = Math.exp(-dampingRatio * undampedAngularFreq * t);
	const freqT = Math.min(dampedFreq * t, 300); // cap to avoid Infinity in sinh/cosh
	return (
		target -
		(envelope *
			((initialVelocity + dampingRatio * undampedAngularFreq * initialDelta) *
				Math.sinh(freqT) +
				dampedFreq * initialDelta * Math.cosh(freqT))) /
			dampedFreq
	);
}

export function stepSpringValue(
	state: SpringState,
	target: number,
	deltaMs: number,
	config: SpringConfig,
) {
	const safeDeltaMs = clampDeltaMs(deltaMs);

	if (!state.initialized || !Number.isFinite(state.value)) {
		state.value = target;
		state.velocity = 0;
		state.initialized = true;
		return state.value;
	}

	const restDelta = config.restDelta ?? 0.0005;
	const restSpeed = config.restSpeed ?? 0.02;

	if (Math.abs(target - state.value) <= restDelta && Math.abs(state.velocity) <= restSpeed) {
		state.value = target;
		state.velocity = 0;
		return state.value;
	}

	const { stiffness, damping, mass } = config;
	const undampedAngularFreq = Math.sqrt(stiffness / mass);
	const dampingRatio = damping / (2 * Math.sqrt(stiffness * mass));
	const initialDelta = target - state.value;
	const initialVelocity = -state.velocity;
	const tSec = msToSec(safeDeltaMs);

	const current = resolveSpringPosition(
		tSec,
		target,
		initialDelta,
		initialVelocity,
		dampingRatio,
		undampedAngularFreq,
	);

	// Overshoot guard for overdamped / critically-damped springs (ζ ≥ 1).
	// With a fixed target an overdamped spring never overshoots, but when
	// the target moves every frame (zoom easing curve) carried-over velocity
	// can push the value past the new target → wobble on reversal.
	// Clamping to target keeps the original animation speed while preventing
	// the jelly-like counter-oscillation.
	if (dampingRatio >= 1) {
		const crossed =
			(state.value <= target && current > target) ||
			(state.value >= target && current < target);
		if (crossed) {
			state.value = target;
			state.velocity = 0;
			return state.value;
		}
	}

	// Analytical velocity via forward-difference on the closed-form solution.
	const epsilon = 0.0001;
	const ahead = resolveSpringPosition(
		tSec + epsilon,
		target,
		initialDelta,
		initialVelocity,
		dampingRatio,
		undampedAngularFreq,
	);
	const analyticalVelocity = (ahead - current) / epsilon; // value per second

	const isBelowVelocityThreshold = Math.abs(analyticalVelocity) <= restSpeed;
	const isBelowDisplacementThreshold = Math.abs(target - current) <= restDelta;
	const isDone = isBelowVelocityThreshold && isBelowDisplacementThreshold;

	if (isDone) {
		state.value = target;
		state.velocity = 0;
	} else {
		state.value = current;
		state.velocity = analyticalVelocity;
	}

	return state.value;
}

export function getCursorSpringConfig(
	smoothingFactor: number,
	tuning?: CursorSpringTuning,
): SpringConfig {
	const clamped = Math.min(CURSOR_SMOOTHING_MAX, Math.max(CURSOR_SMOOTHING_MIN, smoothingFactor));

	if (clamped <= 0) {
		return applyCursorSpringTuning(
			{
				stiffness: 1000,
				damping: 100,
				mass: 1,
				restDelta: 0.0001,
				restSpeed: 0.001,
			},
			tuning,
		);
	}

	if (clamped <= CURSOR_SMOOTHING_LEGACY_MAX) {
		const legacyNormalized = Math.min(
			1,
			Math.max(
				0,
				(clamped - CURSOR_SMOOTHING_MIN) /
					(CURSOR_SMOOTHING_LEGACY_MAX - CURSOR_SMOOTHING_MIN),
			),
		);

		return applyCursorSpringTuning(
			{
				stiffness: (760 - legacyNormalized * 420) * DEFAULT_CURSOR_STIFFNESS_BOOST,
				damping: 34 + legacyNormalized * 24,
				mass: 0.85 + legacyNormalized * 0.55,
				restDelta: 0.0002,
				restSpeed: 0.01,
			},
			tuning,
		);
	}

	const extendedNormalized = Math.min(
		1,
		Math.max(
			0,
			(clamped - CURSOR_SMOOTHING_LEGACY_MAX) /
				(CURSOR_SMOOTHING_MAX - CURSOR_SMOOTHING_LEGACY_MAX),
		),
	);

	return applyCursorSpringTuning(
		{
			stiffness: (340 - extendedNormalized * 180) * DEFAULT_CURSOR_STIFFNESS_BOOST,
			damping: 58 + extendedNormalized * 22,
			mass: 1.35 + extendedNormalized * 0.45,
			restDelta: 0.0002,
			restSpeed: 0.01,
		},
		tuning,
	);
}

export function getZoomSpringConfig(
	smoothnessFactor = 0.5,
	tuning?: CursorSpringTuning,
): SpringConfig {
	const clamped = Math.max(0, Math.min(1, smoothnessFactor));

	if (clamped <= 0) {
		return applyCursorSpringTuning(
			{
				stiffness: 1000,
				damping: 100,
				mass: 1,
				restDelta: 0.0001,
				restSpeed: 0.001,
			},
			tuning,
		);
	}

	// Map 0-1 slider to the internal 0-2 spring range so that
	// smoothness=1 gives the same feel as the old smoothness=2.
	const scaled = clamped * 2;

	// Hooke's law spring: F = -kx - cv
	// Damping ratio ζ = c / (2√(km)) ≈ 1.05 — barely overdamped.
	// The overshoot clamp in stepSpringValue prevents wobble even at
	// this low damping, so animations stay fast and responsive.
	// Higher scaled → lower stiffness + higher mass → slower, floatier settle.
	return applyCursorSpringTuning(
		{
			stiffness: 100 / scaled,
			damping: 21,
			mass: 1.0 * scaled,
			restDelta: 0.0005,
			restSpeed: 0.015,
		},
		tuning,
	);
}