anim-engine 0.3.2 → 0.5.0

package/dist/domain/interpolation.d.ts

@@ -1,10 +1,158 @@
-export type InterpolationStatus = "active" | "inactive" | "dead";
+import { DynamicValue } from './resolve-value';
+import { ExternalTicker } from './ticker';
+/**
+ * Represents the status of an interpolation, which can be either "active" or "inactive".
+ */
+export type InterpolationStatus = "active" | "inactive";
+/**
+ * Represents an interpolation process that can be controlled and monitored.
+ *
+ * The interpolation can be resumed or stopped, and its current value, velocity, and status can be accessed.
+ */
 export type Interpolation = {
-    start: () => void;
+    /**
+     * Resumes the interpolation if it is currently inactive.
+     */
+    resume: () => void;
+    /**
+     * Stops the interpolation if it is currently active.
+     */
     stop: () => void;
-    kill: () => void;
-    setCurrentValue: (value: number) => void;
-    currentValue: number;
+    /**
+     * Sets the current value of the interpolation instantly and resets its velocity to zero.
+     */
+    setValue: (value: number) => void;
+    /**
+     * The current value of the interpolation.
+     */
+    value: number;
+    /**
+     * The current velocity of the interpolation.
+     */
     velocity: number;
+    /**
+     * The current status of the interpolation, which can be "active" or "inactive".
+     */
     status: InterpolationStatus;
 };
+/**
+ * Options for configuring a linear interpolation (lerp) function.
+ */
+export type LerpOptions = {
+    /**
+     * A function that returns the starting value for the interpolation. This is evaluated every frame.
+     */
+    to: () => number;
+    /**
+     * A function that returns the ending value for the interpolation. This is evaluated every frame if a function is provided.
+     */
+    smoothTimeMs: DynamicValue;
+    /**
+     * The precision threshold for determining when the interpolation has effectively reached its target. Defaults to 0.01.
+     */
+    precision?: number;
+    /**
+     * A callback function that is called on every update of the interpolation, receiving the current value and velocity as arguments.
+     */
+    onUpdate?: (value: number, velocity: number) => void;
+    /**
+     * A callback function that is called when the interpolation has effectively reached its target and is considered complete.
+     */
+    onEnded?: () => void;
+    /**
+     * An optional external ticker that can be provided to control the timing of the interpolation updates. If not provided, a default ticker will be used.
+     */
+    ticker?: ExternalTicker;
+};
+/**
+ * Options for configuring a smooth damped interpolation.
+ *
+ * Smooth damp progressively moves toward a target value with velocity that
+ * decreases as it approaches, producing a natural deceleration effect.
+ */
+export type SmoothDampOptions = {
+    /**
+     * A function that returns the target value to smoothly move toward.
+     * This is evaluated every frame, allowing the target to change dynamically.
+     */
+    to: () => number;
+    /**
+     * The approximate time (in milliseconds) it takes for the value to settle
+     * at the target. Larger values produce slower, more gradual movement.
+     */
+    smoothTimeMs: DynamicValue;
+    /**
+     * An optional maximum speed cap (in units/second). Prevents excessively
+     * fast movement when the gap between current and target is large.
+     */
+    maxSpeed?: DynamicValue;
+    /**
+     * The precision threshold for determining when the interpolation has
+     * effectively reached its target. Defaults to 0.01.
+     */
+    precision?: number;
+    /**
+     * A callback function that is called on every update of the interpolation,
+     * receiving the current value and velocity as arguments.
+     */
+    onUpdate?: (value: number, velocity: number) => void;
+    /**
+     * A callback function that is called when the interpolation has effectively
+     * reached its target and is considered complete.
+     */
+    onEnded?: () => void;
+    /**
+     * An optional external ticker that can be provided to control the timing of
+     * the interpolation updates. If not provided, a default ticker will be used.
+     */
+    ticker?: ExternalTicker;
+};
+/**
+ * Options for configuring a spring-based interpolation.
+ *
+ * Spring physics simulate mass-spring-damper motion, producing bouncy or
+ * elastic movement toward the target value.
+ */
+export type SpringOptions = {
+    /**
+     * A function that returns the target value toward which the spring pulls.
+     * This is evaluated every frame, allowing the target to change dynamically.
+     */
+    to: () => number;
+    /**
+     * The stiffness of the spring. Higher values produce faster, snappier motion.
+     * Defaults to 180.
+     */
+    stiffness?: DynamicValue;
+    /**
+     * The damping coefficient. Higher values reduce oscillation and settling time.
+     * Defaults to 12.
+     */
+    damping?: DynamicValue;
+    /**
+     * The mass of the simulated object. Higher values produce slower, heavier
+     * motion. Defaults to 1.
+     */
+    mass?: DynamicValue;
+    /**
+     * The precision threshold for determining when the spring has effectively
+     * settled at its target (both position and velocity within tolerance).
+     * Defaults to 0.01.
+     */
+    precision?: number;
+    /**
+     * A callback function that is called on every update of the spring,
+     * receiving the current value and velocity as arguments.
+     */
+    onUpdate?: (value: number, velocity: number) => void;
+    /**
+     * A callback function that is called when the spring has effectively
+     * settled at its target and is considered complete.
+     */
+    onEnded?: () => void;
+    /**
+     * An optional external ticker that can be provided to control the timing of
+     * the spring updates. If not provided, a default ticker will be used.
+     */
+    ticker?: ExternalTicker;
+};

