@flighthq/easing 0.3.0-next.906.07cea63 → 0.3.0

package/dist/contract.d.ts

@@ -1,10 +1,12 @@
 export * from './createEasingSamples';
 export * from './easeBack';
+export * from './enableEasingGuards';
 export * from './easeBounce';
 export * from './easeCircular';
 export * from './easeCombinators';
 export * from './easeCubic';
 export * from './easeCubicBezier';
+export * from './easeDampedSine';
 export * from './easeElastic';
 export * from './easeExponential';
 export * from './easeLinear';

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC"}

package/dist/contract.js

@@ -1,10 +1,12 @@
 export * from './createEasingSamples';
 export * from './easeBack';
+export * from './enableEasingGuards';
 export * from './easeBounce';
 export * from './easeCircular';
 export * from './easeCombinators';
 export * from './easeCubic';
 export * from './easeCubicBezier';
+export * from './easeDampedSine';
 export * from './easeElastic';
 export * from './easeExponential';
 export * from './easeLinear';

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC"}

package/dist/easeDampedSine.d.ts

@@ -0,0 +1,34 @@
+import type { EasingFunction } from '@flighthq/types/contract';
+/**
+ * The parameterized form of `easeInElastic`: a decaying sine that winds up before departing, with the
+ * overshoot and wavelength stated rather than fixed.
+ */
+export declare function easeInDampedSine(amplitude: number, period: number): EasingFunction;
+/**
+ * The parameterized form of `easeInOutElastic`: a decaying sine that winds up, crosses, and settles,
+ * with the overshoot and wavelength stated rather than fixed.
+ */
+export declare function easeInOutDampedSine(amplitude: number, period: number): EasingFunction;
+/**
+ * The parameterized form of `easeOutElastic`: a decaying sine that overshoots the target and settles
+ * back onto it.
+ *
+ * `easeInElastic` / `easeOutElastic` / `easeInOutElastic` are this same published curve with the two
+ * parameters fixed. They stay the right choice when those constants suit; this family exists for a
+ * caller that states its own — an importer whose source file names an amplitude and a period, where
+ * substituting the fixed curve would be confidently wrong rather than approximately right.
+ *
+ * **Both degenerate cases are Flight's own choices, not anyone else's**, and both are stated here
+ * because they are the only places this can differ from another implementation of the same curve:
+ *
+ * - **An amplitude below 1 is raised to 1.** The phase term is `asin(1 / amplitude)`, which has no real
+ *   solution below unit amplitude, so the published curve is simply not defined there. Rather than
+ *   invent a shape for it we take the smallest curve the form does define, which also keeps the
+ *   endpoints exact. An elastic with less than unit overshoot is a contradiction in terms.
+ * - **A non-positive period falls back to 0.4.** It divides the wave, so zero has no meaning. 0.4 is the
+ *   constant our own `easeOutElastic` already uses, so a caller who states nothing gets the curve this
+ *   package's preset would have given — the least surprising answer available, and one that keeps the
+ *   two families consistent with each other.
+ */
+export declare function easeOutDampedSine(amplitude: number, period: number): EasingFunction;
+//# sourceMappingURL=easeDampedSine.d.ts.map

package/dist/easeDampedSine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"easeDampedSine.d.ts","sourceRoot":"","sources":["../src/easeDampedSine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CASlF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAYrF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAQnF"}

package/dist/easeDampedSine.js

