@flighthq/spring 0.1.0

package/dist/createSpring.d.ts

@@ -0,0 +1,3 @@
+import type { Spring } from '@flighthq/types';
+export declare function createSpring(value?: number, velocity?: number): Spring;
+//# sourceMappingURL=createSpring.d.ts.map

package/dist/createSpring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createSpring.d.ts","sourceRoot":"","sources":["../src/createSpring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAK9C,wBAAgB,YAAY,CAAC,KAAK,GAAE,MAAU,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAE5E"}

package/dist/createSpring.js

@@ -0,0 +1,7 @@
+// Allocate a scalar spring at `value` (default 0) with `velocity` (default 0). This is the only
+// allocating function for scalar springs; `updateSpring`, `resetSpring`, and the settle query all
+// write into or read an existing spring.
+export function createSpring(value = 0, velocity = 0) {
+    return { value, velocity };
+}
+//# sourceMappingURL=createSpring.js.map

package/dist/createSpring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createSpring.js","sourceRoot":"","sources":["../src/createSpring.ts"],"names":[],"mappings":"AAEA,gGAAgG;AAChG,kGAAkG;AAClG,yCAAyC;AACzC,MAAM,UAAU,YAAY,CAAC,QAAgB,CAAC,EAAE,WAAmB,CAAC;IAClE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC7B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './createSpring';
+export * from './isSpringSettled';
+export * from './resetSpring';
+export * from './spring2D';
+export * from './spring3D';
+export * from './springConfig';
+export * from './updateSpring';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './createSpring';
+export * from './isSpringSettled';
+export * from './resetSpring';
+export * from './spring2D';
+export * from './spring3D';
+export * from './springConfig';
+export * from './updateSpring';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC"}

package/dist/isSpringSettled.d.ts

@@ -0,0 +1,3 @@
+import type { Spring } from '@flighthq/types';
+export declare function isSpringSettled(spring: Readonly<Spring>, target: number, positionEpsilon?: number, velocityEpsilon?: number): boolean;
+//# sourceMappingURL=isSpringSettled.d.ts.map

package/dist/isSpringSettled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isSpringSettled.d.ts","sourceRoot":"","sources":["../src/isSpringSettled.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAS9C,wBAAgB,eAAe,CAC7B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,EACxB,MAAM,EAAE,MAAM,EACd,eAAe,GAAE,MAA8B,EAC/C,eAAe,GAAE,MAA8B,GAC9C,OAAO,CAET"}

package/dist/isSpringSettled.js

@@ -0,0 +1,15 @@
+import { approxEqual, approxZero } from '@flighthq/math';
+// Report whether `spring` has come to rest at `target`: its `value` is within `positionEpsilon` of
+// the target AND its `velocity` is within `velocityEpsilon` of zero. Both conditions are required —
+// a spring passing through the target at speed (an underdamped overshoot) is not settled.
+//
+// Settle is a property of position and velocity alone, independent of the `SpringConfig` that drove
+// the motion, so no config is taken. Epsilons default to a UI-scale tolerance; pass tighter or
+// looser values for the value's actual units.
+export function isSpringSettled(spring, target, positionEpsilon = SPRING_SETTLE_EPSILON, velocityEpsilon = SPRING_SETTLE_EPSILON) {
+    return approxEqual(spring.value, target, positionEpsilon) && approxZero(spring.velocity, velocityEpsilon);
+}
+// Default position/velocity tolerance for settle detection: fine enough that motion has visually
+// stopped for typical pixel/normalized values, loose enough not to wait on floating-point tails.
+const SPRING_SETTLE_EPSILON = 1e-3;
+//# sourceMappingURL=isSpringSettled.js.map

package/dist/isSpringSettled.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isSpringSettled.js","sourceRoot":"","sources":["../src/isSpringSettled.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGzD,mGAAmG;AACnG,oGAAoG;AACpG,0FAA0F;AAC1F,EAAE;AACF,oGAAoG;AACpG,+FAA+F;AAC/F,8CAA8C;AAC9C,MAAM,UAAU,eAAe,CAC7B,MAAwB,EACxB,MAAc,EACd,kBAA0B,qBAAqB,EAC/C,kBAA0B,qBAAqB;IAE/C,OAAO,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;AAC5G,CAAC;AAED,iGAAiG;AACjG,iGAAiG;AACjG,MAAM,qBAAqB,GAAG,IAAI,CAAC"}

package/dist/resetSpring.d.ts

@@ -0,0 +1,3 @@
+import type { Spring } from '@flighthq/types';
+export declare function resetSpring(spring: Spring, value: number, velocity?: number): void;
+//# sourceMappingURL=resetSpring.d.ts.map

