@flighthq/math 0.1.0

package/dist/scalar.d.ts

@@ -0,0 +1,30 @@
+/** Round `n` up to the next power of two.
+ *
+ *  Alias for `nextPowerOfTwo` — provided for clarity at texture-sizing call
+ *  sites where the direction is important.
+ */
+export declare function ceilPowerOfTwo(n: number): number;
+/** Round `n` down to the previous power of two.
+ *
+ *  Alias for `previousPowerOfTwo` — provided for clarity at texture-sizing
+ *  call sites where the direction is important.
+ */
+export declare function floorPowerOfTwo(n: number): number;
+/** Quantize `value` into `steps` equal buckets over `[min, max]`.
+ *
+ *  Returns a value snapped to one of `steps + 1` evenly-spaced values between
+ *  `min` and `max`. When `steps <= 0` the result is `min`. When `min === max`
+ *  the result is `min`.
+ *
+ *  ```ts
+ *  quantize(0.7, 4, 0, 1) // 0.75  (nearest of 0, 0.25, 0.5, 0.75, 1.0)
+ *  ```
+ */
+export declare function quantize(value: number, steps: number, min: number, max: number): number;
+/** Zero-aware sign: returns `1` for positive, `-1` for negative, `0` for zero.
+ *
+ *  Unlike `Math.sign`, this is explicit about the zero-aware contract, and the
+ *  name makes intent clear at call sites in animation and physics code.
+ */
+export declare function sign(value: number): number;
+//# sourceMappingURL=scalar.d.ts.map

package/dist/scalar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalar.d.ts","sourceRoot":"","sources":["../src/scalar.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIvF;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1C"}

package/dist/scalar.js

@@ -0,0 +1,42 @@
+import { nextPowerOfTwo, previousPowerOfTwo } from './nextPowerOfTwo';
+/** Round `n` up to the next power of two.
+ *
+ *  Alias for `nextPowerOfTwo` — provided for clarity at texture-sizing call
+ *  sites where the direction is important.
+ */
+export function ceilPowerOfTwo(n) {
+    return nextPowerOfTwo(n);
+}
+/** Round `n` down to the previous power of two.
+ *
+ *  Alias for `previousPowerOfTwo` — provided for clarity at texture-sizing
+ *  call sites where the direction is important.
+ */
+export function floorPowerOfTwo(n) {
+    return previousPowerOfTwo(n);
+}
+/** Quantize `value` into `steps` equal buckets over `[min, max]`.
+ *
+ *  Returns a value snapped to one of `steps + 1` evenly-spaced values between
+ *  `min` and `max`. When `steps <= 0` the result is `min`. When `min === max`
+ *  the result is `min`.
+ *
+ *  ```ts
+ *  quantize(0.7, 4, 0, 1) // 0.75  (nearest of 0, 0.25, 0.5, 0.75, 1.0)
+ *  ```
+ */
+export function quantize(value, steps, min, max) {
+    if (steps <= 0 || min === max)
+        return min;
+    const t = (value - min) / (max - min);
+    return min + (Math.round(Math.max(0, Math.min(1, t)) * steps) / steps) * (max - min);
+}
+/** Zero-aware sign: returns `1` for positive, `-1` for negative, `0` for zero.
+ *
+ *  Unlike `Math.sign`, this is explicit about the zero-aware contract, and the
+ *  name makes intent clear at call sites in animation and physics code.
+ */
+export function sign(value) {
+    return value > 0 ? 1 : value < 0 ? -1 : 0;
+}
+//# sourceMappingURL=scalar.js.map

package/dist/scalar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalar.js","sourceRoot":"","sources":["../src/scalar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtE;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,CAAS;IACtC,OAAO,cAAc,CAAC,CAAC,CAAC,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,CAAS;IACvC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa,EAAE,KAAa,EAAE,GAAW,EAAE,GAAW;IAC7E,IAAI,KAAK,IAAI,CAAC,IAAI,GAAG,KAAK,GAAG;QAAE,OAAO,GAAG,CAAC;IAC1C,MAAM,CAAC,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;IACtC,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;AACvF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,KAAa;IAChC,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5C,CAAC"}

package/dist/statistics.d.ts