@@ -0,0 +1,81 @@
+/**
+ * The parameterized form of `easeInElastic`: a decaying sine that winds up before departing, with the
+ * overshoot and wavelength stated rather than fixed.
+ */
+export function easeInDampedSine(amplitude, period) {
+    const wavelength = toDampedSineWavelength(period);
+    const overshoot = toDampedSineOvershoot(amplitude);
+    const phase = toDampedSinePhase(overshoot, wavelength);
+    return (t) => {
+        if (t === 0 || t === 1)
+            return t;
+        const time = t - 1;
+        return -(overshoot * Math.pow(2, 10 * time) * Math.sin(((time - phase) * TAU) / wavelength));
+    };
+}
+/**
+ * The parameterized form of `easeInOutElastic`: a decaying sine that winds up, crosses, and settles,
+ * with the overshoot and wavelength stated rather than fixed.
+ */
+export function easeInOutDampedSine(amplitude, period) {
+    const wavelength = toDampedSineWavelength(period);
+    const overshoot = toDampedSineOvershoot(amplitude);
+    const phase = toDampedSinePhase(overshoot, wavelength);
+    return (t) => {
+        if (t === 0 || t === 1)
+            return t;
+        const time = t * 2 - 1;
+        if (time < 0) {
+            return -0.5 * overshoot * Math.pow(2, 10 * time) * Math.sin(((time - phase) * TAU) / wavelength);
+        }
+        return 0.5 * overshoot * Math.pow(2, -10 * time) * Math.sin(((time - phase) * TAU) / wavelength) + 1;
+    };
+}
+/**
+ * The parameterized form of `easeOutElastic`: a decaying sine that overshoots the target and settles
+ * back onto it.
+ *
+ * `easeInElastic` / `easeOutElastic` / `easeInOutElastic` are this same published curve with the two
+ * parameters fixed. They stay the right choice when those constants suit; this family exists for a
+ * caller that states its own — an importer whose source file names an amplitude and a period, where
+ * substituting the fixed curve would be confidently wrong rather than approximately right.
+ *
+ * **Both degenerate cases are Flight's own choices, not anyone else's**, and both are stated here
+ * because they are the only places this can differ from another implementation of the same curve:
+ *
+ * - **An amplitude below 1 is raised to 1.** The phase term is `asin(1 / amplitude)`, which has no real
+ *   solution below unit amplitude, so the published curve is simply not defined there. Rather than
+ *   invent a shape for it we take the smallest curve the form does define, which also keeps the
+ *   endpoints exact. An elastic with less than unit overshoot is a contradiction in terms.
+ * - **A non-positive period falls back to 0.4.** It divides the wave, so zero has no meaning. 0.4 is the
+ *   constant our own `easeOutElastic` already uses, so a caller who states nothing gets the curve this
+ *   package's preset would have given — the least surprising answer available, and one that keeps the
+ *   two families consistent with each other.
+ */
+export function easeOutDampedSine(amplitude, period) {
+    const wavelength = toDampedSineWavelength(period);
+    const overshoot = toDampedSineOvershoot(amplitude);
+    const phase = toDampedSinePhase(overshoot, wavelength);
+    return (t) => {
+        if (t === 0 || t === 1)
+            return t;
+        return overshoot * Math.pow(2, -10 * t) * Math.sin(((t - phase) * TAU) / wavelength) + 1;
+    };
+}
+// Where the decaying sine crosses its endpoint, which is what makes t=0 land exactly on 0.
+function toDampedSinePhase(overshoot, wavelength) {
+    return (wavelength / TAU) * Math.asin(1 / overshoot);
+}
+// Below unit overshoot the phase term has no real solution, so the curve is undefined rather than
+// merely small. Clamping is Flight's choice: the smallest defined curve beats an invented one.
+function toDampedSineOvershoot(amplitude) {
+    return amplitude < 1 ? 1 : amplitude;
+}
+// A period divides the wave, so a non-positive one is meaningless. Flight's choice is the constant its
+// own fixed elastic already uses, so the two families agree with each other.
+function toDampedSineWavelength(period) {
+    return period > 0 ? period : DEFAULT_DAMPED_SINE_PERIOD;
+}
+const TAU = 2 * Math.PI;
+const DEFAULT_DAMPED_SINE_PERIOD = 0.4;
+//# sourceMappingURL=easeDampedSine.js.map