package/dist/resetSpring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resetSpring.d.ts","sourceRoot":"","sources":["../src/resetSpring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAK9C,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAU,GAAG,IAAI,CAGrF"}

package/dist/resetSpring.js

@@ -0,0 +1,8 @@
+// Snap `spring` to `value` with `velocity` (default 0), discarding its current motion. Use this to
+// teleport a spring to a new state — e.g. initializing it at a target, or cutting a running spring
+// dead. Unlike `updateSpring`, this applies no dynamics; the spring simply becomes what is passed.
+export function resetSpring(spring, value, velocity = 0) {
+    spring.value = value;
+    spring.velocity = velocity;
+}
+//# sourceMappingURL=resetSpring.js.map

package/dist/resetSpring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resetSpring.js","sourceRoot":"","sources":["../src/resetSpring.ts"],"names":[],"mappings":"AAEA,mGAAmG;AACnG,mGAAmG;AACnG,mGAAmG;AACnG,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,KAAa,EAAE,WAAmB,CAAC;IAC7E,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAC;AAC7B,CAAC"}

package/dist/spring2D.d.ts

@@ -0,0 +1,5 @@
+import type { Spring2D, SpringConfig } from '@flighthq/types';
+export declare function createSpring2D(valueX?: number, valueY?: number, velocityX?: number, velocityY?: number): Spring2D;
+export declare function isSpring2DSettled(spring2D: Readonly<Spring2D>, targetX: number, targetY: number, positionEpsilon?: number, velocityEpsilon?: number): boolean;
+export declare function updateSpring2D(spring2D: Spring2D, targetX: number, targetY: number, config: Readonly<SpringConfig>, deltaTime: number): void;
+//# sourceMappingURL=spring2D.d.ts.map

package/dist/spring2D.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spring2D.d.ts","sourceRoot":"","sources":["../src/spring2D.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAQ9D,wBAAgB,cAAc,CAC5B,MAAM,GAAE,MAAU,EAClB,MAAM,GAAE,MAAU,EAClB,SAAS,GAAE,MAAU,EACrB,SAAS,GAAE,MAAU,GACpB,QAAQ,CAEV;AAID,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,eAAe,CAAC,EAAE,MAAM,EACxB,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAKT;AAKD,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC9B,SAAS,EAAE,MAAM,GAChB,IAAI,CAGN"}

package/dist/spring2D.js

@@ -0,0 +1,22 @@
+import { createSpring } from './createSpring';
+import { isSpringSettled } from './isSpringSettled';
+import { updateSpring } from './updateSpring';
+// Allocate a 2D spring as a pair of scalar springs, each at its `value*` (default 0) and `velocity*`
+// (default 0).
+export function createSpring2D(valueX = 0, valueY = 0, velocityX = 0, velocityY = 0) {
+    return { x: createSpring(valueX, velocityX), y: createSpring(valueY, velocityY) };
+}
+// Report whether both axes of `spring2D` have settled at (`targetX`, `targetY`) — the per-component
+// `isSpringSettled` on each axis, combined with AND. Epsilons apply to each axis independently.
+export function isSpring2DSettled(spring2D, targetX, targetY, positionEpsilon, velocityEpsilon) {
+    return (isSpringSettled(spring2D.x, targetX, positionEpsilon, velocityEpsilon) &&
+        isSpringSettled(spring2D.y, targetY, positionEpsilon, velocityEpsilon));
+}
+// Advance both axes of `spring2D` one `deltaTime` step toward (`targetX`, `targetY`) under the same
+// `config`, applying the scalar `updateSpring` per component. The axes are independent; sharing one
+// config just gives them the same response.
+export function updateSpring2D(spring2D, targetX, targetY, config, deltaTime) {
+    updateSpring(spring2D.x, targetX, config, deltaTime);
+    updateSpring(spring2D.y, targetY, config, deltaTime);
+}
+//# sourceMappingURL=spring2D.js.map

package/dist/spring2D.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spring2D.js","sourceRoot":"","sources":["../src/spring2D.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,qGAAqG;AACrG,eAAe;AACf,MAAM,UAAU,cAAc,CAC5B,SAAiB,CAAC,EAClB,SAAiB,CAAC,EAClB,YAAoB,CAAC,EACrB,YAAoB,CAAC;IAErB,OAAO,EAAE,CAAC,EAAE,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC,EAAE,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC;AACpF,CAAC;AAED,oGAAoG;AACpG,gGAAgG;AAChG,MAAM,UAAU,iBAAiB,CAC/B,QAA4B,EAC5B,OAAe,EACf,OAAe,EACf,eAAwB,EACxB,eAAwB;IAExB,OAAO,CACL,eAAe,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,EAAE,eAAe,CAAC;QACtE,eAAe,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,EAAE,eAAe,CAAC,CACvE,CAAC;AACJ,CAAC;AAED,oGAAoG;AACpG,oGAAoG;AACpG,4CAA4C;AAC5C,MAAM,UAAU,cAAc,CAC5B,QAAkB,EAClB,OAAe,EACf,OAAe,EACf,MAA8B,EAC9B,SAAiB;IAEjB,YAAY,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IACrD,YAAY,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC"}