@@ -0,0 +1,29 @@
+/** Return the arithmetic mean of `values`.
+ *
+ *  Returns `NaN` for an empty array. No allocation beyond the accumulator.
+ */
+export declare function mean(values: Readonly<number[]>): number;
+/** Return the median of `values`.
+ *
+ *  Allocates a sorted copy — does not mutate the input. Returns `NaN` for an
+ *  empty array.
+ */
+export declare function median(values: Readonly<number[]>): number;
+/** Return the population standard deviation of `values`.
+ *
+ *  Returns `NaN` for an empty array.
+ */
+export declare function standardDeviation(values: Readonly<number[]>): number;
+/** Return the population variance of `values`.
+ *
+ *  Returns `NaN` for an empty array, `0` for a single element.
+ */
+export declare function variance(values: Readonly<number[]>): number;
+/** Return the weighted average of `values` using `weights`.
+ *
+ *  Each `values[i]` is weighted by `weights[i]`. The arrays must have the same
+ *  length. Returns `NaN` for an empty array or if total weight is `0`. Throws
+ *  if `values.length !== weights.length`.
+ */
+export declare function weightedAverage(values: Readonly<number[]>, weights: Readonly<number[]>): number;
+//# sourceMappingURL=statistics.d.ts.map

package/dist/statistics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statistics.d.ts","sourceRoot":"","sources":["../src/statistics.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAKvD;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAKzD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAEpE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAS3D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAY/F"}

package/dist/statistics.js

@@ -0,0 +1,67 @@
+/** Return the arithmetic mean of `values`.
+ *
+ *  Returns `NaN` for an empty array. No allocation beyond the accumulator.
+ */
+export function mean(values) {
+    if (values.length === 0)
+        return NaN;
+    let sum = 0;
+    for (let i = 0; i < values.length; i++)
+        sum += values[i];
+    return sum / values.length;
+}
+/** Return the median of `values`.
+ *
+ *  Allocates a sorted copy — does not mutate the input. Returns `NaN` for an
+ *  empty array.
+ */
+export function median(values) {
+    if (values.length === 0)
+        return NaN;
+    const sorted = values.slice().sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 !== 0 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+/** Return the population standard deviation of `values`.
+ *
+ *  Returns `NaN` for an empty array.
+ */
+export function standardDeviation(values) {
+    return Math.sqrt(variance(values));
+}
+/** Return the population variance of `values`.
+ *
+ *  Returns `NaN` for an empty array, `0` for a single element.
+ */
+export function variance(values) {
+    if (values.length === 0)
+        return NaN;
+    const m = mean(values);
+    let sum = 0;
+    for (let i = 0; i < values.length; i++) {
+        const d = values[i] - m;
+        sum += d * d;
+    }
+    return sum / values.length;
+}
+/** Return the weighted average of `values` using `weights`.
+ *
+ *  Each `values[i]` is weighted by `weights[i]`. The arrays must have the same
+ *  length. Returns `NaN` for an empty array or if total weight is `0`. Throws
+ *  if `values.length !== weights.length`.
+ */
+export function weightedAverage(values, weights) {
+    if (values.length !== weights.length) {
+        throw new RangeError('weightedAverage: values and weights must have the same length');
+    }
+    if (values.length === 0)
+        return NaN;
+    let sumWeights = 0;
+    let sumProduct = 0;
+    for (let i = 0; i < values.length; i++) {
+        sumWeights += weights[i];
+        sumProduct += values[i] * weights[i];
+    }
+    return sumWeights === 0 ? NaN : sumProduct / sumWeights;
+}
+//# sourceMappingURL=statistics.js.map

package/dist/statistics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statistics.js","sourceRoot":"","sources":["../src/statistics.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,MAA0B;IAC7C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACpC,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC;IACzD,OAAO,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,MAA0B;IAC/C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACpC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC1C,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;AACrF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA0B;IAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,MAA0B;IACjD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACpC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACxB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;IACD,OAAO,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC;AAC7B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,MAA0B,EAAE,OAA2B;IACrF,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC;QACrC,MAAM,IAAI,UAAU,CAAC,+DAA+D,CAAC,CAAC;IACxF,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACpC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,UAAU,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;QACzB,UAAU,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,GAAG,UAAU,CAAC;AAC1D,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@flighthq/math",
+  "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/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Scalar numeric utilities — interpolation, clamping, angles, rounding, randomness, hashing, statistics, and number theory",
+  "sideEffects": false
+}

package/src/angle.test.ts