package/dist/easeDampedSine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"easeDampedSine.js","sourceRoot":"","sources":["../src/easeDampedSine.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,MAAc;IAChE,MAAM,UAAU,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;IACnD,MAAM,KAAK,GAAG,iBAAiB,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACvD,OAAO,CAAC,CAAC,EAAE,EAAE;QACX,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACjC,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACnB,OAAO,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAC/F,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB,EAAE,MAAc;IACnE,MAAM,UAAU,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;IACnD,MAAM,KAAK,GAAG,iBAAiB,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACvD,OAAO,CAAC,CAAC,EAAE,EAAE;QACX,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACjC,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YACb,OAAO,CAAC,GAAG,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC;QACnG,CAAC;QACD,OAAO,GAAG,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IACvG,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB,EAAE,MAAc;IACjE,MAAM,UAAU,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;IACnD,MAAM,KAAK,GAAG,iBAAiB,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACvD,OAAO,CAAC,CAAC,EAAE,EAAE;QACX,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACjC,OAAO,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC3F,CAAC,CAAC;AACJ,CAAC;AAED,2FAA2F;AAC3F,SAAS,iBAAiB,CAAC,SAAiB,EAAE,UAAkB;IAC9D,OAAO,CAAC,UAAU,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AACvD,CAAC;AAED,kGAAkG;AAClG,+FAA+F;AAC/F,SAAS,qBAAqB,CAAC,SAAiB;IAC9C,OAAO,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACvC,CAAC;AAED,uGAAuG;AACvG,6EAA6E;AAC7E,SAAS,sBAAsB,CAAC,MAAc;IAC5C,OAAO,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,0BAA0B,CAAC;AAC1D,CAAC;AAED,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;AACxB,MAAM,0BAA0B,GAAG,GAAG,CAAC"}

package/dist/easeSteps.d.ts

@@ -1,3 +1,4 @@
-import type { EasingFunction, StepPosition } from '@flighthq/types/contract';
+import type { EasingFunction, EasingStepsGuard, StepPosition } from '@flighthq/types/contract';
 export declare function easeSteps(count: number, position?: StepPosition): EasingFunction;
+export declare function setEasingStepsGuard(guard: EasingStepsGuard | null): void;
 //# sourceMappingURL=easeSteps.d.ts.map

