@penner/responsive-easing 0.0.4 → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,991 @@
+import { EasingFn } from '@penner/easing';
+import { EasingKit } from '@penner/easing';
+import { NormalizedProgress } from '@penner/smart-primitive';
+import { NormalizedTime } from '@penner/smart-primitive';
+import { NormalizedVelocity } from '@penner/smart-primitive';
+import { PercentProgress } from '@penner/smart-primitive';
+import { SwimConfig } from '@penner/easing';
+import { VelocityFn } from '@penner/easing';
+
+/** Discriminated union of all easing definitions */
+export declare type AnyEasingDef = PowerDef | BackDef | PowerBackDef | BezierDef | ExpoDef | SpringDef | BounceDef | SwimDef;
+
+declare interface BackDef extends EasingDefBase<'back'>, BackRemParams {
+}
+
+export declare class BackRem extends EasingRem<BackRemParams> {
+    static readonly OVERSHOOT_KNOB: PercentKnobSpec;
+    readonly kind: "back";
+    readonly metadata: EasingRemMetadata;
+    readonly knobSpecs: readonly KnobSpec[];
+    readonly easeInBoundary: VelocityBoundary;
+    /** Cached strength parameter derived from overshoot */
+    private readonly strength;
+    constructor(params: BackRemParams);
+    easeIn: (u: NormalizedTime) => NormalizedProgress;
+    easeInVelocity: (u: NormalizedTime) => NormalizedVelocity;
+    easeOutVelocity: (u: NormalizedTime) => NormalizedVelocity;
+    with(overrides: Partial<BackRemParams>): BackRem;
+    static create(init?: Partial<BackRemParams>): BackRem;
+}
+
+declare interface BackRemParams {
+    /** Overshoot depth, normalized 0-1 (e.g., 0.1 = 10% overshoot) */
+    readonly overshoot: number;
+}
+
+declare interface BaseKnobSpec<T extends KnobPrimitive = number> {
+    readonly key: string;
+    readonly label: string;
+    readonly default: T;
+    /** Custom display value formatter for UI */
+    readonly displayFormatter?: (value: T) => string;
+    /** Whether this knob should be shown as primary (thicker slider, emphasized styling) */
+    readonly isPrimary?: boolean;
+}
+
+declare interface BezierDef extends EasingDefBase<'bezier'>, BezierRemParams {
+}
+
+export declare class BezierRem extends EasingRem<BezierRemParams> {
+    static readonly X1_KNOB: NumberKnobSpec;
+    static readonly Y1_KNOB: NumberKnobSpec;
+    static readonly X2_KNOB: NumberKnobSpec;
+    static readonly Y2_KNOB: NumberKnobSpec;
+    readonly kind: "bezier";
+    readonly metadata: EasingRemMetadata;
+    readonly knobSpecs: readonly KnobSpec[];
+    /** Both ends depend on control points — always nonzero */
+    readonly easeInBoundary: VelocityBoundary;
+    private readonly bezier;
+    easeIn: (u: NormalizedTime) => NormalizedProgress;
+    easeOut: (u: NormalizedTime) => NormalizedProgress;
+    constructor(params: BezierRemParams);
+    with(overrides: Partial<BezierRemParams>): BezierRem;
+    static create(init?: Partial<BezierRemParams>): BezierRem;
+}
+
+declare interface BezierRemParams {
+    readonly x1: NormalizedTime;
+    readonly y1: NormalizedProgress;
+    readonly x2: NormalizedTime;
+    readonly y2: NormalizedProgress;
+}
+
+/** Boolean toggle knob. */
+declare interface BooleanKnobSpec extends BaseKnobSpec<boolean> {
+    readonly type: 'boolean';
+}
+
+declare interface BounceDef extends EasingDefBase<'bounce'>, BounceRemParams {
+}
+
+export declare class BounceRem extends EasingRem<BounceRemParams> {
+    static readonly BOUNCES_KNOB: NumberKnobSpec;
+    static readonly DECAY_KNOB: PercentKnobSpec;
+    readonly kind: "bounce";
+    readonly metadata: EasingRemMetadata;
+    readonly knobSpecs: readonly KnobSpec[];
+    readonly easeInBoundary: VelocityBoundary;
+    /** Cached standalone easeOut function built with minimal head defaults */
+    private readonly builtP;
+    private readonly builtV;
+    constructor(params: BounceRemParams);
+    easeIn: (u: NormalizedTime) => NormalizedProgress;
+    easeInVelocity: (u: NormalizedTime) => number;
+    easeOut: (u: NormalizedTime) => NormalizedProgress;
+    easeOutVelocity: (u: NormalizedTime) => number;
+    /** Access the underlying TailStrategy for full fuse composition */
+    static get tailStrategy(): typeof BounceTail;
+    with(overrides: Partial<BounceRemParams>): BounceRem;
+    static create(init?: Partial<BounceRemParams>): BounceRem;
+}
+
+declare interface BounceRemParams {
+    /** Number of bounce impacts */
+    readonly bounces: number;
+    /** Total decay from first to last bounce, normalized 0-1 */
+    readonly decay: number;
+}
+
+/**
+ * Hard-surface bounce pulse tail strategy
+ *
+ * Creates a bouncing effect where the tail follows parabolic trajectories,
+ * simulating gravity-based bouncing off a hard surface. The amplitude
+ * decreases by a total percentage over all bounces.
+ *
+ * This is a pulse tail with net-zero displacement - it oscillates around
+ * the target position and settles back to it.
+ *
+ * Physics model:
+ * - Each bounce is a parabola (projectile motion)
+ * - Constant downward acceleration throughout
+ * - Velocity reversal and reduction at each impact
+ * - Total decay applied across all N bounces (not per bounce)
+ */
+declare const BounceTail: TailStrategy;
+
+/**
+ * Calculate head p2 from tail p1 to maintain symmetric smooth node
+ *
+ * Given the tail's first control point (p1), this calculates where the head's
+ * second control point (p2) should be placed to maintain a symmetric smooth Bezier node.
+ *
+ * Uses simple coordinate symmetry in normalized [0,1] space:
+ * - head_p2 = (1 - tail_p1.x, 1 - tail_p1.y)
+ * - Control points are collinear (C¹ continuity)
+ * - Slider values mirror each other (predictable UI)
+ * - Creates "smooth" or "symmetrical" node like in design tools
+ *
+ * @param tailP1 - Tail's first control point in normalized coordinates [0,1]
+ * @param _joinTime - Join point time (not used in calculation, but kept for API consistency)
+ * @returns Calculated head p2 position
+ *
+ * @example
+ * ```ts
+ * // User drags tail p1 to (0.3, 0.7)
+ * const result = calculateHeadP2FromTailP1(
+ *   { x: 0.3, y: 0.7 },
+ *   0.6
+ * );
+ * // Result: head p2 = (0.7, 0.3) - simple inversion
+ * // Update UI: set head p2 sliders to result.point.x, result.point.y
+ * ```
+ */
+export declare function calculateHeadP2FromTailP1(tailP1: Point2D, _joinTime: number): ConstraintResult;
+
+/**
+ * Calculate tail p1 from head p2 to maintain symmetric smooth node
+ *
+ * Given the head's second control point (p2), this calculates where the tail's
+ * first control point (p1) should be placed to maintain a symmetric smooth Bezier node.
+ *
+ * Uses simple coordinate symmetry in normalized [0,1] space:
+ * - tail_p1 = (1 - head_p2.x, 1 - head_p2.y)
+ * - Control points are collinear (C¹ continuity)
+ * - Slider values mirror each other (predictable UI)
+ * - Creates "smooth" or "symmetrical" node like in design tools
+ *
+ * @param headP2 - Head's second control point in normalized coordinates [0,1]
+ * @param _joinTime - Join point time (not used in calculation, but kept for API consistency)
+ * @returns Calculated tail p1 position
+ *
+ * @example
+ * ```ts
+ * // User drags head p2 to (0.8, 0.9)
+ * const result = calculateTailP1FromHeadP2(
+ *   { x: 0.8, y: 0.9 },
+ *   0.6
+ * );
+ * // Result: tail p1 = (0.2, 0.1) - simple inversion
+ * // Update UI: set tail p1 sliders to result.point.x, result.point.y
+ * ```
+ */
+export declare function calculateTailP1FromHeadP2(headP2: Point2D, _joinTime: number): ConstraintResult;
+
+/**
+ * Clamp Bezier y1 value based on head type and feature flags
+ *
+ * When combining power-back head with Bezier tail, y1 must be > 0 to prevent
+ * negative start slope (which breaks power-back head behavior). However, y1 can
+ * exceed 1.0 to allow flexibility in curve design.
+ *
+ * UI components should use this function to constrain slider/control point ranges.
+ *
+ * @param y1 - The desired y1 value
+ * @param headType - The head type being used
+ * @param allowGeneralizedBackHead - Whether to allow y1 <= 0 (advanced feature)
+ * @returns The clamped y1 value
+ *
+ * @example
+ * ```ts
+ * // In UI code:
+ * const clampedY1 = clampBezierY1ForHead(userY1, 'power-back', false);
+ * // Use clampedY1 for slider min or control point bounds
+ * ```
+ */
+export declare function clampBezierY1ForHead(y1: number, headType: EasingKind, allowGeneralizedBackHead?: boolean): number;
+
+/**
+ * Clamp Bezier y2 value based on tail type and feature flags
+ *
+ * When combining Bezier head with power-back/back/power tails, y2 must be < 1.0
+ * to prevent negative end slope (which breaks tail behavior). However, y2 can be
+ * negative to allow flexibility in curve design.
+ *
+ * Since power-back is the generalized form containing both power and back as
+ * special cases, all three tail types use the same clamping logic.
+ *
+ * UI components should use this function to constrain slider/control point ranges.
+ *
+ * @param y2 - The desired y2 value
+ * @param tailType - The tail type being used
+ * @param allowGeneralizedBackTail - Whether to allow y2 >= 1.0 (advanced feature)
+ * @returns The clamped y2 value
+ *
+ * @example
+ * ```ts
+ * // In UI code:
+ * const clampedY2 = clampBezierY2ForTail(userY2, 'power-back', false);
+ * // Use clampedY2 for slider max or control point bounds
+ * ```
+ */
+export declare function clampBezierY2ForTail(y2: number, tailType: EasingKind, allowGeneralizedBackTail?: boolean): number;
+
+/**
+ * Result from constraint calculation
+ */
+declare interface ConstraintResult {
+    /** Whether the calculation was successful */
+    isValid: boolean;
+    /** The calculated control point */
+    point?: Point2D;
+    /** Optional warning message */
+    warning?: string;
+}
+
+/**
+ * Create a back (overshoot) tail strategy - ease out
+ */
+declare function createBackTail(overshoot?: number): RegularTailStrategy;
+
+/**
+ * Create a Bezier tail strategy with custom control points
+ *
+ * Uses cubic Bezier curve with locked endpoints.
+ * In the tail phase, the curve goes from (joinTime, joinHeight) to (1, 1).
+ * The control points (x1, y1) and (x2, y2) are specified in normalized coordinates (0-1)
+ * relative to the tail segment.
+ *
+ * IMPORTANT: For C¹ continuity, the slope from p0 to p1 must match the slope
+ * from the head's p2 to p3. This constraint is enforced at the fuse level,
+ * not in this factory function.
+ *
+ * @param x1 - First control point X coordinate (0 to 1, normalized time)
+ * @param y1 - First control point Y coordinate (0 to 1, normalized progress)
+ * @param x2 - Second control point X coordinate (0 to 1, normalized time)
+ * @param y2 - Second control point Y coordinate (0 to 1, normalized progress)
+ */
+declare function createBezierTail(x1?: NormalizedTime, y1?: NormalizedProgress, x2?: NormalizedTime, y2?: NormalizedProgress): RegularTailStrategy;
+
+/**
+ * Create an exponential ease-out tail strategy with a configurable decay parameter.
+ *
+ * Uses the canonical normalized expo ease-out from @penner/easing.
+ * The analytical derivative is computed for C¹ continuity at the fuse join point.
+ *
+ * @param decay - Fraction of initial velocity lost over the segment, in [0, 1].
+ *   - 0 = linear (no decay)
+ *   - 0.95 = typical smooth deceleration (default)
+ *   - approaching 1 = very steep initial curve
+ */
+declare function createExpoTail(decay?: number): RegularTailStrategy;
+
+/**
+ * Create a power-back ease-out tail strategy
+ *
+ * Combines power curve (exponent) with back overshoot for ease-out.
+ * Uses the unified power-back mathematics to maintain C¹ continuity with head phases.
+ *
+ * For ease-out, we reverse the ease-in formula:
+ *   easeOutPowerBack(u) = 1 - easeInPowerBack(1 - u)
+ *
+ * @param exponent - Power exponent n (must be > 1 for overshoot, default 2)
+ * @param overshoot - Overshoot depth O (0-1, default 0.1)
+ */
+declare function createPowerBackTail(exponent?: number, overshoot?: number): RegularTailStrategy;
+
+/**
+ * Create a power ease-out tail strategy with a configurable exponent
+ */
+declare function createPowerTail(exponent?: number): RegularTailStrategy;
+
+/** Base for all easing definitions — discriminated on `kind` */
+declare interface EasingDefBase<K extends EasingKind> {
+    readonly kind: K;
+}
+
+export { EasingFn }
+
+/**
+ * All supported easing kinds — the canonical union.
+ * HeadType, RegularTailType, PulseTailType are subsets of this.
+ */
+export declare type EasingKind = 'power' | 'back' | 'power-back' | 'bezier' | 'expo' | 'spring' | 'bounce' | 'swim';
+
+/** Map from kind to its params type */
+declare interface EasingParamsMap {
+    power: Partial<PowerRemParams>;
+    back: Partial<BackRemParams>;
+    'power-back': Partial<PowerBackRemParams>;
+    bezier: Partial<BezierRemParams>;
+    expo: Partial<ExpoRemParams>;
+    spring: Partial<SpringRemParams>;
+    bounce: Partial<BounceRemParams>;
+    swim: Partial<SwimRemParams>;
+}
+
+declare abstract class EasingRem<P extends object = Record<string, unknown>> {
+    /** Unique identifier for this REM type (e.g., 'power', 'back') */
+    abstract readonly kind: string;
+    /** Intrinsic metadata: variants, modes */
+    abstract readonly metadata: EasingRemMetadata;
+    /** Knob specs for dynamic UI generation (practical slider ranges, not math constraints) */
+    abstract readonly knobSpecs: readonly KnobSpec[];
+    /** Velocity boundary for ease-in variant (can depend on current params) */
+    abstract readonly easeInBoundary: VelocityBoundary;
+    /** Immutable parameter object */
+    readonly params: Readonly<P>;
+    constructor(params: P);
+    /** Ease-in function */
+    abstract easeIn(u: NormalizedTime): NormalizedProgress;
+    /** Ease-in velocity — default: lazy numerical derivative of easeIn.
+     *  Subclasses may override with an analytical derivative. */
+    easeInVelocity: VelocityFn;
+    /** Ease-out function — default: reverse of easeIn */
+    easeOut: (u: NormalizedTime) => NormalizedProgress;
+    /** Ease-out velocity — default: lazy numerical derivative of easeOut.
+     *  Automatically correct even when easeOut is overridden. */
+    easeOutVelocity: VelocityFn;
+    /** Velocity boundary for ease-out variant — default: reversed easeIn */
+    get easeOutBoundary(): VelocityBoundary;
+    /** Returns a new REM with patched params (immutable update) */
+    abstract with(overrides: Partial<P>): EasingRem<P>;
+}
+
+/**
+ * Intrinsic REM metadata — objective facts, not derived heuristics.
+ * Composition rules (e.g., "which REMs can be heads?") are inferred
+ * from these facts by the Fuse logic, not baked into the metadata.
+ */
+declare interface EasingRemMetadata {
+    /** Which easing variants this REM can produce */
+    readonly variants: {
+        readonly easeIn: boolean;
+        readonly easeOut: boolean;
+    };
+    /** Which movement modes this REM supports
+     *  (e.g., Spring supports both: natively pulse, transition via bridge) */
+    readonly modes: {
+        readonly transition: boolean;
+        readonly pulse: boolean;
+    };
+}
+
+/**
+ * Evaluate the unified power-Back ease-in at point u.
+ *
+ * Unified formula for all n > 1:
+ *   f_n(u; s) = (s+1)u^n − su^(n-1)
+ *
+ * Factored form (computational):
+ *   f_n(u; s) = u^(n-1)[(s+1)u - s]
+ *
+ * This saves one Math.pow() call and reveals the geometric structure:
+ *   - Zero crossing at u = s/(s+1)
+ *   - Amplitude scaling by (s+1)
+ *   - Power envelope u^(n-1)
+ *
+ * For s = 0 or n ≤ 1: falls back to pure power u^n
+ *
+ * @param u - Normalized time parameter [0, 1]
+ * @param exponent - Power exponent n
+ * @param strength - Strength parameter (from solvePowerBackStrength)
+ * @returns Position at time u
+ */
+export declare function evalPowerBackIn(u: number, exponent: number, strength: number): number;
+
+declare interface ExpoDef extends EasingDefBase<'expo'>, ExpoRemParams {
+}
+
+export declare class ExpoRem extends EasingRem<ExpoRemParams> {
+    static readonly DECAY_KNOB: PercentKnobSpec;
+    readonly kind: "expo";
+    readonly metadata: EasingRemMetadata;
+    readonly knobSpecs: readonly KnobSpec[];
+    readonly easeInBoundary: VelocityBoundary;
+    /** Cached ease-out function and derivative constants */
+    private readonly easeOutFn;
+    private readonly negK;
+    private readonly scale;
+    private readonly d;
+    constructor(params: ExpoRemParams);
+    /** easeIn is the reverse of easeOut (not natively supported, metadata.variants.easeIn = false) */
+    easeIn: (u: NormalizedTime) => NormalizedProgress;
+    easeInVelocity: (u: NormalizedTime) => number;
+    easeOut: (u: NormalizedTime) => NormalizedProgress;
+    easeOutVelocity: (u: NormalizedTime) => number;
+    private easeOutVelocityImpl;
+    with(overrides: Partial<ExpoRemParams>): ExpoRem;
+    static create(init?: Partial<ExpoRemParams>): ExpoRem;
+}
+
+declare interface ExpoRemParams {
+    /** Decay fraction (0-1). 0 = linear, 0.95 = typical, approaching 1 = very steep. */
+    readonly decay: number;
+}
+
+/**
+ * Find the exponent that places the local minimum at a target u-coordinate.
+ *
+ * This is the inverse of getLocalMinimumPosition: given a fixed overshoot
+ * and a desired position for the local minimum, find the exponent n that
+ * achieves that position.
+ *
+ * The relationship between u*, n, and x is:
+ *   u* = (n-1)x/n
+ *
+ * where x = s/(s+1) depends on both n and overshoot O.
+ *
+ * Since x depends on n (through the overshoot equation), we use bisection
+ * to solve for n numerically.
+ *
+ * @param overshoot - Fixed overshoot percentage (0-1), e.g., 0.3 for 30%
+ * @param targetUMin - Desired u-coordinate of local minimum (0-1)
+ * @param minExponent - Minimum allowed exponent (default 1.01)
+ * @param maxExponent - Maximum allowed exponent (default 10)
+ * @returns Exponent n that places the minimum at targetUMin, or null if impossible
+ */
+export declare function findExponentForMinimumPosition(overshoot: number, targetUMin: number, minExponent?: number, maxExponent?: number): number | null;
+
+/**
+ * Create a fused easing from a serializable FuseConfig.
+ *
+ * Resolves each EasingDef to an EasingRem, then delegates to composeFuse
+ * for composition. Returns an EasingKit with position, velocity, and metadata.
+ *
+ * @example
+ * const result = fuse({
+ *   head: { kind: 'power', exponent: 2 },
+ *   tail: { kind: 'back', overshoot: 0.1 },
+ *   joinTime: 0.5,
+ * });
+ * const y = result.easingFn(0.5);
+ */
+export declare function fuse(config: FuseConfig): EasingKit;
+
+/**
+ * Serializable fuse configuration — generic over head and tail types.
+ *
+ * @example
+ * const config: FuseConfig = {
+ *   head: { kind: 'power-back', exponent: 3, overshoot: 0.15 },
+ *   tail: { kind: 'spring', bounces: 4, decay: 0.95 },
+ *   joinTime: 0.6,
+ * };
+ * const result = fuse(config);
+ */
+export declare interface FuseConfig<H extends AnyEasingDef = AnyEasingDef, T extends AnyEasingDef = AnyEasingDef> {
+    /** @default 'transition' — most common; pulse is the special case */
+    movement?: 'transition' | 'pulse';
+    head: H;
+    tail: T;
+    joinTime?: NormalizedTime;
+    /** When true, the tail is created by reversing the head easing (easeIn → easeOut),
+     *  so both phases use the same curve shape. The tail EasingDef is ignored.
+     *  This produces symmetric "inOut" style curves from a single head definition.
+     *  Only applies to regular tails (not spring/bounce pulse tails). */
+    mirror?: boolean;
+    /** Enable bridge for pulse tails. @default true */
+    useBridge?: boolean;
+    /** Bridge tuning parameters */
+    bridgeTuning?: {
+        headWeight?: number;
+        freqWeight?: number;
+        freqExponent?: number;
+        baseMultiplier?: number;
+    };
+    /** Allow generalized back tail when joinHeight is clamped to 1.0 */
+    allowGeneralizedBackTail?: boolean;
+    /**
+     * Maximum velocity at the join point. When the head's natural ending
+     * velocity exceeds this, a constant-velocity cruise phase is inserted
+     * between the head and tail. The head ends early (when it hits maxSpeed),
+     * then cruises at maxSpeed until the join point.
+     *
+     * Only applies to transition tails (power, back, power-back).
+     * When undefined or Infinity, no cruise — current behavior.
+     */
+    maxSpeed?: number;
+}
+
+/**
+ * Create an EasingRem instance from a kind string and params.
+ *
+ * @param kind - The easing type identifier
+ * @param params - Optional parameters (uses defaults if omitted)
+ * @returns A new EasingRem instance
+ *
+ * @example
+ * const rem = getEasingRem('power', { exponent: 3 });
+ * const rem2 = getEasingRem('back'); // uses defaults
+ */
+export declare function getEasingRem<K extends EasingKind>(kind: K, params?: EasingParamsMap[K]): EasingRem;
+
+/**
+ * Compute the u-coordinate of the local minimum (critical point) for power-back ease-in.
+ *
+ * The critical point occurs where f'(u) = 0:
+ *   u* = (n-1)s / [n(s+1)] = (n-1)x/n
+ *
+ * where x = s/(s+1) is the zero-crossing position.
+ *
+ * This is the position of the "bulge" in the overshoot curve - the deepest
+ * point of anticipation before the curve rises toward 1.
+ *
+ * @param exponent - Power exponent n (must be > 1)
+ * @param overshoot - Overshoot percentage (0-1), e.g., 0.3 for 30%
+ * @returns u-coordinate of local minimum, or 0 if no overshoot exists
+ */
+export declare function getLocalMinimumPosition(exponent: number, overshoot: number): number;
+
+/**
+ * Compute the canonical grab point on a pure power ease-in curve u^n.
+ *
+ * This is the point of maximum perpendicular distance from the diagonal (p = u),
+ * found by maximizing u^n − u:
+ *
+ *   d/du [u^n − u] = n·u^(n-1) − 1 = 0
+ *   → u_peak = n^(−1/(n−1))
+ *   → p_peak = u_peak^n = n^(−n/(n−1))
+ *
+ * This serves as the natural "visual center" of the curve's bend — the intrinsic
+ * analog of the extremum for the zero-overshoot case. Used to position the
+ * affordance dot when overshoot/anticipation is 0.
+ *
+ * For the ease-out mirror: u_tail = 1 − u_peak, p_tail = 1 − p_peak.
+ *
+ * @param exponent - Power exponent n (> 1 for a meaningful result)
+ * @returns { u, p } coordinates of the canonical point on the pure power curve
+     */
+ export declare function getPowerCurveCanonicalPoint(exponent: number): {
+     u: number;
+     p: number;
+ };
+
+ /**
+  * Get a tail strategy by type
+  */
+ export declare function getTailStrategy(type: TailType_2, config?: {
+     overshoot?: number;
+     exponent?: number;
+     x1?: number;
+     y1?: number;
+     x2?: number;
+     y2?: number;
+     decay?: number;
+ }): RegularTailStrategy;
+
+ /**
+  * Predefined head easing types (subset of EasingKind)
+  */
+ export declare type HeadType = Extract<EasingKind, 'power' | 'back' | 'bezier' | 'spring' | 'power-back' | 'swim'>;
+
+ declare type KnobPrimitive = boolean | number | string;
+
+ /** Union of all supported knob flavours. */
+ export declare type KnobSpec = NumberKnobSpec | PercentKnobSpec | BooleanKnobSpec | StringKnobSpec;
+
+ /** Numeric slider knob (min / max / step valid only here). */
+ export declare interface NumberKnobSpec extends BaseKnobSpec<number> {
+     readonly type: 'number';
+     readonly min?: number;
+     readonly max?: number;
+     readonly step?: number;
+ }
+
+ /** Percent slider knob — domain value 0-1, UI displays 0-100. */
+ export declare interface PercentKnobSpec extends BaseKnobSpec<number> {
+     readonly type: 'percent';
+     readonly min?: number;
+     readonly max?: number;
+     readonly step?: number;
+ }
+
+ /**
+  * Bezier-to-Bezier Join Constraint Utilities
+  *
+  * When fusing two Bezier curves with the custom join strategy:
+  * - joinHeight = joinTime (diagonal constraint)
+  * - Symmetric smooth node: control points use simple coordinate inversion in local [0,1] space
+  * - tail_p1 = (1 - head_p2.x, 1 - head_p2.y) and vice versa
+  * - C¹ continuity via collinear control points (shared slope)
+  * - Predictable UI: slider values mirror each other
+  *
+  * These utilities help UI implementations maintain the constraint bidirectionally:
+  * - Moving head p2 automatically calculates tail p1
+  * - Moving tail p1 automatically calculates head p2
+  */
+ /**
+  * Control point in 2D space
+  */
+ declare interface Point2D {
+     x: number;
+     y: number;
+ }
+
+ declare interface PowerBackDef extends EasingDefBase<'power-back'>, PowerBackRemParams {
+ }
+
+ export declare class PowerBackRem extends EasingRem<PowerBackRemParams> {
+     static readonly EXPONENT_KNOB: NumberKnobSpec;
+     static readonly OVERSHOOT_KNOB: PercentKnobSpec;
+     readonly kind: "power-back";
+     readonly metadata: EasingRemMetadata;
+     readonly knobSpecs: readonly KnobSpec[];
+     /** Cached strength parameter derived from overshoot + exponent */
+     private readonly strength;
+     constructor(params: PowerBackRemParams);
+     get easeInBoundary(): VelocityBoundary;
+     easeIn: (u: NormalizedTime) => NormalizedProgress;
+     easeInVelocity: (u: NormalizedTime) => number;
+     easeOutVelocity: (u: NormalizedTime) => number;
+     with(overrides: Partial<PowerBackRemParams>): PowerBackRem;
+     static create(init?: Partial<PowerBackRemParams>): PowerBackRem;
+ }
+
+ declare interface PowerBackRemParams {
+     /** Power exponent (>= 0.1) */
+     readonly exponent: number;
+     /** Overshoot depth, normalized 0-1 */
+     readonly overshoot: number;
+ }
+
+ /** Per-kind definitions with type-safe params (all normalized 0-1) */
+ declare interface PowerDef extends EasingDefBase<'power'>, PowerRemParams {
+ }
+
+ export declare class PowerRem extends EasingRem<PowerRemParams> {
+     static readonly EXPONENT_KNOB: NumberKnobSpec;
+     readonly kind: "power";
+     readonly metadata: EasingRemMetadata;
+     readonly knobSpecs: readonly KnobSpec[];
+     constructor(params: PowerRemParams);
+     get easeInBoundary(): VelocityBoundary;
+     easeIn: (u: NormalizedTime) => NormalizedProgress;
+     easeInVelocity: (u: NormalizedTime) => number;
+     easeOutVelocity: (u: NormalizedTime) => number;
+     with(overrides: Partial<PowerRemParams>): PowerRem;
+     static create(init?: Partial<PowerRemParams>): PowerRem;
+ }
+
+ declare interface PowerRemParams {
+     readonly exponent: number;
+ }
+
+ /**
+  * Pulse tail types with net-zero displacement (used by createBounceFuse and createSpringFuse)
+  * These tails oscillate around the target position and settle back to it.
+  */
+ declare type PulseTailType = Extract<EasingKind, 'spring' | 'bounce'>;
+
+ /**
+  * Tail strategy interface for regular (non-pulse) tails
+  *
+  * Regular tails have net displacement - they move from one position to another.
+  * In contrast, pulse tails oscillate around a target and settle back to it (net-zero displacement).
+  */
+ declare interface RegularTailStrategy {
+     /**
+      * Unique identifier for this tail strategy
+      */
+     id: string;
+     /**
+      * Human-readable label
+      */
+     label: string;
+     /**
+      * The easing function (should be an "out" variant)
+      */
+     easingFn: EasingFn;
+     /**
+      * Derivative of the easing function
+      */
+     velocityFn: VelocityFn;
+     /**
+      * Optional configuration object
+      */
+     config?: Record<string, unknown>;
+ }
+
+ /**
+  * Regular tail types with net displacement (used by createSimpleFuse)
+  * These tails move from one position to another position.
+  */
+ declare type RegularTailType = Extract<EasingKind, 'power' | 'back' | 'power-back' | 'bezier' | 'expo'>;
+
+ /**
+  * Inverse mapping: find parameter s given overshoot and exponent
+  *
+  * Uses bisection on x = s/(s+1) to solve the inverse problem:
+  * given target overshoot O and exponent n, find s such that f_n(u; s)
+  * has minimum value −O.
+  *
+  * Strategy:
+  *   - Re-parameterize s with x = s/(s+1), so s = x/(1−x), x ∈ [0,1)
+  *   - For fixed n, overshoot O(x; n) is strictly increasing in x
+  *   - Use bisection to solve O(x; n) = target
+  *
+  * @param overshoot - Target overshoot depth O (0 to ~1) as NormalizedProgress
+  * @param exponent - Power exponent n (must be > 1 for Back behavior)
+  * @returns The strength parameter (≥ 0) for the PowerBack anticipation term
+  */
+ export declare function solvePowerBackStrength(overshoot: NormalizedProgress, exponent: number): number;
+
+ declare interface SpringDef extends EasingDefBase<'spring'>, SpringRemParams {
+ }
+
+ export declare class SpringRem extends EasingRem<SpringRemParams> {
+     static readonly BOUNCES_KNOB: NumberKnobSpec;
+     static readonly DECAY_KNOB: PercentKnobSpec;
+     readonly kind: "spring";
+     readonly metadata: EasingRemMetadata;
+     readonly knobSpecs: readonly KnobSpec[];
+     readonly easeInBoundary: VelocityBoundary;
+     /** Cached standalone easeOut function built with minimal head defaults */
+     private readonly builtP;
+     private readonly builtV;
+     constructor(params: SpringRemParams);
+     /** easeIn is the reverse of easeOut (not natively supported) */
+     easeIn: (u: NormalizedTime) => NormalizedProgress;
+     easeInVelocity: (u: NormalizedTime) => number;
+     easeOut: (u: NormalizedTime) => NormalizedProgress;
+     easeOutVelocity: (u: NormalizedTime) => number;
+     /** Access the underlying TailStrategy for full fuse composition */
+     static get tailStrategy(): typeof SpringZeroLockedTail;
+     with(overrides: Partial<SpringRemParams>): SpringRem;
+     static create(init?: Partial<SpringRemParams>): SpringRem;
+ }
+
+ declare interface SpringRemParams {
+     /** Number of half-cycles in the oscillation */
+     readonly bounces: number;
+     /** Total decay from first to last peak, normalized 0-1 (e.g., 0.95 = last peak is 5% of first) */
+     readonly decay: number;
+ }
+
+ /**
+  * Spring phase-locked pulse tail strategy
+  *
+  * Creates a spring-like oscillation where the tail follows a damped sinusoid
+  * that's phase-locked at the START to ensure C¹ continuity with the head.
+  * The amplitude decreases by a total percentage over all half-cycles.
+  *
+  * This is a pulse tail with net-zero displacement - it oscillates around
+  * the target position and settles back to it.
+  *
+  * Physics model:
+  * - Damped harmonic oscillator: A*e^(-kt)*sin(Bt)
+  * - START-LOCKED: Sine wave always begins at zero-crossing (sin(0) = 0)
+  * - Phase-locked so that N half-cycles fit exactly in the remaining time
+  * - Total decay applied across all N half-cycles (not per half-cycle)
+  *
+  * The start-locking ensures that the oscillation begins at exactly zero,
+  * maintaining smooth C¹ continuity at the join point even with fractional
+  * bounce counts. For integer bounces, the endpoint also lands on a zero-crossing.
+  * For fractional bounces, the endpoint may be slightly off zero but is visually
+  * acceptable during parameter adjustment (and snaps to integer on release).
+  */
+ declare const SpringZeroLockedTail: TailStrategy;
+
+ /** Text/select knob. */
+ declare interface StringKnobSpec extends BaseKnobSpec {
+     readonly type: 'string';
+     readonly options?: readonly string[];
+ }
+
+ declare interface SwimDef extends EasingDefBase<'swim'>, SwimRemParams {
+ }
+
+ export declare class SwimRem extends EasingRem<SwimRemParams> {
+     static readonly STROKES_KNOB: NumberKnobSpec;
+     static readonly EFFORT_KNOB: PercentKnobSpec;
+     static readonly DRAG_KNOB: NumberKnobSpec;
+     readonly kind: "swim";
+     readonly metadata: EasingRemMetadata;
+     readonly knobSpecs: readonly KnobSpec[];
+     readonly easeInBoundary: VelocityBoundary;
+     constructor(params: SwimRemParams);
+     easeIn: (u: NormalizedTime) => NormalizedProgress;
+     with(overrides: Partial<SwimRemParams>): SwimRem;
+     static create(init?: Partial<SwimRemParams>): SwimRem;
+ }
+
+ /** Derived from SwimConfig — single source of truth for swim parameter names. */
+ declare type SwimRemParams = Readonly<Required<SwimConfig>>;
+
+ /**
+  * Parameters for building a tail strategy
+  */
+ declare interface TailBuildParams {
+     /**
+      * Join point in normalized time [0,1]
+      * This is the fraction of the timeline where head ends and tail begins
+      */
+     joinTime: NormalizedTime;
+     /**
+      * Number of bounces in the tail
+      */
+     bounces: number;
+     /**
+      * Decay percentage per oscillation (0-100)
+      * This represents the TOTAL decay from first to last oscillation.
+      * For example, decay=90 means the last oscillation is 10% of the first.
+      *
+      * For bounce: total decay from first bounce peak to last bounce peak
+      * For spring: total decay from first peak to last peak
+      *
+      * Special case for single oscillation (N=1):
+      * - decay=0 means full energy (no reduction)
+      * - decay=50 means the single oscillation is 50% smaller
+      * - decay=100 means no oscillation (settles immediately)
+      */
+     decayPct: PercentProgress /**
+     * Head easing function (defaults to easeInBack)
+     */;
+     L?: EasingFn;
+     /**
+      * Head velocity function (derivative of L, defaults to easeInBack derivative)
+      */
+     Ld?: VelocityFn;
+     /**
+      * Bridge mode parameters (optional, only for pulse tails)
+      * When provided, a constant-velocity bridge connects the head to the pulse
+      */
+     bridge?: {
+         /**
+          * Position where head ends (and bridge begins)
+          * This is less than 1, allowing the head to scale more naturally
+          */
+         joinHeight: NormalizedProgress;
+         /**
+          * Duration of the bridge phase in normalized time
+          * The bridge goes from time `a` to `a + duration`
+          */
+         duration: number;
+         /**
+          * Constant velocity of the bridge (matches head ending velocity and pulse starting velocity)
+          */
+         velocity: number;
+     };
+ }
+
+ /**
+  * Result from building a tail strategy
+  * Contains the easing function, velocity function, and metadata
+  */
+ declare interface TailBuildResult {
+     /**
+      * Easing function for the tail segment (normalized time [0,1] → normalized position)
+      */
+     p: EasingFn;
+     /**
+      * Velocity function for the tail segment (derivative of position)
+      */
+     v: VelocityFn;
+     /**
+      * Metadata about the tail configuration
+      */
+     meta: {
+         /** Restitution coefficient or amplitude decay ratio */
+         r: number;
+         /** Final amplitude as percentage of initial */
+         finalPct: number;
+         /** Decay rate constant (spring tail) */
+         k?: number;
+         /** Angular frequency (spring tail) */
+         B?: number;
+         /** C¹ scaling factor (spring tail) */
+         P?: number;
+         /** Guard message indicating any robustness fallbacks applied */
+         guard?: string;
+         /** Whether bridge mode was used */
+         useBridge?: boolean;
+         /** Additional metadata specific to the tail type */
+         [key: string]: unknown;
+     };
+ }
+
+ /**
+  * Map of all predefined regular tail strategy factories
+  *
+  * Regular tails have net displacement - they move from one position to another.
+  * These factories create tail strategies with easingFn/velocityFn for use by createSimpleFuse.
+  *
+  * For pulse tails with net-zero displacement (oscillate and settle), use:
+  * - HardBounceTail (bounce) - gravity-based bouncing physics
+  * - ElasticZeroLockedTail (spring) - spring-like oscillation
+  */
+ declare const tailStrategies: {
+     readonly back: typeof createBackTail;
+     readonly power: typeof createPowerTail;
+     readonly 'power-back': typeof createPowerBackTail;
+     readonly bezier: typeof createBezierTail;
+     readonly expo: typeof createExpoTail;
+ };
+
+ /**
+  * Tail strategy interface
+  * Implementations define how to build a specific type of tail (bounce, spring, etc.)
+  */
+ declare interface TailStrategy {
+     /**
+      * Unique identifier for this tail strategy
+      */
+     id: string;
+     /**
+      * Human-readable label
+      */
+     label: string;
+     /**
+      * Build the tail easing function from parameters
+      */
+     build: (params: TailBuildParams) => TailBuildResult;
+     /**
+      * Get the natural starting velocity for this tail type (optional, for pulse tails)
+      *
+      * This is used in bridge mode to calculate the appropriate joinHeight (join height)
+      * and bridge duration. The velocity is what the pulse would naturally start
+      * with given its oscillation and decay parameters.
+      *
+      * @param params - Parameters for calculating natural velocity (N cycles, decay %)
+      * @param headVelocityFn - The head's velocity function for adaptive bridge calculation
+      * @param tuning - Optional tuning parameters for bridge velocity calculation (defaults: all 1.0)
+      * @returns The natural starting velocity magnitude, or undefined if not applicable
+      */
+     getNaturalStartVelocity?: (params: {
+         bounces: number;
+         decayPct: number;
+     }, headVelocityFn: (u: number) => number, tuning?: {
+         headWeight?: number;
+         freqWeight?: number;
+         freqExponent?: number;
+         baseMultiplier?: number;
+     }) => number;
+ }
+
+ /**
+  * All predefined tail types
+  */
+ export declare type TailType = RegularTailType | PulseTailType;
+
+ /**
+  * Regular tail type union (tails with net displacement)
+  */
+ declare type TailType_2 = keyof typeof tailStrategies;
+
+ /** Velocity boundary metadata for an easing variant */
+ declare interface VelocityBoundary {
+     readonly start: VelocityConstraint;
+     readonly end: VelocityConstraint;
+ }
+
+ /**
+  * Velocity constraint at a boundary.
+  * Kept as a union (not boolean) for future extensibility —
+  * e.g., Bezier joins may need a 'tangent-coupled' constraint.
+  */
+ declare type VelocityConstraint = 'zero' | 'nonzero';
+
+ export { }