@@ -0,0 +1,83 @@
+import { degToRad, deltaAngle, normalizeAngle, radToDeg } from './angle';
+
+describe('degToRad', () => {
+  it('converts 0 degrees to 0 radians', () => {
+    expect(degToRad(0)).toBe(0);
+  });
+  it('converts 180 degrees to π', () => {
+    expect(degToRad(180)).toBeCloseTo(Math.PI, 10);
+  });
+  it('converts 360 degrees to 2π', () => {
+    expect(degToRad(360)).toBeCloseTo(Math.PI * 2, 10);
+  });
+  it('converts 90 degrees to π/2', () => {
+    expect(degToRad(90)).toBeCloseTo(Math.PI / 2, 10);
+  });
+  it('converts negative degrees', () => {
+    expect(degToRad(-90)).toBeCloseTo(-Math.PI / 2, 10);
+  });
+});
+
+describe('deltaAngle', () => {
+  it('returns 0 for identical angles', () => {
+    expect(deltaAngle(1, 1)).toBeCloseTo(0, 10);
+  });
+  it('returns the shortest arc when crossing 0', () => {
+    // from = π - 0.1, to = -(π - 0.1). The short arc going forward is 0.2 rad.
+    expect(deltaAngle(Math.PI - 0.1, -(Math.PI - 0.1))).toBeCloseTo(0.2, 5);
+  });
+  it('returns a positive delta when the target is ahead', () => {
+    expect(deltaAngle(0, Math.PI / 2)).toBeCloseTo(Math.PI / 2, 10);
+  });
+  it('returns a negative delta when the target is behind', () => {
+    expect(deltaAngle(Math.PI / 2, 0)).toBeCloseTo(-Math.PI / 2, 10);
+  });
+  it('result is always within (-π, π]', () => {
+    for (let i = -10; i <= 10; i++) {
+      const d = deltaAngle(i, i + 3);
+      expect(d).toBeGreaterThan(-Math.PI);
+      expect(d).toBeLessThanOrEqual(Math.PI);
+    }
+  });
+});
+
+describe('normalizeAngle', () => {
+  it('normalizes 0 to 0', () => {
+    expect(normalizeAngle(0)).toBeCloseTo(0, 10);
+  });
+  it('normalizes π to -π (range is [-π, π))', () => {
+    // The range is [-π, π): π is outside the range, maps to -π.
+    expect(normalizeAngle(Math.PI)).toBeCloseTo(-Math.PI, 5);
+  });
+  it('wraps 2π to 0', () => {
+    expect(normalizeAngle(Math.PI * 2)).toBeCloseTo(0, 10);
+  });
+  it('wraps values above π to the negative side', () => {
+    expect(normalizeAngle(Math.PI + 1)).toBeCloseTo(-(Math.PI - 1), 10);
+  });
+  it('wraps negative values into [-π, π)', () => {
+    expect(normalizeAngle(-Math.PI * 3)).toBeCloseTo(-Math.PI, 5);
+  });
+  it('result is always in [-π, π)', () => {
+    for (let i = -20; i <= 20; i++) {
+      const a = normalizeAngle(i);
+      expect(a).toBeGreaterThanOrEqual(-Math.PI);
+      expect(a).toBeLessThan(Math.PI);
+    }
+  });
+});
+
+describe('radToDeg', () => {
+  it('converts 0 radians to 0 degrees', () => {
+    expect(radToDeg(0)).toBe(0);
+  });
+  it('converts π to 180 degrees', () => {
+    expect(radToDeg(Math.PI)).toBeCloseTo(180, 10);
+  });
+  it('converts 2π to 360 degrees', () => {
+    expect(radToDeg(Math.PI * 2)).toBeCloseTo(360, 10);
+  });
+  it('is the inverse of degToRad', () => {
+    expect(radToDeg(degToRad(45))).toBeCloseTo(45, 10);
+  });
+});

package/src/clamp.test.ts