package/dist/domain/resolve-value.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Represents a value that can either be a static number or a function
+ * that returns a number. Functions are re-evaluated each time the value
+ * is resolved, allowing dynamic values that change over time.
+ */
 export type DynamicValue = number | (() => number);
+/**
+ * Resolves a {@link DynamicValue} to a concrete number.
+ * If the value is a function, it is called and its return value is used.
+ * If the value is a number, it is returned directly.
+ *
+ * @param value - The dynamic value to resolve.
+ * @returns The resolved number.
+ */
 export declare const resolveValue: (value: DynamicValue) => number;

package/dist/domain/resolve-value.js

@@ -1,4 +1,12 @@
 //#region src/domain/resolve-value.ts
+/**
+* Resolves a {@link DynamicValue} to a concrete number.
+* If the value is a function, it is called and its return value is used.
+* If the value is a number, it is returned directly.
+*
+* @param value - The dynamic value to resolve.
+* @returns The resolved number.
+*/
 var resolveValue = (value) => typeof value === "function" ? value() : value;
 //#endregion
 export { resolveValue };

package/dist/domain/ticker.d.ts

@@ -1,24 +1,36 @@
+/**
+ * A function that is called on each tick with the elapsed time in milliseconds.
+ *
+ * @param deltaMs - The time elapsed since the last tick in milliseconds.
+ */
 export type TickHandler = (deltaMs: number) => void;
+/**
+ * A ticker that drives frame updates. It manages a list of {@link TickHandler}
+ * callbacks and distributes time updates to them on each frame.
+ */
 export type Ticker = {
+    /** Starts the ticker, beginning to dispatch updates to registered handlers. */
     start: () => void;
+    /** Stops the ticker, halting further dispatch of updates. */
     stop: () => void;
+    /**
+     * Manually advances the ticker by the given delta, dispatching to all
+     * registered handlers.
+     */
     update: (deltaMs: number) => void;
+    /** Registers a handler to receive tick updates. */
     add: (handler: TickHandler) => void;
+    /** Unregisters a previously registered handler. */
     remove: (handler: TickHandler) => void;
 };
-/** Returns the default ticker singleton. Created lazily on first access. */
-export declare const getTicker: () => Ticker;
 /**
- * Create a ticker that drives active animations.
- *
- * Does NOT auto-start. The user must explicitly call either:
- * - `start()` — begins a `requestAnimationFrame` loop
- * - `update(deltaMs)` — drive manually from a game loop
- *
- * `add()` and `remove()` register/unregister animations without
- * side effects on the rAF loop.
- *
- * Uses a flat array with undefined-tombstone removal for safe concurrent
- * modification during iteration. Compacted after each frame.
+ * A minimal ticker interface exposing only subscription capabilities.
+ * Useful for external tickers (e.g. from a game loop or an animation
+ * framework) where start/stop/update are managed externally.
  */
-export declare const createTicker: () => Ticker;
+export type ExternalTicker = {
+    /** Registers a handler to receive tick updates. */
+    add: (handler: TickHandler) => void;
+    /** Unregisters a previously registered handler. */
+    remove: (handler: TickHandler) => void;
+};

package/dist/domain/timeline.d.ts

@@ -1,5 +1,11 @@
-import { DynamicValue } from '../domain';
 import { KeyframeAnimationOptions, AnimationStatus } from './animation';