package/dist/easeSteps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"easeSteps.d.ts","sourceRoot":"","sources":["../src/easeSteps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAc7E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,YAAwB,GAAG,cAAc,CAc3F"}
+{"version":3,"file":"easeSteps.d.ts","sourceRoot":"","sources":["../src/easeSteps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAe/F,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,YAAwB,GAAG,cAAc,CAe3F;AAMD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAExE"}

package/dist/easeSteps.js

@@ -6,11 +6,14 @@
 //   jumpBoth  - jump at both edges; count+1 levels from 0 to 1 inclusive.
 // Follows the CSS Easing Level 1 step algorithm.
 //
-// Sharp edge: easeSteps(1, 'jumpNone') has jumps = count - 1 = 0, so the returned
-// function divides by zero and yields NaN. This mirrors the CSS spec, which forbids
-// steps(1, jump-none) for the same reason. Callers must pass count >= 2 with
-// 'jumpNone'; every other position is well-defined for count >= 1.
+// Sharp edge: easeSteps(1, 'jumpNone') has jumps = count - 1 = 0, so the returned function divides by
+// zero and yields NaN for every input. This mirrors the CSS spec, which forbids steps(1, jump-none) for
+// the same reason; `count >= 2` is required with 'jumpNone', while every other position is well-defined
+// for count >= 1. The failure is SILENT — NaN propagates into whatever the easing drives — so the
+// degenerate call routes through the guard seam below, which enableEasingGuards turns into a warning.
 export function easeSteps(count, position = 'jumpEnd') {
+    if (position === 'jumpNone' && count < 2)
+        _stepsGuard?.(count, position);
     const jumps = position === 'jumpNone' ? count - 1 : position === 'jumpBoth' ? count + 1 : count;
     const startOffset = position === 'jumpStart' || position === 'jumpBoth' ? 1 : 0;
     return (t) => {
@@ -24,4 +27,12 @@ export function easeSteps(count, position = 'jumpEnd') {
         return step / jumps;
     };
 }
+// The diagnostics seam for the degenerate `easeSteps` call, not the caller-facing entry point — use
+// `enableEasingGuards`, which installs the @flighthq/log reporter through here. Null uninstalls it, and a
+// null slot is what production sees: the check above is one comparison and the message text plus the
+// @flighthq/log dependency live only in the separately-imported guard module.
+export function setEasingStepsGuard(guard) {
+    _stepsGuard = guard;
+}
+let _stepsGuard = null;
 //# sourceMappingURL=easeSteps.js.map

package/dist/easeSteps.js.map

@@ -1 +1 @@
-{"version":3,"file":"easeSteps.js","sourceRoot":"","sources":["../src/easeSteps.ts"],"names":[],"mappings":"AAEA,4EAA4E;AAC5E,gEAAgE;AAChE,yEAAyE;AACzE,+EAA+E;AAC/E,uFAAuF;AACvF,0EAA0E;AAC1E,iDAAiD;AACjD,EAAE;AACF,kFAAkF;AAClF,oFAAoF;AACpF,6EAA6E;AAC7E,mEAAmE;AACnE,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,WAAyB,SAAS;IACzE,MAAM,KAAK,GAAG,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAChG,MAAM,WAAW,GAAG,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEhF,OAAO,CAAC,CAAC,EAAE,EAAE;QACX,IAAI,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,WAAW,CAAC;QAC/C,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YACvB,IAAI,GAAG,CAAC,CAAC;QACX,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;YAC3B,IAAI,GAAG,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,GAAG,KAAK,CAAC;IACtB,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"easeSteps.js","sourceRoot":"","sources":["../src/easeSteps.ts"],"names":[],"mappings":"AAEA,4EAA4E;AAC5E,gEAAgE;AAChE,yEAAyE;AACzE,+EAA+E;AAC/E,uFAAuF;AACvF,0EAA0E;AAC1E,iDAAiD;AACjD,EAAE;AACF,sGAAsG;AACtG,wGAAwG;AACxG,wGAAwG;AACxG,kGAAkG;AAClG,sGAAsG;AACtG,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,WAAyB,SAAS;IACzE,IAAI,QAAQ,KAAK,UAAU,IAAI,KAAK,GAAG,CAAC;QAAE,WAAW,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACzE,MAAM,KAAK,GAAG,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAChG,MAAM,WAAW,GAAG,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEhF,OAAO,CAAC,CAAC,EAAE,EAAE;QACX,IAAI,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,WAAW,CAAC;QAC/C,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YACvB,IAAI,GAAG,CAAC,CAAC;QACX,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;YAC3B,IAAI,GAAG,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,GAAG,KAAK,CAAC;IACtB,CAAC,CAAC;AACJ,CAAC;AAED,oGAAoG;AACpG,0GAA0G;AAC1G,qGAAqG;AACrG,8EAA8E;AAC9E,MAAM,UAAU,mBAAmB,CAAC,KAA8B;IAChE,WAAW,GAAG,KAAK,CAAC;AACtB,CAAC;AAED,IAAI,WAAW,GAA4B,IAAI,CAAC"}

package/dist/enableEasingGuards.d.ts

@@ -0,0 +1,3 @@
+export declare function disableEasingGuards(): void;
+export declare function enableEasingGuards(): void;
+//# sourceMappingURL=enableEasingGuards.d.ts.map

package/dist/enableEasingGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableEasingGuards.d.ts","sourceRoot":"","sources":["../src/enableEasingGuards.ts"],"names":[],"mappings":"AAOA,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAWD,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/enableEasingGuards.js

@@ -0,0 +1,25 @@
+import { logOnce } from '@flighthq/log/contract';
+import { LogLevel } from '@flighthq/types/contract';
+import { setEasingStepsGuard } from './easeSteps';
+// Uninstalls the guard installed by enableEasingGuards.
+export function disableEasingGuards() {
+    setEasingStepsGuard(null);
+}
+// Installs the caller-facing easing guard (opt-in, dev-only). This package has one silent footgun:
+// `easeSteps(count, 'jumpNone')` with `count < 2` leaves zero jumps, so the returned function divides by
+// zero and hands back NaN for every input. Nothing throws and nothing logs — the NaN just propagates into
+// whatever the easing drives, which is why a comment telling callers "pass count >= 2" was not enough.
+//
+// @flighthq/easing is a CORE package, and core may otherwise depend only on types/core. This module is the
+// sanctioned exception: it is separately importable and shakeable, so a build that never imports it never
+// pulls @flighthq/log, and the layer rule's actual concern — feature weight in core's always-loaded graph —
+// does not arise. `packages:check` enforces that the import appears in guard modules only. Idempotent.
+export function enableEasingGuards() {
+    setEasingStepsGuard(warnOnDegenerateSteps);
+}
+function warnOnDegenerateSteps(count, position) {
+    logOnce('easing:degenerate-steps', LogLevel.Warn, {
+        message: `easeSteps(${count}, '${position}'): '${position}' has count - 1 jumps, so it needs count >= 2. With ${count} there are no jumps, the easing divides by zero, and every input returns NaN. Pass count >= 2, or use a position that jumps at an edge ('jumpEnd', 'jumpStart', 'jumpBoth') — those are defined for count >= 1.`,
+    }, 'easing');
+}
+//# sourceMappingURL=enableEasingGuards.js.map

package/dist/enableEasingGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableEasingGuards.js","sourceRoot":"","sources":["../src/enableEasingGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,wDAAwD;AACxD,MAAM,UAAU,mBAAmB;IACjC,mBAAmB,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,mGAAmG;AACnG,yGAAyG;AACzG,0GAA0G;AAC1G,uGAAuG;AACvG,EAAE;AACF,2GAA2G;AAC3G,0GAA0G;AAC1G,4GAA4G;AAC5G,uGAAuG;AACvG,MAAM,UAAU,kBAAkB;IAChC,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAa,EAAE,QAAsB;IAClE,OAAO,CACL,yBAAyB,EACzB,QAAQ,CAAC,IAAI,EACb;QACE,OAAO,EAAE,aAAa,KAAK,MAAM,QAAQ,QAAQ,QAAQ,uDAAuD,KAAK,iNAAiN;KACvU,EACD,QAAQ,CACT,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { createEasingSamples, easeClamp, easeClampOutput, easeCubicBezier, easeInBack, easeInBounce, easeInCircular, easeInCubic, easeInElastic, easeInExponential, easeInOutBack, easeInOutBounce, easeInOutCircular, easeInOutCubic, easeInOutElastic, easeInOutExponential, easeInOutPower, easeInOutQuadratic, easeInOutQuartic, easeInOutQuintic, easeInOutSine, easeInPower, easeInQuadratic, easeInQuartic, easeInQuintic, easeInSine, easeInvert, easeLinear, easeMirror, easeOutBack, easeOutBounce, easeOutCircular, easeOutCubic, easeOutElastic, easeOutExponential, easeOutPower, easeOutQuadratic, easeOutQuartic, easeOutQuintic, easeOutSine, easePiecewise, easeReverse, easeScaleOutput, easeSmootherstep, easeSmoothstep, easeSmoothstepRange, easeSteps, getEasingDerivative, } from './contract';
+export { createEasingSamples, easeClamp, easeClampOutput, easeCubicBezier, easeInBack, easeInBounce, easeInCircular, easeInCubic, easeInDampedSine, easeInElastic, easeInExponential, easeInOutBack, easeInOutBounce, easeInOutCircular, easeInOutCubic, easeInOutDampedSine, easeInOutElastic, easeInOutExponential, easeInOutPower, easeInOutQuadratic, easeInOutQuartic, easeInOutQuintic, easeInOutSine, easeInPower, easeInQuadratic, easeInQuartic, easeInQuintic, easeInSine, easeInvert, easeLinear, easeMirror, easeOutBack, easeOutBounce, easeOutCircular, easeOutCubic, easeOutDampedSine, easeOutElastic, easeOutExponential, easeOutPower, easeOutQuadratic, easeOutQuartic, easeOutQuintic, easeOutSine, easePiecewise, easeReverse, easeScaleOutput, easeSmootherstep, easeSmoothstep, easeSmoothstepRange, easeSteps, getEasingDerivative, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,eAAe,EACf,eAAe,EACf,UAAU,EACV,YAAY,EACZ,cAAc,EACd,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,eAAe,EACf,aAAa,EACb,aAAa,EACb,UAAU,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,aAAa,EACb,eAAe,EACf,YAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,EACb,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,SAAS,EACT,mBAAmB,GACpB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,eAAe,EACf,eAAe,EACf,UAAU,EACV,YAAY,EACZ,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,eAAe,EACf,aAAa,EACb,aAAa,EACb,UAAU,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,aAAa,EACb,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,EACb,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,SAAS,EACT,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { createEasingSamples, easeClamp, easeClampOutput, easeCubicBezier, easeInBack, easeInBounce, easeInCircular, easeInCubic, easeInElastic, easeInExponential, easeInOutBack, easeInOutBounce, easeInOutCircular, easeInOutCubic, easeInOutElastic, easeInOutExponential, easeInOutPower, easeInOutQuadratic, easeInOutQuartic, easeInOutQuintic, easeInOutSine, easeInPower, easeInQuadratic, easeInQuartic, easeInQuintic, easeInSine, easeInvert, easeLinear, easeMirror, easeOutBack, easeOutBounce, easeOutCircular, easeOutCubic, easeOutElastic, easeOutExponential, easeOutPower, easeOutQuadratic, easeOutQuartic, easeOutQuintic, easeOutSine, easePiecewise, easeReverse, easeScaleOutput, easeSmootherstep, easeSmoothstep, easeSmoothstepRange, easeSteps, getEasingDerivative, } from './contract';
+export { createEasingSamples, easeClamp, easeClampOutput, easeCubicBezier, easeInBack, easeInBounce, easeInCircular, easeInCubic, easeInDampedSine, easeInElastic, easeInExponential, easeInOutBack, easeInOutBounce, easeInOutCircular, easeInOutCubic, easeInOutDampedSine, easeInOutElastic, easeInOutExponential, easeInOutPower, easeInOutQuadratic, easeInOutQuartic, easeInOutQuintic, easeInOutSine, easeInPower, easeInQuadratic, easeInQuartic, easeInQuintic, easeInSine, easeInvert, easeLinear, easeMirror, easeOutBack, easeOutBounce, easeOutCircular, easeOutCubic, easeOutDampedSine, easeOutElastic, easeOutExponential, easeOutPower, easeOutQuadratic, easeOutQuartic, easeOutQuintic, easeOutSine, easePiecewise, easeReverse, easeScaleOutput, easeSmootherstep, easeSmoothstep, easeSmoothstepRange, easeSteps, getEasingDerivative, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,eAAe,EACf,eAAe,EACf,UAAU,EACV,YAAY,EACZ,cAAc,EACd,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,eAAe,EACf,aAAa,EACb,aAAa,EACb,UAAU,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,aAAa,EACb,eAAe,EACf,YAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,EACb,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,SAAS,EACT,mBAAmB,GACpB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,eAAe,EACf,eAAe,EACf,UAAU,EACV,YAAY,EACZ,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,eAAe,EACf,aAAa,EACb,aAAa,EACb,UAAU,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,aAAa,EACb,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,EACb,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,SAAS,EACT,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@flighthq/easing",
-  "version": "0.3.0-next.906.07cea63",
+  "version": "0.3.0",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,7 +38,8 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/types": "0.3.0-next.906.07cea63"
+    "@flighthq/log": "0.3.0",
+    "@flighthq/types": "0.3.0"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/easeDampedSine.test.ts

@@ -0,0 +1,100 @@
+import { easeInDampedSine, easeInOutDampedSine, easeOutDampedSine } from './easeDampedSine';
+import { easeInElastic, easeInOutElastic, easeOutElastic } from './easeElastic';
+
+describe('easeInDampedSine', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    const ease = easeInDampedSine(1, 0.4);
+
+    expect(ease(0)).toBe(0);
+    expect(ease(1)).toBe(1);
+  });
+
+  it('winds up below 0 before departing', () => {
+    expect(easeInDampedSine(1, 0.4)(0.8)).toBeLessThan(0);
+  });
+
+  it('matches the fixed easeInElastic at the constants that one hardcodes', () => {
+    // The fixed curve is this one at amplitude 1, period 0.4 — the check that the general form is
+    // right rather than merely plausible.
+    const ease = easeInDampedSine(1, 0.4);
+    for (const t of [0.1, 0.25, 0.4, 0.6, 0.75, 0.9]) {
+      expect(ease(t)).toBeCloseTo(easeInElastic(t), 10);
+    }
+  });
+});
+
+describe('easeInOutDampedSine', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    const ease = easeInOutDampedSine(1, 0.45);
+
+    expect(ease(0)).toBe(0);
+    expect(ease(1)).toBe(1);
+  });
+
+  it('matches the fixed easeInOutElastic at the constants that one hardcodes', () => {
+    const ease = easeInOutDampedSine(1, 0.45);
+    for (const t of [0.1, 0.3, 0.5, 0.7, 0.9]) {
+      expect(ease(t)).toBeCloseTo(easeInOutElastic(t), 10);
+    }
+  });
+});
+
+describe('easeOutDampedSine', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    const ease = easeOutDampedSine(1, 0.4);
+
+    expect(ease(0)).toBe(0);
+    expect(ease(1)).toBe(1);
+  });
+
+  it('overshoots past 1 near the start', () => {
+    expect(easeOutDampedSine(1, 0.4)(0.6)).toBeGreaterThan(1);
+  });
+
+  it('matches the fixed easeOutElastic at the constants that one hardcodes', () => {
+    const ease = easeOutDampedSine(1, 0.4);
+    for (const t of [0.1, 0.25, 0.4, 0.6, 0.75, 0.9]) {
+      expect(ease(t)).toBeCloseTo(easeOutElastic(t), 10);
+    }
+  });
+
+  it('separates the curves that the fixed form collapses together', () => {
+    // The whole reason this family exists: a source stating its own period gets a materially
+    // different curve, so substituting the fixed one is wrong rather than approximate. Measured as
+    // the widest gap across the curve — any single sample can land where two curves happen to cross.
+    const wide = easeOutDampedSine(1, 0.9);
+    const narrow = easeOutDampedSine(1, 0.2);
+    const widest = Math.max(
+      ...Array.from({ length: 99 }, (_, index) => Math.abs(wide((index + 1) / 100) - narrow((index + 1) / 100))),
+    );
+
+    expect(widest).toBeGreaterThan(0.5);
+  });
+
+  it('overshoots further as amplitude grows', () => {
+    const peak = (amplitude: number): number =>
+      Math.max(...Array.from({ length: 99 }, (_, index) => easeOutDampedSine(amplitude, 0.4)((index + 1) / 100)));
+
+    expect(peak(3)).toBeGreaterThan(peak(1));
+  });
+
+  it('raises an amplitude below 1 to the smallest defined curve', () => {
+    // The phase term is asin(1 / amplitude), which has no real solution below unit amplitude, so the
+    // curve is undefined there rather than merely small. Flight clamps rather than inventing a shape.
+    const clamped = easeOutDampedSine(0.5, 0.4);
+    const unit = easeOutDampedSine(1, 0.4);
+
+    for (const t of [0.2, 0.5, 0.8]) expect(clamped(t)).toBeCloseTo(unit(t), 10);
+    expect(Number.isFinite(clamped(0.3))).toBe(true);
+  });
+
+  it('falls back to this package own fixed period when the period is not positive', () => {
+    // A period divides the wave, so zero has no meaning. Flight's choice is 0.4 — the constant
+    // easeOutElastic already uses — so the parameterized and fixed families agree with each other.
+    for (const period of [0, -1]) {
+      const ease = easeOutDampedSine(1, period);
+      expect(Number.isFinite(ease(0.5))).toBe(true);
+      expect(ease(0.5)).toBeCloseTo(easeOutDampedSine(1, 0.4)(0.5), 10);
+    }
+  });
+});