package/dist/spring3D.d.ts

@@ -0,0 +1,5 @@
+import type { Spring3D, SpringConfig } from '@flighthq/types';
+export declare function createSpring3D(valueX?: number, valueY?: number, valueZ?: number, velocityX?: number, velocityY?: number, velocityZ?: number): Spring3D;
+export declare function isSpring3DSettled(spring3D: Readonly<Spring3D>, targetX: number, targetY: number, targetZ: number, positionEpsilon?: number, velocityEpsilon?: number): boolean;
+export declare function updateSpring3D(spring3D: Spring3D, targetX: number, targetY: number, targetZ: number, config: Readonly<SpringConfig>, deltaTime: number): void;
+//# sourceMappingURL=spring3D.d.ts.map

package/dist/spring3D.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spring3D.d.ts","sourceRoot":"","sources":["../src/spring3D.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAQ9D,wBAAgB,cAAc,CAC5B,MAAM,GAAE,MAAU,EAClB,MAAM,GAAE,MAAU,EAClB,MAAM,GAAE,MAAU,EAClB,SAAS,GAAE,MAAU,EACrB,SAAS,GAAE,MAAU,EACrB,SAAS,GAAE,MAAU,GACpB,QAAQ,CAMV;AAID,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,eAAe,CAAC,EAAE,MAAM,EACxB,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAMT;AAID,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC9B,SAAS,EAAE,MAAM,GAChB,IAAI,CAIN"}

package/dist/spring3D.js

@@ -0,0 +1,27 @@
+import { createSpring } from './createSpring';
+import { isSpringSettled } from './isSpringSettled';
+import { updateSpring } from './updateSpring';
+// Allocate a 3D spring as three scalar springs, each at its `value*` (default 0) and `velocity*`
+// (default 0).
+export function createSpring3D(valueX = 0, valueY = 0, valueZ = 0, velocityX = 0, velocityY = 0, velocityZ = 0) {
+    return {
+        x: createSpring(valueX, velocityX),
+        y: createSpring(valueY, velocityY),
+        z: createSpring(valueZ, velocityZ),
+    };
+}
+// Report whether all three axes of `spring3D` have settled at (`targetX`, `targetY`, `targetZ`) —
+// the per-component `isSpringSettled` on each axis, combined with AND.
+export function isSpring3DSettled(spring3D, targetX, targetY, targetZ, positionEpsilon, velocityEpsilon) {
+    return (isSpringSettled(spring3D.x, targetX, positionEpsilon, velocityEpsilon) &&
+        isSpringSettled(spring3D.y, targetY, positionEpsilon, velocityEpsilon) &&
+        isSpringSettled(spring3D.z, targetZ, positionEpsilon, velocityEpsilon));
+}
+// Advance all three axes of `spring3D` one `deltaTime` step toward (`targetX`, `targetY`, `targetZ`)
+// under the same `config`, applying the scalar `updateSpring` per component.
+export function updateSpring3D(spring3D, targetX, targetY, targetZ, config, deltaTime) {
+    updateSpring(spring3D.x, targetX, config, deltaTime);
+    updateSpring(spring3D.y, targetY, config, deltaTime);
+    updateSpring(spring3D.z, targetZ, config, deltaTime);
+}
+//# sourceMappingURL=spring3D.js.map

package/dist/spring3D.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spring3D.js","sourceRoot":"","sources":["../src/spring3D.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,iGAAiG;AACjG,eAAe;AACf,MAAM,UAAU,cAAc,CAC5B,SAAiB,CAAC,EAClB,SAAiB,CAAC,EAClB,SAAiB,CAAC,EAClB,YAAoB,CAAC,EACrB,YAAoB,CAAC,EACrB,YAAoB,CAAC;IAErB,OAAO;QACL,CAAC,EAAE,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC;QAClC,CAAC,EAAE,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC;QAClC,CAAC,EAAE,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC;KACnC,CAAC;AACJ,CAAC;AAED,kGAAkG;AAClG,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAC/B,QAA4B,EAC5B,OAAe,EACf,OAAe,EACf,OAAe,EACf,eAAwB,EACxB,eAAwB;IAExB,OAAO,CACL,eAAe,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,EAAE,eAAe,CAAC;QACtE,eAAe,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,EAAE,eAAe,CAAC;QACtE,eAAe,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,EAAE,eAAe,CAAC,CACvE,CAAC;AACJ,CAAC;AAED,qGAAqG;AACrG,6EAA6E;AAC7E,MAAM,UAAU,cAAc,CAC5B,QAAkB,EAClB,OAAe,EACf,OAAe,EACf,OAAe,EACf,MAA8B,EAC9B,SAAiB;IAEjB,YAAY,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IACrD,YAAY,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IACrD,YAAY,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC"}