+import { DynamicValue } from './resolve-value';
+import { ExternalTicker } from './ticker';
+/**
+ * A single layer in a timeline, describing when an animation plays.
+ * - `at`: The animation starts at this absolute point in time (in ms).
+ * - `gap`: The animation starts this many ms after the previous layer ends.
+ */
 export type TimelineLayer = {
     animation: KeyframeAnimationOptions;
     at: DynamicValue;
@@ -7,15 +13,54 @@ export type TimelineLayer = {
     animation: KeyframeAnimationOptions;
     gap: number;
 };
+/**
+ * Callback hooks and options for a timeline animation.
+ */
+export type TimelineCallbacks = {
+    /** Callback fired when the timeline starts playing. */
+    onStarted?: () => void;
+    /**
+     * Callback fired on each update with the current values and velocities
+     * of all layers in the timeline.
+     */
+    onUpdate?: (values: number[], velocities: number[]) => void;
+    /** Callback fired on each update with the current progress (0 to 1). */
+    onProgress?: (progress: number) => void;
+    /** Callback fired when the timeline ends. */
+    onEnded?: () => void;
+    /** Optional external ticker to drive the timeline. */
+    ticker?: ExternalTicker;
+};
+/**
+ * Represents a timeline animation instance that sequences multiple layers
+ * and can be controlled and queried for its aggregate state.
+ */
 export type Timeline = {
+    /** Plays the timeline from the current state. Returns a promise that resolves when the timeline ends. */
     play: () => Promise<void>;
+    /** Pauses the timeline if it is currently playing. */
     pause: () => void;
+    /** Resumes the timeline if it is currently paused. */
     resume: () => void;
+    /** Stops the timeline and resets its state. */
     stop: () => void;
+    /** Skips the timeline to its end state immediately. */
     skipToEnd: () => void;
-    kill: () => void;
+    /** Sets the progress of the timeline to a specific value between 0 and 1. If playing, pauses. */
     setProgress: (value: number) => void;
+    /** The current progress of the timeline (0 to 1). */
     progress: number;
+    /**
+     * The current status of the timeline, which can be "playing", "paused", or "stopped".
+     * - "playing": The timeline is currently running.
+     * - "paused": The timeline is temporarily halted but can be resumed.
+     * - "stopped": The timeline has finished or has been stopped.
+     */
     status: AnimationStatus;
+    /** The total duration of the timeline in milliseconds. */
     durationMs: number;
+    /** The current values of all layers in the timeline. */
+    values: number[];
+    /** The current velocities of all layers in the timeline. */
+    velocities: number[];
 };

package/dist/index.d.ts

@@ -1,13 +1,10 @@
-export { createAnimation } from './animation/create-animation';
-export { createTimeline } from './timeline/create-timeline';
-export { createSpring } from './spring/create-spring';
-export { createSmoothDamp } from './smooth-damp/create-smooth-damp';
-export { createLerp } from './lerp/create-lerp';
-export { createSmoothClamp } from './smooth-clamp/smooth-clamp';
-export { lerpOklab, hexToRgba } from './color/lerp-oklab';
-export { getTicker, EASE_NAMES, cubicBezier } from './domain';
-export type { EaseName, Interpolation, AnimationStatus, InterpolationStatus, DynamicValue, Animation, Keyframe, AnimationOptions, KeyframeAnimationOptions, TimelineLayer, Timeline, Ticker, } from './domain';
-export type { SpringOptions } from './spring/create-spring';
-export type { SmoothDampOptions } from './smooth-damp/create-smooth-damp';
-export type { LerpOptions } from './lerp/create-lerp';
-export type { RgbaTuple } from './color/lerp-oklab';
+export { createAnimation } from './animation';
+export { createTimeline } from './timeline';
+export { createLerp } from './lerp';
+export { createSmoothDamp } from './smooth-damp';
+export { createSmoothClamp } from './smooth-clamp';
+export { createSpring } from './spring';
+export { lerpRgba, hexToRgba } from './lerp-rgba';
+export { getTicker } from './ticker';
+export { cubicBezier } from './domain';
+export type { EaseName, Interpolation, AnimationStatus, InterpolationStatus, DynamicValue, Animation, Keyframe, AnimationOptions, KeyframeAnimationOptions, TimelineLayer, Timeline, Ticker, LerpOptions, SmoothDampOptions, SpringOptions, RgbaTuple, ExternalTicker, } from './domain';

package/dist/index.js

@@ -1,10 +1,11 @@
-import { EASE_NAMES, cubicBezier } from "./domain/easing.js";
-import { getTicker } from "./domain/ticker.js";
+import { cubicBezier } from "./domain/easing.js";
+import { getTicker } from "./ticker/get-ticker.js";
 import { createAnimation } from "./animation/create-animation.js";
 import { createTimeline } from "./timeline/create-timeline.js";
-import { createSpring } from "./spring/create-spring.js";
-import { createSmoothDamp } from "./smooth-damp/create-smooth-damp.js";
 import { createLerp } from "./lerp/create-lerp.js";
-import { createSmoothClamp } from "./smooth-clamp/smooth-clamp.js";
-import { hexToRgba, lerpOklab } from "./color/lerp-oklab.js";
-export { EASE_NAMES, createAnimation, createLerp, createSmoothClamp, createSmoothDamp, createSpring, createTimeline, cubicBezier, getTicker, hexToRgba, lerpOklab };
+import { createSmoothDamp } from "./smooth-damp/create-smooth-damp.js";
+import { createSmoothClamp } from "./smooth-clamp/create-smooth-clamp.js";
+import { createSpring } from "./spring/create-spring.js";
+import { lerpRgba } from "./lerp-rgba/lerp-rgba.js";
+import { hexToRgba } from "./lerp-rgba/hex-to-rgba.js";
+export { createAnimation, createLerp, createSmoothClamp, createSmoothDamp, createSpring, createTimeline, cubicBezier, getTicker, hexToRgba, lerpRgba };

package/dist/lerp/create-lerp.d.ts

@@ -1,9 +1,14 @@
-import { Interpolation, DynamicValue } from '../domain';
-export type LerpOptions = {
-    to: () => number;
-    smoothTimeMs: DynamicValue;
-    precision?: number;
-    onUpdate?: (value: number, velocity: number) => void;
-    onEnded?: () => void;
-};
-export declare const createLerp: (options: LerpOptions) => Interpolation;
+import { Interpolation, LerpOptions } from '../domain';
+/**
+ * Creates a linear interpolation that smoothly moves a value toward a
+ * target over a specified time constant. Uses exponential decay for a
+ * smooth, asymptotic approach.
+ *
+ * The interpolation automatically starts and runs until it reaches the
+ * target within the configured precision. The target is re-evaluated
+ * every frame, allowing it to change dynamically.
+ *
+ * @param options - Configuration options for the interpolation.
+ * @returns An {@link Interpolation} instance for controlling the lerp.
+ */
+export declare const createLerp: ({ precision, onUpdate, onEnded, to, smoothTimeMs: rawSmoothTimeMs, ticker, }: LerpOptions) => Interpolation;

package/dist/lerp/create-lerp.js

@@ -1,22 +1,30 @@
-import { getTicker } from "../domain/ticker.js";
 import { resolveValue } from "../domain/resolve-value.js";
+import { getTicker } from "../ticker/get-ticker.js";
 import { lerpStep } from "./step.js";
 //#region src/lerp/create-lerp.ts
-var createLerp = (options) => {
-	const precision = options.precision ?? .01;
-	const onUpdate = options.onUpdate;
-	const onEnded = options.onEnded;
+/**
+* Creates a linear interpolation that smoothly moves a value toward a
+* target over a specified time constant. Uses exponential decay for a
+* smooth, asymptotic approach.
+*
+* The interpolation automatically starts and runs until it reaches the
+* target within the configured precision. The target is re-evaluated
+* every frame, allowing it to change dynamically.
+*
+* @param options - Configuration options for the interpolation.
+* @returns An {@link Interpolation} instance for controlling the lerp.
+*/
+var createLerp = ({ precision = .01, onUpdate, onEnded, to, smoothTimeMs: rawSmoothTimeMs, ticker = getTicker() }) => {
 	const state = { current: 0 };
 	let previousValue = 0;
 	let currentVelocity = 0;
 	let active = true;
-	const ticker = getTicker();
-	state.current = options.to();
+	state.current = to();
 	previousValue = state.current;
 	const update = (deltaMs) => {
 		if (!active) return;
-		const target = options.to();
-		const smoothTimeMs = resolveValue(options.smoothTimeMs);
+		const target = to();
+		const smoothTimeMs = resolveValue(rawSmoothTimeMs);
 		lerpStep(state, target, smoothTimeMs, deltaMs);
 		currentVelocity = (state.current - previousValue) / (deltaMs / 1e3);
 		previousValue = state.current;
@@ -28,7 +36,7 @@ var createLerp = (options) => {
 		}
 	};
 	ticker.add(update);
-	const start = () => {
+	const resume = () => {
 		if (active) return;
 		active = true;
 		ticker.add(update);
@@ -37,20 +45,15 @@ var createLerp = (options) => {
 		active = false;
 		ticker.remove(update);
 	};
-	const kill = () => {
-		active = false;
-		ticker.remove(update);
-	};
 	return {
-		start,
+		resume,
 		stop,
-		kill,
-		setCurrentValue: (value) => {
+		setValue: (value) => {
 			state.current = value;
 			previousValue = value;
 			currentVelocity = 0;
 		},
-		get currentValue() {
+		get value() {
 			return state.current;
 		},
 		get velocity() {

package/dist/lerp/index.d.ts

@@ -0,0 +1 @@
+export { createLerp } from './create-lerp';

package/dist/lerp-rgba/hex-to-rgba.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parse a hex color string into an RGBA tuple.
+ *
+ * Accepts formats:
+ *   - `#RGB`
+ *   - `#RGBA`
+ *   - `#RRGGBB`
+ *   - `#RRGGBBAA`
+ *
+ * @param hex - Hex color string with optional leading `#`.
+ * @returns An RGBA tuple [R, G, B, A], each 0–1.
+ */
+export declare const hexToRgba: (hex: string) => [number, number, number, number];

package/dist/lerp-rgba/hex-to-rgba.js

@@ -0,0 +1,48 @@
+//#region src/lerp-rgba/hex-to-rgba.ts
+/**
+* Parse a hex color string into an RGBA tuple.
+*
+* Accepts formats:
+*   - `#RGB`
+*   - `#RGBA`
+*   - `#RRGGBB`
+*   - `#RRGGBBAA`
+*
+* @param hex - Hex color string with optional leading `#`.
+* @returns An RGBA tuple [R, G, B, A], each 0–1.
+*/
+var hexToRgba = (hex) => {
+	const cleaned = hex.startsWith("#") ? hex.slice(1) : hex;
+	if (!/^[0-9a-fA-F]+$/.test(cleaned)) return [
+		0,
+		0,
+		0,
+		1
+	];
+	if (cleaned.length === 3) return [
+		parseInt(cleaned[0] + cleaned[0], 16) / 255,
+		parseInt(cleaned[1] + cleaned[1], 16) / 255,
+		parseInt(cleaned[2] + cleaned[2], 16) / 255,
+		1
+	];
+	if (cleaned.length === 4) return [
+		parseInt(cleaned[0] + cleaned[0], 16) / 255,
+		parseInt(cleaned[1] + cleaned[1], 16) / 255,
+		parseInt(cleaned[2] + cleaned[2], 16) / 255,
+		parseInt(cleaned[3] + cleaned[3], 16) / 255
+	];
+	if (cleaned.length >= 6) return [
+		parseInt(cleaned.slice(0, 2), 16) / 255,
+		parseInt(cleaned.slice(2, 4), 16) / 255,
+		parseInt(cleaned.slice(4, 6), 16) / 255,
+		cleaned.length >= 8 ? parseInt(cleaned.slice(6, 8), 16) / 255 : 1
+	];
+	return [
+		0,
+		0,
+		0,
+		1
+	];
+};
+//#endregion
+export { hexToRgba };

package/dist/lerp-rgba/index.d.ts

@@ -0,0 +1,2 @@
+export { lerpRgba } from './lerp-rgba';
+export { hexToRgba } from './hex-to-rgba';

package/dist/lerp-rgba/lerp-rgba.d.ts

@@ -0,0 +1,13 @@
+import { LerpRgba } from '../domain';
+/**
+ * Interpolate between two RGBA colors in Oklab space.
+ *
+ * The RGB channels are converted to Oklab, lerped perceptually uniformly,
+ * and converted back. The alpha channel is lerped linearly.
+ *
+ * @param from - Starting RGBA tuple [R, G, B, A], each 0–1.
+ * @param to - Ending RGBA tuple [R, G, B, A], each 0–1.
+ * @param progress - Interpolation factor (0 = from, 1 = to).
+ * @returns A new RGBA tuple [R, G, B, A], each 0–1.
+ */
+export declare const lerpRgba: LerpRgba;

package/dist/{color/lerp-oklab.js → lerp-rgba/lerp-rgba.js}

@@ -1,4 +1,4 @@
-//#region src/color/lerp-oklab.ts
+//#region src/lerp-rgba/lerp-rgba.ts
 /**
 * Pre-computed constants for Oklab conversion.
 *
@@ -121,7 +121,7 @@ var clamp = (value) => {
 * @param progress - Interpolation factor (0 = from, 1 = to).
 * @returns A new RGBA tuple [R, G, B, A], each 0–1.
 */
-var lerpOklab = (from, to, progress) => {
+var lerpRgba = (from, to, progress) => {
 	const clampedProgress = clamp(progress);
 	const [lFrom, aFrom, bFrom] = rgbToOklab(from[0], from[1], from[2]);
 	const [lTo, aTo, bTo] = rgbToOklab(to[0], to[1], to[2]);
@@ -133,50 +133,5 @@ var lerpOklab = (from, to, progress) => {
 		clamp(from[3] + (to[3] - from[3]) * clampedProgress)
 	];
 };
-/**
-* Parse a hex color string into an RGBA tuple.
-*
-* Accepts formats:
-*   - `#RGB`
-*   - `#RGBA`
-*   - `#RRGGBB`
-*   - `#RRGGBBAA`
-*
-* @param hex - Hex color string with optional leading `#`.
-* @returns An RGBA tuple [R, G, B, A], each 0–1.
-*/
-var hexToRgba = (hex) => {
-	const cleaned = hex.startsWith("#") ? hex.slice(1) : hex;
-	if (!/^[0-9a-fA-F]+$/.test(cleaned)) return [
-		0,
-		0,
-		0,
-		1
-	];
-	if (cleaned.length === 3) return [
-		parseInt(cleaned[0] + cleaned[0], 16) / 255,
-		parseInt(cleaned[1] + cleaned[1], 16) / 255,
-		parseInt(cleaned[2] + cleaned[2], 16) / 255,
-		1
-	];
-	if (cleaned.length === 4) return [
-		parseInt(cleaned[0] + cleaned[0], 16) / 255,
-		parseInt(cleaned[1] + cleaned[1], 16) / 255,
-		parseInt(cleaned[2] + cleaned[2], 16) / 255,
-		parseInt(cleaned[3] + cleaned[3], 16) / 255
-	];
-	if (cleaned.length >= 6) return [
-		parseInt(cleaned.slice(0, 2), 16) / 255,
-		parseInt(cleaned.slice(2, 4), 16) / 255,
-		parseInt(cleaned.slice(4, 6), 16) / 255,
-		cleaned.length >= 8 ? parseInt(cleaned.slice(6, 8), 16) / 255 : 1
-	];
-	return [
-		0,
-		0,
-		0,
-		1
-	];
-};
 //#endregion
-export { hexToRgba, lerpOklab };
+export { lerpRgba };

package/dist/smooth-clamp/{smooth-clamp.js → create-smooth-clamp.js}

@@ -1,4 +1,4 @@
-//#region src/smooth-clamp/smooth-clamp.ts
+//#region src/smooth-clamp/create-smooth-clamp.ts
 /**
 * Creates a smooth clamp function that maps input toward a threshold
 * without ever exceeding it. Uses `x / (1 + |x|)` for a natural-feeling

package/dist/smooth-clamp/index.d.ts

@@ -0,0 +1 @@
+export { createSmoothClamp } from './create-smooth-clamp';

package/dist/smooth-damp/create-smooth-damp.d.ts

@@ -1,10 +1,16 @@
-import { Interpolation, DynamicValue } from '../domain';
-export type SmoothDampOptions = {
-    to: () => number;
-    smoothTimeMs: DynamicValue;
-    maxSpeed?: DynamicValue;
-    precision?: number;
-    onUpdate?: (value: number, velocity: number) => void;
-    onEnded?: () => void;
-};
-export declare const createSmoothDamp: (options: SmoothDampOptions) => Interpolation;
+import { Interpolation, SmoothDampOptions } from '../domain';
+/**
+ * Creates a smooth damped interpolation that progressively moves a value
+ * toward a target with velocity that decreases as it approaches, producing
+ * a natural deceleration effect.
+ *
+ * Unlike a simple lerp, smooth damp respects an optional max speed and
+ * maintains velocity continuity, making it suitable for camera-relative
+ * movement, UI animations, and game object tracking.
+ *
+ * The target is re-evaluated every frame, allowing it to change dynamically.
+ *
+ * @param options - Configuration options for the smooth damp interpolation.
+ * @returns An {@link Interpolation} instance for controlling the smooth damp.
+ */
+export declare const createSmoothDamp: ({ to, smoothTimeMs: rawSmoothTimeMs, maxSpeed: rawMaxSpeed, precision, onUpdate, onEnded, ticker, }: SmoothDampOptions) => Interpolation;