package/src/easeSteps.test.ts

@@ -1,4 +1,6 @@
-import { easeSteps } from './easeSteps';
+import type { StepPosition } from '@flighthq/types/contract';
+
+import { easeSteps, setEasingStepsGuard } from './easeSteps';
 
 describe('easeSteps', () => {
   it('jumpEnd holds at 0 first and reaches 1 only at t=1', () => {
@@ -63,3 +65,33 @@ describe('easeSteps', () => {
     }
   });
 });
+
+describe('setEasingStepsGuard', () => {
+  it('reports the degenerate jumpNone call that silently returns NaN', () => {
+    const seen: [number, StepPosition][] = [];
+    setEasingStepsGuard((count, position) => seen.push([count, position]));
+    try {
+      // The failure being reported: one step with no edge jump leaves zero jumps to divide by.
+      expect(Number.isNaN(easeSteps(1, 'jumpNone')(0.5))).toBe(true);
+    } finally {
+      setEasingStepsGuard(null);
+    }
+    expect(seen).toEqual([[1, 'jumpNone']]);
+  });
+
+  it('stays silent for well-defined calls, and once uninstalled', () => {
+    const seen: number[] = [];
+    setEasingStepsGuard((count) => seen.push(count));
+    try {
+      easeSteps(2, 'jumpNone')(0.5); // count >= 2 is the documented minimum for jumpNone
+      easeSteps(1, 'jumpEnd')(0.5); // edge-jumping positions are defined for count >= 1
+      easeSteps(1, 'jumpBoth')(0.5);
+    } finally {
+      setEasingStepsGuard(null);
+    }
+    expect(seen).toEqual([]);
+    // Uninstalled: the degenerate call still returns NaN, but nothing is reported.
+    easeSteps(1, 'jumpNone')(0.5);
+    expect(seen).toEqual([]);
+  });
+});

package/src/enableEasingGuards.test.ts

@@ -0,0 +1,70 @@
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/contract';
+import type { LogEntry } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { easeSteps } from './easeSteps';
+import { disableEasingGuards, enableEasingGuards } from './enableEasingGuards';
+
+function captureLog(run: () => void): readonly LogEntry[] {
+  const sink = createMemoryLogSink(8);
+  addLogSink(sink.sink);
+  try {
+    run();
+    return getMemoryLogSinkEntries(sink);
+  } finally {
+    removeLogSink(sink.sink);
+  }
+}
+
+function messageOf(entry: Readonly<LogEntry>): string {
+  const data = entry.data;
+  return typeof data === 'string' ? data : String(data.message);
+}
+
+describe('disableEasingGuards', () => {
+  it('uninstalls the guard, returning the degenerate call to silence', () => {
+    const entries = captureLog(() => {
+      enableEasingGuards();
+      disableEasingGuards();
+      // Still NaN — disabling removes the reporting, not the sharp edge.
+      expect(Number.isNaN(easeSteps(1, 'jumpNone')(0.5))).toBe(true);
+    });
+    expect(entries.length).toBe(0);
+  });
+});
+
+describe('enableEasingGuards', () => {
+  it('WARNS on the degenerate jumpNone step count that silently returns NaN', () => {
+    const entries = captureLog(() => {
+      enableEasingGuards();
+      try {
+        expect(Number.isNaN(easeSteps(1, 'jumpNone')(0.5))).toBe(true);
+      } finally {
+        disableEasingGuards();
+      }
+    });
+    expect(entries.length).toBe(1);
+    expect(messageOf(entries[0])).toContain('count >= 2');
+  });
+
+  it('stays SILENT for well-defined calls, and without the guard at all', () => {
+    const guarded = captureLog(() => {
+      enableEasingGuards();
+      try {
+        easeSteps(2, 'jumpNone')(0.5);
+        easeSteps(1, 'jumpEnd')(0.5);
+        easeSteps(1, 'jumpStart')(0.5);
+        easeSteps(1, 'jumpBoth')(0.5);
+      } finally {
+        disableEasingGuards();
+      }
+    });
+    expect(guarded.length).toBe(0);
+
+    // Production default: still NaN, but nothing is logged — the guard is opt-in.
+    const unguarded = captureLog(() => {
+      expect(Number.isNaN(easeSteps(1, 'jumpNone')(0.5))).toBe(true);
+    });
+    expect(unguarded.length).toBe(0);
+  });
+});