package/dist/springConfig.d.ts

@@ -0,0 +1,4 @@
+import type { SpringConfig } from '@flighthq/types';
+export declare function createSpringConfig(frequency: number, dampingRatio: number): SpringConfig;
+export declare function createSpringConfigFromPhysical(stiffness: number, damping: number, mass: number): SpringConfig;
+//# sourceMappingURL=springConfig.d.ts.map

package/dist/springConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"springConfig.d.ts","sourceRoot":"","sources":["../src/springConfig.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAKpD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,YAAY,CAExF;AAMD,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAK7G"}

package/dist/springConfig.js

@@ -0,0 +1,18 @@
+import { TAU } from '@flighthq/math';
+// Allocate a `SpringConfig` from the designer-intuitive `frequency` (Hz) and `dampingRatio`
+// (0 undamped, <1 underdamped/overshoots, 1 critical/fastest-no-overshoot, >1 overdamped). This is
+// the primary constructor; use `createSpringConfigFromPhysical` when starting from raw physics.
+export function createSpringConfig(frequency, dampingRatio) {
+    return { dampingRatio, frequency };
+}
+// Allocate a `SpringConfig` from a physical spring: `stiffness` (k), `damping` (c), and `mass` (m).
+// Converts to the mass-independent form via `frequency = sqrt(k / m) / (2 * PI)` and
+// `dampingRatio = c / (2 * sqrt(k * m))`, the standard undamped-natural-frequency and
+// damping-ratio identities. Expects positive `stiffness` and `mass`.
+export function createSpringConfigFromPhysical(stiffness, damping, mass) {
+    return {
+        dampingRatio: damping / (2 * Math.sqrt(stiffness * mass)),
+        frequency: Math.sqrt(stiffness / mass) / TAU,
+    };
+}
+//# sourceMappingURL=springConfig.js.map

package/dist/springConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"springConfig.js","sourceRoot":"","sources":["../src/springConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAGrC,4FAA4F;AAC5F,mGAAmG;AACnG,gGAAgG;AAChG,MAAM,UAAU,kBAAkB,CAAC,SAAiB,EAAE,YAAoB;IACxE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;AACrC,CAAC;AAED,oGAAoG;AACpG,qFAAqF;AACrF,sFAAsF;AACtF,qEAAqE;AACrE,MAAM,UAAU,8BAA8B,CAAC,SAAiB,EAAE,OAAe,EAAE,IAAY;IAC7F,OAAO;QACL,YAAY,EAAE,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;QACzD,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,GAAG;KAC7C,CAAC;AACJ,CAAC"}

package/dist/updateSpring.d.ts

@@ -0,0 +1,3 @@
+import type { Spring, SpringConfig } from '@flighthq/types';
+export declare function updateSpring(spring: Spring, target: number, config: Readonly<SpringConfig>, deltaTime: number): void;
+//# sourceMappingURL=updateSpring.d.ts.map

package/dist/updateSpring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateSpring.d.ts","sourceRoot":"","sources":["../src/updateSpring.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAmB5D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CA+DpH"}

package/dist/updateSpring.js