@@ -0,0 +1,61 @@
+import { clamp, inRange, saturate } from './clamp';
+
+describe('clamp', () => {
+  it('clamps below minimum', () => {
+    expect(clamp(-5, 0, 10)).toBe(0);
+  });
+  it('clamps above maximum', () => {
+    expect(clamp(15, 0, 10)).toBe(10);
+  });
+  it('leaves value within range unchanged', () => {
+    expect(clamp(5, 0, 10)).toBe(5);
+  });
+  it('leaves value equal to min unchanged', () => {
+    expect(clamp(0, 0, 10)).toBe(0);
+  });
+  it('leaves value equal to max unchanged', () => {
+    expect(clamp(10, 0, 10)).toBe(10);
+  });
+  it('propagates NaN', () => {
+    expect(clamp(NaN, 0, 10)).toBeNaN();
+  });
+});
+
+describe('inRange', () => {
+  it('returns true for a value within range', () => {
+    expect(inRange(5, 0, 10)).toBe(true);
+  });
+  it('returns true at the minimum boundary', () => {
+    expect(inRange(0, 0, 10)).toBe(true);
+  });
+  it('returns true at the maximum boundary', () => {
+    expect(inRange(10, 0, 10)).toBe(true);
+  });
+  it('returns false below minimum', () => {
+    expect(inRange(-1, 0, 10)).toBe(false);
+  });
+  it('returns false above maximum', () => {
+    expect(inRange(11, 0, 10)).toBe(false);
+  });
+});
+
+describe('saturate', () => {
+  it('clamps below 0 to 0', () => {
+    expect(saturate(-1)).toBe(0);
+  });
+  it('clamps above 1 to 1', () => {
+    expect(saturate(2)).toBe(1);
+  });
+  it('leaves value within [0, 1] unchanged', () => {
+    expect(saturate(0.5)).toBe(0.5);
+  });
+  it('leaves 0 unchanged', () => {
+    expect(saturate(0)).toBe(0);
+  });
+  it('leaves 1 unchanged', () => {
+    expect(saturate(1)).toBe(1);
+  });
+  it('returns 0 for NaN (GPU semantics)', () => {
+    expect(saturate(NaN)).toBe(0);
+  });
+});

package/src/comparison.test.ts

@@ -0,0 +1,54 @@
+import { approxEqual, approxEqualRelative, approxZero } from './comparison';
+
+describe('approxEqual', () => {
+  it('returns true for identical values', () => {
+    expect(approxEqual(1, 1)).toBe(true);
+  });
+  it('returns true when values are within the default epsilon', () => {
+    expect(approxEqual(1, 1 + 1e-7)).toBe(true);
+  });
+  it('returns false when values differ by more than the default epsilon', () => {
+    expect(approxEqual(1, 1 + 1e-5)).toBe(false);
+  });
+  it('accepts a custom epsilon', () => {
+    expect(approxEqual(1, 1.1, 0.2)).toBe(true);
+    expect(approxEqual(1, 1.3, 0.2)).toBe(false);
+  });
+  it('returns true for zero and near-zero', () => {
+    expect(approxEqual(0, 1e-7)).toBe(true);
+  });
+  it('works with negative values', () => {
+    expect(approxEqual(-1, -1 - 1e-7)).toBe(true);
+  });
+});
+
+describe('approxEqualRelative', () => {
+  it('returns true for identical values', () => {
+    expect(approxEqualRelative(1000, 1000)).toBe(true);
+  });
+  it('returns true for large values within relative epsilon', () => {
+    expect(approxEqualRelative(1e8, 1e8 + 1)).toBe(true);
+  });
+  it('returns false when large values differ beyond relative epsilon', () => {
+    expect(approxEqualRelative(1e8, 1e8 * 2)).toBe(false);
+  });
+  it('returns true for near-zero values within absolute epsilon', () => {
+    expect(approxEqualRelative(0, 1e-7)).toBe(true);
+  });
+});
+
+describe('approxZero', () => {
+  it('returns true for exact zero', () => {
+    expect(approxZero(0)).toBe(true);
+  });
+  it('returns true for values within epsilon', () => {
+    expect(approxZero(1e-7)).toBe(true);
+  });
+  it('returns false for values outside epsilon', () => {
+    expect(approxZero(1e-4)).toBe(false);
+  });
+  it('accepts a custom epsilon', () => {
+    expect(approxZero(0.01, 0.1)).toBe(true);
+    expect(approxZero(0.2, 0.1)).toBe(false);
+  });
+});

package/src/constants.test.ts

