@flighthq/easing 0.3.0-next.906.07cea63 → 0.3.1-next.1041.35b950c

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":"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"}

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.1-next.1041.35b950c",
+  "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.1-next.1041.35b950c",
+    "@flighthq/types": "0.3.1-next.1041.35b950c"
   },
   "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/easingFamilies.test.ts

@@ -0,0 +1,276 @@
+import type { EasingFunction } from '@flighthq/types/contract';
+
+// Cross-family invariants: relationships BETWEEN the In/Out/InOut siblings, which is where this package's
+// real defects live. A per-curve value assertion is close to blind here — `easeInQuadratic(0.5) === 0.25`
+// also accepts curves that are not easeInQuadratic, and every easing function satisfies f(0)=0 and f(1)=1,
+// so endpoint assertions accept nearly everything. In ten families of near-identical arithmetic the likely
+// defect is a copy-paste between neighbours, and only a relationship between siblings can see it.
+//
+// This file is cross-family by construction, which is why it has no single source sibling: each assertion
+// is about a PAIR or the whole set. Per-curve behaviour stays in each family's own test file.
+import {
+  easeInBack,
+  easeInBounce,
+  easeInCircular,
+  easeInCubic,
+  easeInElastic,
+  easeInExponential,
+  easeInOutBack,
+  easeInOutBounce,
+  easeInOutCircular,
+  easeInOutCubic,
+  easeInOutElastic,
+  easeInOutExponential,
+  easeInOutQuadratic,
+  easeInOutQuartic,
+  easeInOutQuintic,
+  easeInOutSine,
+  easeInQuadratic,
+  easeInQuartic,
+  easeInQuintic,
+  easeInSine,
+  easeOutBack,
+  easeOutBounce,
+  easeOutCircular,
+  easeOutCubic,
+  easeOutElastic,
+  easeOutExponential,
+  easeOutQuadratic,
+  easeOutQuartic,
+  easeOutQuintic,
+  easeOutSine,
+} from './contract';
+
+interface Family {
+  easeIn: EasingFunction;
+  easeInOut: EasingFunction;
+  easeOut: EasingFunction;
+  // Whether easeInOut is the two halves of easeIn/easeOut scaled into place. FALSE for the two families
+  // whose canonical definition gives the InOut variant a DIFFERENT constant — Back scales its overshoot
+  // by 1.525 and Elastic widens its period from 0.4 to 0.45 — so forcing the relation here would be
+  // asserting a curve the family does not have.
+  halvesMatch: boolean;
+  // Whether easeIn rises without ever stepping back. False where the shape is the point: Back undershoots
+  // below 0, Elastic oscillates, Bounce bounces.
+  monotonic: boolean;
+  name: string;
+}
+
+const FAMILIES: readonly Family[] = [
+  {
+    easeIn: easeInBack,
+    easeInOut: easeInOutBack,
+    easeOut: easeOutBack,
+    halvesMatch: false,
+    monotonic: false,
+    name: 'Back',
+  },
+  {
+    easeIn: easeInBounce,
+    easeInOut: easeInOutBounce,
+    easeOut: easeOutBounce,
+    halvesMatch: true,
+    monotonic: false,
+    name: 'Bounce',
+  },
+  {
+    easeIn: easeInCircular,
+    easeInOut: easeInOutCircular,
+    easeOut: easeOutCircular,
+    halvesMatch: true,
+    monotonic: true,
+    name: 'Circular',
+  },
+  {
+    easeIn: easeInCubic,
+    easeInOut: easeInOutCubic,
+    easeOut: easeOutCubic,
+    halvesMatch: true,
+    monotonic: true,
+    name: 'Cubic',
+  },
+  {
+    easeIn: easeInElastic,
+    easeInOut: easeInOutElastic,
+    easeOut: easeOutElastic,
+    halvesMatch: false,
+    monotonic: false,
+    name: 'Elastic',
+  },
+  {
+    easeIn: easeInExponential,
+    easeInOut: easeInOutExponential,
+    easeOut: easeOutExponential,
+    halvesMatch: true,
+    monotonic: true,
+    name: 'Exponential',
+  },
+  {
+    easeIn: easeInQuadratic,
+    easeInOut: easeInOutQuadratic,
+    easeOut: easeOutQuadratic,
+    halvesMatch: true,
+    monotonic: true,
+    name: 'Quadratic',
+  },
+  {
+    easeIn: easeInQuartic,
+    easeInOut: easeInOutQuartic,
+    easeOut: easeOutQuartic,
+    halvesMatch: true,
+    monotonic: true,
+    name: 'Quartic',
+  },
+  {
+    easeIn: easeInQuintic,
+    easeInOut: easeInOutQuintic,
+    easeOut: easeOutQuintic,
+    halvesMatch: true,
+    monotonic: true,
+    name: 'Quintic',
+  },
+  {
+    easeIn: easeInSine,
+    easeInOut: easeInOutSine,
+    easeOut: easeOutSine,
+    halvesMatch: true,
+    monotonic: true,
+    name: 'Sine',
+  },
+];
+
+// 201 points rather than a handful: a copy-paste between neighbours can agree at the sample points a
+// hand-picked list would choose, and cannot agree across the whole unit interval.
+const SAMPLES: readonly number[] = Array.from({ length: 201 }, (_, index) => index / 200);
+
+// The measured worst reflection error across every family is 1.1e-15, so this bound is roughly three
+// orders of magnitude tighter than the smallest real difference a wrong constant could produce, and
+// still far above double-precision noise.
+const EPSILON = 1e-12;
+
+describe('easing family distinctness', () => {
+  // The direct test for the copy-paste defect, and the only one that can see it: two families whose
+  // bodies were pasted from each other agree everywhere, and every other assertion in this file passes
+  // for both. The measured closest pair is Quadratic against Sine at 5.6e-2, so this bound sits an order
+  // of magnitude below the nearest real neighbours and far above any rounding difference.
+  it.each(['easeIn', 'easeInOut', 'easeOut'] as const)('%s curves are pairwise distinct', (direction) => {
+    for (let a = 0; a < FAMILIES.length; a += 1) {
+      for (let b = a + 1; b < FAMILIES.length; b += 1) {
+        const first = FAMILIES[a][direction];
+        const second = FAMILIES[b][direction];
+        const separation = SAMPLES.reduce((worst, t) => Math.max(worst, Math.abs(first(t) - second(t))), 0);
+        expect({ pair: `${FAMILIES[a].name}/${FAMILIES[b].name}`, separated: separation > 0.005 }).toEqual({
+          pair: `${FAMILIES[a].name}/${FAMILIES[b].name}`,
+          separated: true,
+        });
+      }
+    }
+  });
+});
+
+describe('easing family endpoints', () => {
+  // EXACT, not approximate — except where the formula itself cannot be exact in binary floating point,
+  // and those two are named rather than folded into a loose tolerance for everyone. easeInSine(1) is
+  // 1 - cos(pi/2) and cos(pi/2) is 6.1e-17 rather than 0; easeInBack(1) is (s + 1) - s, which cancels to
+  // 0.9999999999999998 for s = 1.70158. Both are one ulp, both are properties of the arithmetic, and
+  // special-casing the code to force a rounder number would be making the curve fit the test.
+  const INEXACT_AT_ONE = new Set(['Back', 'Sine']);
+
+  // OBSERVED, and harmless: easeInBack(0) and easeInOutSine(0) return NEGATIVE zero, because both bodies
+  // end in a multiplication by zero with a negative factor. It is numerically equal to 0 and behaves
+  // identically everywhere an easing value is consumed; only Object.is separates them, which is what
+  // `toBe` uses. Normalising rather than loosening keeps the assertion EXACT for every other value.
+  it.each(FAMILIES)('$name: starts at exactly 0', ({ easeIn, easeInOut, easeOut }) => {
+    expect(normalizeZero(easeIn(0))).toBe(0);
+    expect(normalizeZero(easeInOut(0))).toBe(0);
+    expect(Math.abs(easeOut(0))).toBeLessThan(EPSILON);
+  });
+
+  it.each(FAMILIES)('$name: ends at 1, exactly where the arithmetic allows', ({ easeIn, easeInOut, easeOut }) => {
+    expect(easeOut(1)).toBe(1);
+    expect(easeInOut(1)).toBe(1);
+    if (INEXACT_AT_ONE.has(name(easeIn))) expect(easeIn(1)).toBeCloseTo(1, 15);
+    else expect(easeIn(1)).toBe(1);
+  });
+
+  function normalizeZero(value: number): number {
+    return value === 0 ? 0 : value;
+  }
+
+  function name(easeIn: EasingFunction): string {
+    return FAMILIES.find((family) => family.easeIn === easeIn)!.name;
+  }
+});
+
+describe('easing family halves', () => {
+  it.each(FAMILIES.filter((family) => family.halvesMatch))(
+    '$name: easeInOut is easeIn on the first half and easeOut on the second',
+    ({ easeIn, easeInOut, easeOut }) => {
+      for (const t of SAMPLES) {
+        const expected = t <= 0.5 ? easeIn(t * 2) / 2 : 0.5 + easeOut(t * 2 - 1) / 2;
+        expect(Math.abs(easeInOut(t) - expected)).toBeLessThan(EPSILON);
+      }
+    },
+  );
+
+  // The two exceptions are asserted as exceptions rather than skipped, so a later edit that "fixes" one
+  // of them into the scaled-halves shape fails here and has to be a deliberate change to the curve.
+  it.each(FAMILIES.filter((family) => !family.halvesMatch))(
+    '$name: easeInOut deliberately differs from the scaled halves, because its canonical constant differs',
+    ({ easeIn, easeInOut }) => {
+      const worst = SAMPLES.filter((t) => t <= 0.5).reduce(
+        (accumulated, t) => Math.max(accumulated, Math.abs(easeInOut(t) - easeIn(t * 2) / 2)),
+        0,
+      );
+      expect(worst).toBeGreaterThan(0.01);
+    },
+  );
+
+  // Continuity asserted as the gap SHRINKING with the interval, not as the gap being small. A small-gap
+  // test is the wrong instrument here: Circular has a vertical tangent at the midpoint by construction —
+  // it is a quarter circle — so its slope there measures ~1000 against 0.58 at t=0.25, and any fixed
+  // bound either fails a correct curve or is loose enough to accept a real step. A genuine discontinuity
+  // has a gap that stops shrinking; a steep one has a gap that keeps going.
+  it.each(FAMILIES)('$name: easeInOut passes through the midpoint without a step', ({ easeInOut }) => {
+    expect(easeInOut(0.5)).toBeCloseTo(0.5, 12);
+    const wide = Math.abs(easeInOut(0.5 + 1e-4) - easeInOut(0.5 - 1e-4));
+    const narrow = Math.abs(easeInOut(0.5 + 1e-6) - easeInOut(0.5 - 1e-6));
+    expect(narrow).toBeLessThan(Math.max(wide / 2, 1e-9));
+  });
+});
+
+describe('easing family reflection', () => {
+  // The workhorse. easeOut is easeIn rotated 180 degrees about the centre of the unit square, and that
+  // holds BY DEFINITION for every family here — so a constant that differs between the two, or a body
+  // pasted from the wrong neighbour, breaks it at once.
+  it.each(FAMILIES)('$name: easeOut(t) is 1 - easeIn(1 - t) across the interval', ({ easeIn, easeOut }) => {
+    for (const t of SAMPLES) {
+      expect(Math.abs(easeOut(t) - (1 - easeIn(1 - t)))).toBeLessThan(EPSILON);
+    }
+  });
+});
+
+describe('easing family shape', () => {
+  it.each(FAMILIES.filter((family) => family.monotonic))('$name: easeIn never steps back', ({ easeIn }) => {
+    for (let index = 1; index < SAMPLES.length; index += 1) {
+      expect(easeIn(SAMPLES[index])).toBeGreaterThanOrEqual(easeIn(SAMPLES[index - 1]));
+    }
+  });
+
+  // The overshoot IS the family. A wrong constant removes it silently and leaves a curve that still runs
+  // 0 to 1 monotonically — which every endpoint assertion in this package would happily accept.
+  it.each([
+    { easeIn: easeInBack, easeOut: easeOutBack, name: 'Back' },
+    { easeIn: easeInElastic, easeOut: easeOutElastic, name: 'Elastic' },
+  ])('$name: easeIn dips below 0 and easeOut rises above 1', ({ easeIn, easeOut }) => {
+    expect(Math.min(...SAMPLES.map(easeIn))).toBeLessThan(-0.05);
+    expect(Math.max(...SAMPLES.map(easeOut))).toBeGreaterThan(1.05);
+  });
+
+  it('Bounce reverses without ever leaving the unit interval', () => {
+    const values = SAMPLES.map(easeInBounce);
+    expect(Math.min(...values)).toBeGreaterThanOrEqual(0);
+    expect(Math.max(...values)).toBeLessThanOrEqual(1);
+    expect(values.some((value, index) => index > 0 && value < values[index - 1])).toBe(true);
+  });
+});

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);
+  });
+});