@@ -0,0 +1,81 @@
+import { TAU } from '@flighthq/math';
+// Advance `spring` one step of `deltaTime` seconds toward `target` under `config`, writing the new
+// `value` and `velocity` back into `spring`. This is the scalar primitive; `updateSpring2D` and
+// `updateSpring3D` call it once per component. The `target` is per-step, not stored on the spring,
+// so it can change every frame.
+//
+// The step is the closed-form analytic solution of the damped-harmonic equation
+// `c'' + 2*zeta*omega*c' + omega^2*c = 0` (where `c = value - target`, `omega = 2*PI*frequency`,
+// `zeta = dampingRatio`), evaluated exactly over `deltaTime`. Because it is exact rather than an
+// explicit-Euler approximation, it is unconditionally stable: for a stiff spring at a large
+// `deltaTime` the decaying exponentials underflow to 0 and the coefficients stay bounded, so the
+// spring lands on the target with zero velocity instead of exploding. It behaves consistently across
+// frame rates (it is the analytic answer at any `deltaTime`) up to the usual limit that a target
+// which itself moves between steps is only sampled at step boundaries.
+//
+// `deltaTime <= 0` is a no-op. A non-positive `frequency` is an inert spring (no force, no change);
+// `dampingRatio` is clamped to `>= 0`. Inputs are read into locals before any write, so passing a
+// `spring` that also appears elsewhere is safe.
+export function updateSpring(spring, target, config, deltaTime) {
+    if (deltaTime <= 0)
+        return;
+    const frequency = config.frequency;
+    if (frequency <= 0)
+        return;
+    const value = spring.value;
+    const velocity = spring.velocity;
+    const dampingRatio = config.dampingRatio < 0 ? 0 : config.dampingRatio;
+    const omega = TAU * frequency;
+    // Offset from equilibrium; the analytic solution is in terms of this displacement.
+    const c0 = value - target;
+    let posPosCoef;
+    let posVelCoef;
+    let velPosCoef;
+    let velVelCoef;
+    if (dampingRatio > 1 + CRITICAL_BAND) {
+        // Overdamped: two distinct real roots z1 < z2 < 0 of s^2 + 2*zeta*omega*s + omega^2.
+        const zb = omega * Math.sqrt(dampingRatio * dampingRatio - 1);
+        const za = -omega * dampingRatio;
+        const z1 = za - zb;
+        const z2 = za + zb;
+        const e1 = Math.exp(z1 * deltaTime);
+        const e2 = Math.exp(z2 * deltaTime);
+        const invDenominator = 1 / (z2 - z1);
+        posPosCoef = (z2 * e1 - z1 * e2) * invDenominator;
+        posVelCoef = (e2 - e1) * invDenominator;
+        // z1 * z2 == omega^2 (product of the roots).
+        velPosCoef = z1 * z2 * (e1 - e2) * invDenominator;
+        velVelCoef = (z2 * e2 - z1 * e1) * invDenominator;
+    }
+    else if (dampingRatio < 1 - CRITICAL_BAND) {
+        // Underdamped: complex roots -alpha +/- i*beta; oscillates within a decaying envelope.
+        const alpha = dampingRatio * omega;
+        const beta = omega * Math.sqrt(1 - dampingRatio * dampingRatio);
+        const envelope = Math.exp(-alpha * deltaTime);
+        const cosine = Math.cos(beta * deltaTime);
+        const sine = Math.sin(beta * deltaTime);
+        const invBeta = 1 / beta;
+        posPosCoef = envelope * (cosine + alpha * invBeta * sine);
+        posVelCoef = envelope * invBeta * sine;
+        // omega^2 == alpha^2 + beta^2.
+        velPosCoef = -envelope * omega * omega * invBeta * sine;
+        velVelCoef = envelope * (cosine - alpha * invBeta * sine);
+    }
+    else {
+        // Critically damped (dampingRatio within CRITICAL_BAND of 1): a repeated real root -omega. Using
+        // the closed form here also avoids the divide-by-zero the over/under branches hit exactly at 1.
+        const envelope = Math.exp(-omega * deltaTime);
+        const omegaDt = omega * deltaTime;
+        posPosCoef = envelope * (1 + omegaDt);
+        posVelCoef = envelope * deltaTime;
+        velPosCoef = -envelope * omega * omega * deltaTime;
+        velVelCoef = envelope * (1 - omegaDt);
+    }
+    spring.value = target + posPosCoef * c0 + posVelCoef * velocity;
+    spring.velocity = velPosCoef * c0 + velVelCoef * velocity;
+}
+// Half-width of the damping-ratio band around 1 treated as critically damped. Inside it the
+// over/under-damped closed forms divide by a vanishing root separation, so the critical form is both
+// numerically safer and physically indistinguishable this close to 1.
+const CRITICAL_BAND = 1e-4;
+//# sourceMappingURL=updateSpring.js.map

package/dist/updateSpring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateSpring.js","sourceRoot":"","sources":["../src/updateSpring.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/spring",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/math": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Spring-physics animation — plain-data damped-harmonic springs (frequency + damping-ratio config, physical stiffness/damping/mass constructor) stepped by a numerically stable analytic integrator that stays finite for stiff springs at any deltaTime; scalar springs plus componentwise 2D/3D vector springs, settle detection, and reset",
+  "sideEffects": false
+}

package/src/createSpring.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+
+import { createSpring } from './createSpring';
+
+describe('createSpring', () => {
+  it('defaults value and velocity to 0', () => {
+    const spring = createSpring();
+    expect(spring.value).toBe(0);
+    expect(spring.velocity).toBe(0);
+  });
+
+  it('sets the provided value and velocity', () => {
+    const spring = createSpring(5, -2);
+    expect(spring.value).toBe(5);
+    expect(spring.velocity).toBe(-2);
+  });
+});