@@ -0,0 +1,38 @@
+import { DEG_TO_RAD, EPSILON, HALF_PI, RAD_TO_DEG, TAU } from './constants';
+
+describe('constants', () => {
+  describe('DEG_TO_RAD', () => {
+    it('converts 180 degrees to π', () => {
+      expect(180 * DEG_TO_RAD).toBeCloseTo(Math.PI, 10);
+    });
+    it('converts 360 degrees to 2π', () => {
+      expect(360 * DEG_TO_RAD).toBeCloseTo(Math.PI * 2, 10);
+    });
+  });
+  describe('EPSILON', () => {
+    it('is a positive number', () => {
+      expect(EPSILON).toBeGreaterThan(0);
+    });
+    it('is smaller than 1e-5', () => {
+      expect(EPSILON).toBeLessThan(1e-5);
+    });
+  });
+  describe('HALF_PI', () => {
+    it('equals π / 2', () => {
+      expect(HALF_PI).toBeCloseTo(Math.PI / 2, 10);
+    });
+  });
+  describe('RAD_TO_DEG', () => {
+    it('converts π radians to 180 degrees', () => {
+      expect(Math.PI * RAD_TO_DEG).toBeCloseTo(180, 10);
+    });
+    it('is the reciprocal of DEG_TO_RAD', () => {
+      expect(RAD_TO_DEG * DEG_TO_RAD).toBeCloseTo(1, 10);
+    });
+  });
+  describe('TAU', () => {
+    it('equals 2π', () => {
+      expect(TAU).toBeCloseTo(Math.PI * 2, 10);
+    });
+  });
+});

package/src/hash.test.ts

@@ -0,0 +1,84 @@
+import { createRandomSourceFromHash, hash2D, hash3D, hashCombine, hashUint32 } from './hash';
+
+describe('createRandomSourceFromHash', () => {
+  it('returns a random source that produces values in [0, 1)', () => {
+    const rng = createRandomSourceFromHash(3, 7);
+    for (let i = 0; i < 20; i++) {
+      const v = rng();
+      expect(v).toBeGreaterThanOrEqual(0);
+      expect(v).toBeLessThan(1);
+    }
+  });
+  it('produces different sequences for different (x, y) positions', () => {
+    const a = createRandomSourceFromHash(0, 0);
+    const b = createRandomSourceFromHash(1, 0);
+    let differs = false;
+    for (let i = 0; i < 10; i++) if (a() !== b()) differs = true;
+    expect(differs).toBe(true);
+  });
+  it('produces the same sequence for the same (x, y)', () => {
+    const a = createRandomSourceFromHash(5, 9);
+    const b = createRandomSourceFromHash(5, 9);
+    for (let i = 0; i < 20; i++) expect(a()).toBe(b());
+  });
+});
+
+describe('hash2D', () => {
+  it('returns a non-negative integer', () => {
+    const h = hash2D(3, 7);
+    expect(h).toBeGreaterThanOrEqual(0);
+    expect(Number.isInteger(h)).toBe(true);
+  });
+  it('is deterministic', () => {
+    expect(hash2D(5, 10)).toBe(hash2D(5, 10));
+  });
+  it('differs for different inputs', () => {
+    expect(hash2D(0, 0)).not.toBe(hash2D(1, 0));
+    expect(hash2D(0, 0)).not.toBe(hash2D(0, 1));
+  });
+});
+
+describe('hash3D', () => {
+  it('returns a non-negative integer', () => {
+    const h = hash3D(1, 2, 3);
+    expect(h).toBeGreaterThanOrEqual(0);
+    expect(Number.isInteger(h)).toBe(true);
+  });
+  it('is deterministic', () => {
+    expect(hash3D(1, 2, 3)).toBe(hash3D(1, 2, 3));
+  });
+  it('differs for different inputs', () => {
+    expect(hash3D(0, 0, 0)).not.toBe(hash3D(1, 0, 0));
+    expect(hash3D(0, 0, 0)).not.toBe(hash3D(0, 0, 1));
+  });
+});
+
+describe('hashCombine', () => {
+  it('returns a number', () => {
+    expect(typeof hashCombine(1, 2)).toBe('number');
+  });
+  it('is deterministic', () => {
+    expect(hashCombine(100, 200)).toBe(hashCombine(100, 200));
+  });
+  it('produces different results for different seeds', () => {
+    expect(hashCombine(1, 100)).not.toBe(hashCombine(2, 100));
+  });
+});
+
+describe('hashUint32', () => {
+  it('returns a non-negative integer', () => {
+    const h = hashUint32(42);
+    expect(h).toBeGreaterThanOrEqual(0);
+    expect(Number.isInteger(h)).toBe(true);
+  });
+  it('is deterministic', () => {
+    expect(hashUint32(12345)).toBe(hashUint32(12345));
+  });
+  it('produces different results for different inputs', () => {
+    expect(hashUint32(0)).not.toBe(hashUint32(1));
+    expect(hashUint32(100)).not.toBe(hashUint32(101));
+  });
+  it('handles 0', () => {
+    expect(hashUint32(0)).toBeGreaterThanOrEqual(0);
+  });
+});