package/src/isSpringSettled.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+
+import { createSpring } from './createSpring';
+import { isSpringSettled } from './isSpringSettled';
+import { createSpringConfig } from './springConfig';
+import { updateSpring } from './updateSpring';
+
+describe('isSpringSettled', () => {
+  it('is false while the spring is still moving toward the target', () => {
+    const spring = createSpring(0);
+    const config = createSpringConfig(1, 1);
+    updateSpring(spring, 10, config, 1 / 60);
+    expect(isSpringSettled(spring, 10)).toBe(false);
+  });
+
+  it('is true once the spring rests at the target', () => {
+    const spring = createSpring(0);
+    const config = createSpringConfig(4, 1);
+    for (let i = 0; i < 600; i++) updateSpring(spring, 10, config, 1 / 60);
+    expect(isSpringSettled(spring, 10)).toBe(true);
+  });
+
+  it('is false at the target when velocity is still high (mid overshoot)', () => {
+    // At the target position but moving fast is not settled.
+    const spring = createSpring(10, 50);
+    expect(isSpringSettled(spring, 10)).toBe(false);
+  });
+
+  it('is false when at rest but away from the target', () => {
+    const spring = createSpring(3, 0);
+    expect(isSpringSettled(spring, 10)).toBe(false);
+  });
+
+  it('honors custom epsilons', () => {
+    const spring = createSpring(10.4, 0.4);
+    expect(isSpringSettled(spring, 10)).toBe(false);
+    expect(isSpringSettled(spring, 10, 0.5, 0.5)).toBe(true);
+  });
+});

package/src/resetSpring.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+
+import { createSpring } from './createSpring';
+import { resetSpring } from './resetSpring';
+
+describe('resetSpring', () => {
+  it('snaps value and velocity, defaulting velocity to 0', () => {
+    const spring = createSpring(3, 9);
+    resetSpring(spring, 100);
+    expect(spring.value).toBe(100);
+    expect(spring.velocity).toBe(0);
+  });
+
+  it('sets an explicit velocity', () => {
+    const spring = createSpring(0, 0);
+    resetSpring(spring, -5, 12);
+    expect(spring.value).toBe(-5);
+    expect(spring.velocity).toBe(12);
+  });
+});

package/src/spring2D.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+
+import { createSpring2D, isSpring2DSettled, updateSpring2D } from './spring2D';
+import { createSpringConfig } from './springConfig';
+
+describe('createSpring2D', () => {
+  it('defaults both axes to value 0 and velocity 0', () => {
+    const spring = createSpring2D();
+    expect(spring.x.value).toBe(0);
+    expect(spring.x.velocity).toBe(0);
+    expect(spring.y.value).toBe(0);
+    expect(spring.y.velocity).toBe(0);
+  });
+
+  it('sets per-axis value and velocity', () => {
+    const spring = createSpring2D(1, 2, 3, 4);
+    expect(spring.x.value).toBe(1);
+    expect(spring.y.value).toBe(2);
+    expect(spring.x.velocity).toBe(3);
+    expect(spring.y.velocity).toBe(4);
+  });
+});
+
+describe('isSpring2DSettled', () => {
+  it('is false until both axes rest at their targets', () => {
+    const spring = createSpring2D(0, 0);
+    const config = createSpringConfig(4, 1);
+    expect(isSpring2DSettled(spring, 10, -6)).toBe(false);
+    for (let i = 0; i < 600; i++) updateSpring2D(spring, 10, -6, config, 1 / 60);
+    expect(isSpring2DSettled(spring, 10, -6)).toBe(true);
+  });
+});
+
+describe('updateSpring2D', () => {
+  it('moves both components toward their targets', () => {
+    const spring = createSpring2D(0, 0);
+    const config = createSpringConfig(2, 1);
+    updateSpring2D(spring, 10, -20, config, 1 / 60);
+    expect(spring.x.value).toBeGreaterThan(0);
+    expect(spring.y.value).toBeLessThan(0);
+  });
+
+  it('drives the axes independently (matching the scalar solver per component)', () => {
+    // x and y use the same config but different targets, so they should reach different values.
+    const spring = createSpring2D(0, 0);
+    const config = createSpringConfig(2, 0.8);
+    for (let i = 0; i < 30; i++) updateSpring2D(spring, 10, 5, config, 1 / 60);
+    expect(spring.x.value).not.toBeCloseTo(spring.y.value, 3);
+  });
+});

package/src/spring3D.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+
+import { createSpring3D, isSpring3DSettled, updateSpring3D } from './spring3D';
+import { createSpringConfig } from './springConfig';
+
+describe('createSpring3D', () => {
+  it('defaults all axes to value 0 and velocity 0', () => {
+    const spring = createSpring3D();
+    expect(spring.x.value).toBe(0);
+    expect(spring.y.value).toBe(0);
+    expect(spring.z.value).toBe(0);
+    expect(spring.x.velocity).toBe(0);
+    expect(spring.y.velocity).toBe(0);
+    expect(spring.z.velocity).toBe(0);
+  });
+
+  it('sets per-axis value and velocity', () => {
+    const spring = createSpring3D(1, 2, 3, 4, 5, 6);
+    expect(spring.x.value).toBe(1);
+    expect(spring.y.value).toBe(2);
+    expect(spring.z.value).toBe(3);
+    expect(spring.x.velocity).toBe(4);
+    expect(spring.y.velocity).toBe(5);
+    expect(spring.z.velocity).toBe(6);
+  });
+});
+
+describe('isSpring3DSettled', () => {
+  it('is false until all three axes rest at their targets', () => {
+    const spring = createSpring3D(0, 0, 0);
+    const config = createSpringConfig(4, 1);
+    expect(isSpring3DSettled(spring, 10, -6, 3)).toBe(false);
+    for (let i = 0; i < 600; i++) updateSpring3D(spring, 10, -6, 3, config, 1 / 60);
+    expect(isSpring3DSettled(spring, 10, -6, 3)).toBe(true);
+  });
+});
+
+describe('updateSpring3D', () => {
+  it('moves all three components toward their targets', () => {
+    const spring = createSpring3D(0, 0, 0);
+    const config = createSpringConfig(2, 1);
+    updateSpring3D(spring, 10, -20, 30, config, 1 / 60);
+    expect(spring.x.value).toBeGreaterThan(0);
+    expect(spring.y.value).toBeLessThan(0);
+    expect(spring.z.value).toBeGreaterThan(0);
+  });
+});

package/src/springConfig.test.ts

@@ -0,0 +1,27 @@
+import { TAU } from '@flighthq/math';
+import { describe, expect, it } from 'vitest';
+
+import { createSpringConfig, createSpringConfigFromPhysical } from './springConfig';
+
+describe('createSpringConfig', () => {
+  it('stores frequency and dampingRatio verbatim', () => {
+    const config = createSpringConfig(2.5, 0.4);
+    expect(config.frequency).toBe(2.5);
+    expect(config.dampingRatio).toBe(0.4);
+  });
+});
+
+describe('createSpringConfigFromPhysical', () => {
+  it('maps k=100, c=20, m=1 to frequency = sqrt(k/m)/(2*PI) and dampingRatio = 1 (critical)', () => {
+    const config = createSpringConfigFromPhysical(100, 20, 1);
+    expect(config.frequency).toBeCloseTo(10 / TAU, 9);
+    expect(config.dampingRatio).toBeCloseTo(1, 12);
+  });
+
+  it('accounts for mass in both frequency and damping ratio', () => {
+    // k=100, m=4 -> sqrt(25)=5 -> frequency 5/TAU; c=20 -> 20/(2*sqrt(400))=0.5.
+    const config = createSpringConfigFromPhysical(100, 20, 4);
+    expect(config.frequency).toBeCloseTo(5 / TAU, 9);
+    expect(config.dampingRatio).toBeCloseTo(0.5, 12);
+  });
+});