package/src/interpolation.test.ts

@@ -0,0 +1,93 @@
+import { inverseLerp, lerp, remap, smoothStep, step } from './interpolation';
+
+describe('inverseLerp', () => {
+  it('returns 0 when value equals a', () => {
+    expect(inverseLerp(0, 10, 0)).toBe(0);
+  });
+  it('returns 1 when value equals b', () => {
+    expect(inverseLerp(0, 10, 10)).toBe(1);
+  });
+  it('returns 0.5 for the midpoint', () => {
+    expect(inverseLerp(0, 10, 5)).toBe(0.5);
+  });
+  it('returns 0 when a equals b to avoid division by zero', () => {
+    expect(inverseLerp(5, 5, 5)).toBe(0);
+  });
+  it('works with negative ranges', () => {
+    expect(inverseLerp(-10, 10, 0)).toBe(0.5);
+  });
+});
+
+describe('lerp', () => {
+  it('returns a when t is 0', () => {
+    expect(lerp(0, 10, 0)).toBe(0);
+  });
+  it('returns b when t is 1', () => {
+    expect(lerp(0, 10, 1)).toBe(10);
+  });
+  it('returns the midpoint for t = 0.5', () => {
+    expect(lerp(0, 10, 0.5)).toBe(5);
+  });
+  it('extrapolates when t is outside [0, 1]', () => {
+    expect(lerp(0, 10, 2)).toBe(20);
+    expect(lerp(0, 10, -1)).toBe(-10);
+  });
+  it('works with negative values', () => {
+    expect(lerp(-10, 10, 0.5)).toBe(0);
+  });
+});
+
+describe('remap', () => {
+  it('maps a value from one range to another', () => {
+    expect(remap(5, 0, 10, 0, 100)).toBe(50);
+  });
+  it('maps the minimum input to the minimum output', () => {
+    expect(remap(0, 0, 10, 50, 150)).toBe(50);
+  });
+  it('maps the maximum input to the maximum output', () => {
+    expect(remap(10, 0, 10, 50, 150)).toBe(150);
+  });
+  it('returns outMin when inMin equals inMax', () => {
+    expect(remap(5, 5, 5, 0, 100)).toBe(0);
+  });
+  it('works with inverted output ranges', () => {
+    expect(remap(5, 0, 10, 100, 0)).toBe(50);
+  });
+});
+
+describe('smoothStep', () => {
+  it('returns 0 at the lower edge', () => {
+    expect(smoothStep(0, 1, 0)).toBe(0);
+  });
+  it('returns 1 at the upper edge', () => {
+    expect(smoothStep(0, 1, 1)).toBe(1);
+  });
+  it('returns 0.5 at the midpoint', () => {
+    expect(smoothStep(0, 1, 0.5)).toBe(0.5);
+  });
+  it('returns 0 for x below the lower edge', () => {
+    expect(smoothStep(0, 1, -1)).toBe(0);
+  });
+  it('returns 1 for x above the upper edge', () => {
+    expect(smoothStep(0, 1, 2)).toBe(1);
+  });
+  it('has zero derivative at the edges', () => {
+    const h = 0.001;
+    const dLow = (smoothStep(0, 1, h) - smoothStep(0, 1, 0)) / h;
+    const dHigh = (smoothStep(0, 1, 1) - smoothStep(0, 1, 1 - h)) / h;
+    expect(dLow).toBeCloseTo(0, 1);
+    expect(dHigh).toBeCloseTo(0, 1);
+  });
+});
+
+describe('step', () => {
+  it('returns 0 when x is less than edge', () => {
+    expect(step(0.5, 0.3)).toBe(0);
+  });
+  it('returns 1 when x equals edge', () => {
+    expect(step(0.5, 0.5)).toBe(1);
+  });
+  it('returns 1 when x is greater than edge', () => {
+    expect(step(0.5, 0.7)).toBe(1);
+  });
+});