package/src/updateSpring.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest';
+
+import { createSpring } from './createSpring';
+import { isSpringSettled } from './isSpringSettled';
+import { createSpringConfig } from './springConfig';
+import { updateSpring } from './updateSpring';
+
+describe('updateSpring', () => {
+  it('converges monotonically to the target with no overshoot when critically damped', () => {
+    const spring = createSpring(0);
+    const config = createSpringConfig(1, 1);
+    const target = 10;
+
+    let previous = spring.value;
+    for (let i = 0; i < 600; i++) {
+      updateSpring(spring, target, config, 1 / 60);
+      // Critical damping never overshoots and never reverses on a step-to-rest.
+      expect(spring.value).toBeGreaterThanOrEqual(previous - 1e-9);
+      expect(spring.value).toBeLessThanOrEqual(target + 1e-9);
+      previous = spring.value;
+    }
+    expect(spring.value).toBeCloseTo(target, 3);
+    expect(isSpringSettled(spring, target)).toBe(true);
+  });
+
+  it('overshoots the target at least once then settles when underdamped', () => {
+    const spring = createSpring(0);
+    const config = createSpringConfig(1, 0.3);
+    const target = 10;
+
+    let overshot = false;
+    for (let i = 0; i < 2000; i++) {
+      updateSpring(spring, target, config, 1 / 60);
+      if (spring.value > target + 0.05) overshot = true;
+    }
+    expect(overshot).toBe(true);
+    expect(isSpringSettled(spring, target)).toBe(true);
+  });
+
+  it('converges slowly without overshoot when overdamped', () => {
+    const underTarget = createSpring(0);
+    const config = createSpringConfig(1, 2);
+    const target = 10;
+
+    let previous = underTarget.value;
+    for (let i = 0; i < 120; i++) {
+      updateSpring(underTarget, target, config, 1 / 60);
+      expect(underTarget.value).toBeGreaterThanOrEqual(previous - 1e-9);
+      expect(underTarget.value).toBeLessThanOrEqual(target + 1e-9);
+      previous = underTarget.value;
+    }
+
+    // After the same wall time an overdamped spring lags behind a critically damped one.
+    const critical = createSpring(0);
+    const criticalConfig = createSpringConfig(1, 1);
+    for (let i = 0; i < 120; i++) updateSpring(critical, target, criticalConfig, 1 / 60);
+    expect(underTarget.value).toBeLessThan(critical.value);
+  });
+
+  it('stays finite and bounded for a stiff spring stepped at a huge deltaTime', () => {
+    const spring = createSpring(0);
+    const config = createSpringConfig(1000, 1);
+    const target = 10;
+
+    // An explicit-Euler integrator would explode here; the analytic step lands on the target.
+    updateSpring(spring, target, config, 1);
+    expect(Number.isFinite(spring.value)).toBe(true);
+    expect(Number.isFinite(spring.velocity)).toBe(true);
+    expect(spring.value).toBeCloseTo(target, 6);
+    expect(spring.velocity).toBeCloseTo(0, 6);
+  });
+
+  it('stays finite for a stiff underdamped spring stepped repeatedly at a huge deltaTime', () => {
+    const spring = createSpring(0);
+    const config = createSpringConfig(1000, 0.5);
+    const target = 10;
+
+    for (let i = 0; i < 50; i++) {
+      updateSpring(spring, target, config, 1);
+      expect(Number.isFinite(spring.value)).toBe(true);
+      expect(Number.isFinite(spring.velocity)).toBe(true);
+      expect(Math.abs(spring.value)).toBeLessThan(100);
+    }
+    expect(isSpringSettled(spring, target)).toBe(true);
+  });
+
+  it('is frame-rate independent for a constant target (analytic semigroup)', () => {
+    const config = createSpringConfig(2, 0.5);
+    const target = 7;
+
+    // 60 small steps of 1/60s cover exactly the same second as one 1s step; the exact analytic
+    // solution makes them agree to floating tolerance (M(dt)^60 == M(1)).
+    const fine = createSpring(0, 3);
+    for (let i = 0; i < 60; i++) updateSpring(fine, target, config, 1 / 60);
+
+    const coarse = createSpring(0, 3);
+    updateSpring(coarse, target, config, 1);
+
+    expect(fine.value).toBeCloseTo(coarse.value, 6);
+    expect(fine.velocity).toBeCloseTo(coarse.velocity, 6);
+  });
+
+  it('is a no-op for deltaTime <= 0', () => {
+    const spring = createSpring(4, 2);
+    const config = createSpringConfig(1, 1);
+
+    updateSpring(spring, 100, config, 0);
+    expect(spring.value).toBe(4);
+    expect(spring.velocity).toBe(2);
+
+    updateSpring(spring, 100, config, -1);
+    expect(spring.value).toBe(4);
+    expect(spring.velocity).toBe(2);
+  });
+
+  it('is inert for a non-positive frequency', () => {
+    const spring = createSpring(4, 2);
+    updateSpring(spring, 100, createSpringConfig(0, 1), 1 / 60);
+    expect(spring.value).toBe(4);
+    expect(spring.velocity).toBe(2);
+  });
+
+  it('reads value and velocity before writing (no self-clobber)', () => {
+    // The new value must use the OLD velocity; if the step wrote value before reading velocity the
+    // result would differ. A hand-rolled second reference spring from the same state must match.
+    const spring = createSpring(5, 2);
+    const reference = createSpring(5, 2);
+    const config = createSpringConfig(3, 0.7);
+
+    updateSpring(spring, 0, config, 1 / 60);
+    updateSpring(reference, 0, config, 1 / 60);
+    expect(spring.value).toBe(reference.value);
+    expect(spring.velocity).toBe(reference.velocity);
+    // A meaningful step actually moved and imparted velocity.
+    expect(spring.value).not.toBe(5);
+    expect(spring.velocity).not.toBe(2);
+  });
+});