@flighthq/math 0.1.0

package/src/interpolationAdvanced.test.ts

@@ -0,0 +1,122 @@
+import { damp, lerpAngle, moveTowards, pingPong, repeat, smootherStep } from './interpolationAdvanced';
+
+describe('damp', () => {
+  it('moves current toward target over time', () => {
+    const result = damp(0, 10, 1, 1);
+    expect(result).toBeGreaterThan(0);
+    expect(result).toBeLessThan(10);
+  });
+  it('returns current when deltaTime is 0', () => {
+    expect(damp(5, 10, 2, 0)).toBe(5);
+  });
+  it('returns current when lambda is 0', () => {
+    expect(damp(5, 10, 0, 1)).toBe(5);
+  });
+  it('approaches target asymptotically', () => {
+    const stepValue = damp(0, 1, 5, 0.1);
+    expect(stepValue).toBeGreaterThan(0.39);
+    expect(stepValue).toBeLessThan(0.41);
+  });
+  it('is frame-rate independent: two half-steps equal one full step', () => {
+    const full = damp(0, 1, 2, 0.2);
+    const half1 = damp(0, 1, 2, 0.1);
+    const half2 = damp(half1, 1, 2, 0.1);
+    expect(half2).toBeCloseTo(full, 10);
+  });
+});
+
+describe('lerpAngle', () => {
+  it('interpolates between two close angles', () => {
+    const result = lerpAngle(0, Math.PI / 2, 0.5);
+    expect(result).toBeCloseTo(Math.PI / 4, 10);
+  });
+  it('takes the shortest arc across 0/2π', () => {
+    // 1.9π → 0.1π: the short arc is +0.2π. At t = 0.5 the result is 1.9π + 0.1π = 2π.
+    // 2π and 0 are the same angle; normalise before comparing.
+    const TAU = Math.PI * 2;
+    const result = lerpAngle(Math.PI * 1.9, Math.PI * 0.1, 0.5);
+    const normalised = ((result % TAU) + TAU) % TAU;
+    expect(normalised).toBeCloseTo(0, 5);
+  });
+  it('returns a at t = 0', () => {
+    expect(lerpAngle(1, 2, 0)).toBeCloseTo(1, 10);
+  });
+  it('returns b at t = 1', () => {
+    expect(lerpAngle(1, 2, 1)).toBeCloseTo(2, 10);
+  });
+});
+
+describe('moveTowards', () => {
+  it('moves toward target by maxDelta', () => {
+    expect(moveTowards(0, 10, 3)).toBe(3);
+  });
+  it('snaps to target when within maxDelta', () => {
+    expect(moveTowards(9, 10, 5)).toBe(10);
+  });
+  it('works when target is below current', () => {
+    expect(moveTowards(10, 0, 3)).toBe(7);
+  });
+  it('returns target when current equals target', () => {
+    expect(moveTowards(5, 5, 1)).toBe(5);
+  });
+});
+
+describe('pingPong', () => {
+  it('starts at 0', () => {
+    expect(pingPong(0, 1)).toBe(0);
+  });
+  it('reaches length at t = length', () => {
+    expect(pingPong(1, 1)).toBe(1);
+  });
+  it('bounces back at t = 1.5 * length', () => {
+    expect(pingPong(1.5, 1)).toBeCloseTo(0.5, 10);
+  });
+  it('returns 0 when length is 0', () => {
+    expect(pingPong(1, 0)).toBe(0);
+  });
+  it('works with larger lengths', () => {
+    expect(pingPong(3, 2)).toBeCloseTo(1, 10);
+  });
+});
+
+describe('repeat', () => {
+  it('wraps t over [0, length)', () => {
+    expect(repeat(1.6, 1)).toBeCloseTo(0.6, 10);
+  });
+  it('returns 0 for exact multiple', () => {
+    expect(repeat(2, 1)).toBeCloseTo(0, 10);
+  });
+  it('handles negative t', () => {
+    const r = repeat(-0.3, 1);
+    expect(r).toBeGreaterThanOrEqual(0);
+    expect(r).toBeLessThan(1);
+  });
+  it('returns 0 when length is 0', () => {
+    expect(repeat(1, 0)).toBe(0);
+  });
+});
+
+describe('smootherStep', () => {
+  it('returns 0 at the lower edge', () => {
+    expect(smootherStep(0, 1, 0)).toBe(0);
+  });
+  it('returns 1 at the upper edge', () => {
+    expect(smootherStep(0, 1, 1)).toBe(1);
+  });
+  it('returns 0.5 at the midpoint', () => {
+    expect(smootherStep(0, 1, 0.5)).toBe(0.5);
+  });
+  it('returns 0 for x below the lower edge', () => {
+    expect(smootherStep(0, 1, -1)).toBe(0);
+  });
+  it('returns 1 for x above the upper edge', () => {
+    expect(smootherStep(0, 1, 2)).toBe(1);
+  });
+  it('has zero first and second derivatives at the edges', () => {
+    const h = 0.001;
+    const dLow = (smootherStep(0, 1, h) - smootherStep(0, 1, 0)) / h;
+    const dHigh = (smootherStep(0, 1, 1) - smootherStep(0, 1, 1 - h)) / h;
+    expect(dLow).toBeCloseTo(0, 1);
+    expect(dHigh).toBeCloseTo(0, 1);
+  });
+});

package/src/nextPowerOfTwo.test.ts

@@ -0,0 +1,84 @@
+import { isPowerOfTwo, nextMultipleOf, nextPowerOfTwo, previousPowerOfTwo } from './nextPowerOfTwo';
+
+describe('isPowerOfTwo', () => {
+  it('returns true for powers of two', () => {
+    expect(isPowerOfTwo(1)).toBe(true);
+    expect(isPowerOfTwo(2)).toBe(true);
+    expect(isPowerOfTwo(4)).toBe(true);
+    expect(isPowerOfTwo(64)).toBe(true);
+    expect(isPowerOfTwo(1024)).toBe(true);
+  });
+  it('returns false for non-powers of two', () => {
+    expect(isPowerOfTwo(3)).toBe(false);
+    expect(isPowerOfTwo(5)).toBe(false);
+    expect(isPowerOfTwo(100)).toBe(false);
+  });
+  it('returns false for 0', () => {
+    expect(isPowerOfTwo(0)).toBe(false);
+  });
+  it('returns false for negative numbers', () => {
+    expect(isPowerOfTwo(-1)).toBe(false);
+    expect(isPowerOfTwo(-4)).toBe(false);
+  });
+});
+
+describe('nextMultipleOf', () => {
+  it('rounds up to the next multiple', () => {
+    expect(nextMultipleOf(7, 4)).toBe(8);
+  });
+  it('leaves an exact multiple unchanged', () => {
+    expect(nextMultipleOf(8, 4)).toBe(8);
+  });
+  it('returns value when multiple is 0', () => {
+    expect(nextMultipleOf(7, 0)).toBe(7);
+  });
+  it('works with small values', () => {
+    expect(nextMultipleOf(1, 16)).toBe(16);
+    expect(nextMultipleOf(0, 4)).toBe(0);
+  });
+});
+
+describe('nextPowerOfTwo', () => {
+  it('returns 1 for 0', () => {
+    expect(nextPowerOfTwo(0)).toBe(1);
+  });
+  it('returns 1 for 1', () => {
+    expect(nextPowerOfTwo(1)).toBe(1);
+  });
+  it('returns an exact power of two unchanged', () => {
+    expect(nextPowerOfTwo(2)).toBe(2);
+    expect(nextPowerOfTwo(64)).toBe(64);
+    expect(nextPowerOfTwo(128)).toBe(128);
+    expect(nextPowerOfTwo(1024)).toBe(1024);
+  });
+  it('rounds up to the next power of two', () => {
+    expect(nextPowerOfTwo(3)).toBe(4);
+    expect(nextPowerOfTwo(5)).toBe(8);
+    expect(nextPowerOfTwo(100)).toBe(128);
+    expect(nextPowerOfTwo(129)).toBe(256);
+    expect(nextPowerOfTwo(1000)).toBe(1024);
+  });
+  it('handles negative numbers', () => {
+    expect(nextPowerOfTwo(-1)).toBe(1);
+  });
+});
+
+describe('previousPowerOfTwo', () => {
+  it('returns 1 for 1', () => {
+    expect(previousPowerOfTwo(1)).toBe(1);
+  });
+  it('returns 1 for values <= 1', () => {
+    expect(previousPowerOfTwo(0)).toBe(1);
+    expect(previousPowerOfTwo(-1)).toBe(1);
+  });
+  it('returns an exact power of two unchanged', () => {
+    expect(previousPowerOfTwo(4)).toBe(4);
+    expect(previousPowerOfTwo(64)).toBe(64);
+  });
+  it('rounds down to the previous power of two', () => {
+    expect(previousPowerOfTwo(6)).toBe(4);
+    expect(previousPowerOfTwo(100)).toBe(64);
+    expect(previousPowerOfTwo(200)).toBe(128);
+    expect(previousPowerOfTwo(1025)).toBe(1024);
+  });
+});

package/src/numberTheory.test.ts

@@ -0,0 +1,95 @@
+import { factorial, gcd, hypot2, isEven, isOdd, lcm } from './numberTheory';
+
+describe('factorial', () => {
+  it('returns 1 for 0', () => {
+    expect(factorial(0)).toBe(1);
+  });
+  it('returns 1 for 1', () => {
+    expect(factorial(1)).toBe(1);
+  });
+  it('computes common factorials', () => {
+    expect(factorial(5)).toBe(120);
+    expect(factorial(10)).toBe(3628800);
+  });
+  it('throws for negative integers', () => {
+    expect(() => factorial(-1)).toThrow(RangeError);
+  });
+  it('throws for non-integers', () => {
+    expect(() => factorial(1.5)).toThrow(RangeError);
+  });
+});
+
+describe('gcd', () => {
+  it('returns the gcd of two positive integers', () => {
+    expect(gcd(12, 8)).toBe(4);
+    expect(gcd(100, 75)).toBe(25);
+  });
+  it('returns the larger number when one is a multiple of the other', () => {
+    expect(gcd(6, 3)).toBe(3);
+  });
+  it('returns 1 for coprime numbers', () => {
+    expect(gcd(7, 13)).toBe(1);
+  });
+  it('accepts negative inputs', () => {
+    expect(gcd(-12, 8)).toBe(4);
+  });
+  it('accepts zero as one argument', () => {
+    expect(gcd(0, 5)).toBe(5);
+    expect(gcd(7, 0)).toBe(7);
+  });
+  it('throws when both arguments are 0', () => {
+    expect(() => gcd(0, 0)).toThrow(RangeError);
+  });
+});
+
+describe('hypot2', () => {
+  it('returns x squared plus y squared', () => {
+    expect(hypot2(3, 4)).toBe(25);
+  });
+  it('returns 0 for zero inputs', () => {
+    expect(hypot2(0, 0)).toBe(0);
+  });
+  it('matches Math.hypot squared', () => {
+    const h = Math.hypot(5, 12);
+    expect(hypot2(5, 12)).toBeCloseTo(h * h, 10);
+  });
+});
+
+describe('isEven', () => {
+  it('returns true for even numbers', () => {
+    expect(isEven(0)).toBe(true);
+    expect(isEven(2)).toBe(true);
+    expect(isEven(100)).toBe(true);
+  });
+  it('returns false for odd numbers', () => {
+    expect(isEven(1)).toBe(false);
+    expect(isEven(3)).toBe(false);
+    expect(isEven(99)).toBe(false);
+  });
+});
+
+describe('isOdd', () => {
+  it('returns true for odd numbers', () => {
+    expect(isOdd(1)).toBe(true);
+    expect(isOdd(3)).toBe(true);
+    expect(isOdd(99)).toBe(true);
+  });
+  it('returns false for even numbers', () => {
+    expect(isOdd(0)).toBe(false);
+    expect(isOdd(2)).toBe(false);
+    expect(isOdd(100)).toBe(false);
+  });
+});
+
+describe('lcm', () => {
+  it('returns the lcm of two positive integers', () => {
+    expect(lcm(4, 6)).toBe(12);
+    expect(lcm(3, 5)).toBe(15);
+  });
+  it('returns the larger number when one is a multiple of the other', () => {
+    expect(lcm(4, 8)).toBe(8);
+  });
+  it('accepts negative inputs', () => {
+    expect(lcm(-4, 6)).toBe(12);
+  });
+});

package/src/random.test.ts

@@ -0,0 +1,32 @@
+import { createRandomSource } from './random';
+
+describe('createRandomSource', () => {
+  it('produces values in [0, 1)', () => {
+    const rng = createRandomSource(1);
+    for (let i = 0; i < 1000; i++) {
+      const v = rng();
+      expect(v).toBeGreaterThanOrEqual(0);
+      expect(v).toBeLessThan(1);
+    }
+  });
+
+  it('is deterministic — same seed yields the same sequence', () => {
+    const a = createRandomSource(0xc0ffee);
+    const b = createRandomSource(0xc0ffee);
+    for (let i = 0; i < 100; i++) expect(a()).toBe(b());
+  });
+
+  it('different seeds yield different sequences', () => {
+    const a = createRandomSource(1);
+    const b = createRandomSource(2);
+    let differs = false;
+    for (let i = 0; i < 10; i++) if (a() !== b()) differs = true;
+    expect(differs).toBe(true);
+  });
+
+  it('tolerates non-finite seeds without producing NaN', () => {
+    const rng = createRandomSource(NaN);
+    const v = rng();
+    expect(Number.isFinite(v)).toBe(true);
+  });
+});

package/src/randomDistributions.test.ts

@@ -0,0 +1,348 @@
+import { createRandomSource } from './random';
+import {
+  pick,
+  randomExponential,
+  randomGaussian,
+  randomGaussianPair,
+  randomInsideUnitDisc,
+  randomInsideUnitSphere,
+  randomOnUnitCircle,
+  randomOnUnitSphere,
+  randomPoisson,
+  randomWeighted,
+  shuffle,
+  shuffleInPlace,
+} from './randomDistributions';
+
+const rng = () => createRandomSource(0xabcdef);
+
+describe('pick', () => {
+  it('returns an element from the array', () => {
+    const items = [1, 2, 3, 4, 5];
+    const random = rng();
+    for (let i = 0; i < 50; i++) {
+      expect(items).toContain(pick(random, items));
+    }
+  });
+  it('returns undefined for an empty array', () => {
+    expect(pick(rng(), [])).toBeUndefined();
+  });
+  it('always returns the only element in a single-item array', () => {
+    const random = rng();
+    for (let i = 0; i < 20; i++) expect(pick(random, [42])).toBe(42);
+  });
+  it('is deterministic for the same seed', () => {
+    const items = ['a', 'b', 'c', 'd'];
+    const a = rng();
+    const b = rng();
+    for (let i = 0; i < 20; i++) expect(pick(a, items)).toBe(pick(b, items));
+  });
+});
+
+describe('randomExponential', () => {
+  it('returns a non-negative value', () => {
+    const random = rng();
+    for (let i = 0; i < 200; i++) {
+      expect(randomExponential(random)).toBeGreaterThanOrEqual(0);
+    }
+  });
+  it('mean approximates 1/rate for rate=1', () => {
+    const random = rng();
+    let sum = 0;
+    const n = 5000;
+    for (let i = 0; i < n; i++) sum += randomExponential(random, 1);
+    expect(sum / n).toBeCloseTo(1, 0);
+  });
+  it('mean approximates 1/rate for rate=2', () => {
+    const random = rng();
+    let sum = 0;
+    const n = 5000;
+    for (let i = 0; i < n; i++) sum += randomExponential(random, 2);
+    expect(sum / n).toBeCloseTo(0.5, 0);
+  });
+  it('throws for rate <= 0', () => {
+    expect(() => randomExponential(rng(), 0)).toThrow(RangeError);
+    expect(() => randomExponential(rng(), -1)).toThrow(RangeError);
+  });
+  it('is deterministic for the same seed', () => {
+    const a = rng();
+    const b = rng();
+    for (let i = 0; i < 20; i++) expect(randomExponential(a)).toBe(randomExponential(b));
+  });
+});
+
+describe('randomGaussian', () => {
+  it('produces finite values', () => {
+    const random = rng();
+    for (let i = 0; i < 100; i++) expect(Number.isFinite(randomGaussian(random))).toBe(true);
+  });
+  it('centers around the mean', () => {
+    const random = rng();
+    let sum = 0;
+    const n = 2000;
+    for (let i = 0; i < n; i++) sum += randomGaussian(random, 5, 1);
+    expect(sum / n).toBeCloseTo(5, 0);
+  });
+  it('is deterministic for the same seed', () => {
+    const a = rng();
+    const b = rng();
+    for (let i = 0; i < 20; i++) expect(randomGaussian(a)).toBe(randomGaussian(b));
+  });
+});
+
+describe('randomGaussianPair', () => {
+  it('returns a tuple of two finite values', () => {
+    const random = rng();
+    const [z0, z1] = randomGaussianPair(random);
+    expect(Number.isFinite(z0)).toBe(true);
+    expect(Number.isFinite(z1)).toBe(true);
+  });
+  it('produces values matching the requested mean', () => {
+    const random = rng();
+    let sum = 0;
+    const n = 2000;
+    for (let i = 0; i < n; i++) {
+      const [z0, z1] = randomGaussianPair(random, 10, 1);
+      sum += z0 + z1;
+    }
+    expect(sum / (n * 2)).toBeCloseTo(10, 0);
+  });
+});
+
+describe('randomInsideUnitDisc', () => {
+  it('produces points inside the unit disc', () => {
+    const random = rng();
+    const out = { x: 0, y: 0 };
+    for (let i = 0; i < 200; i++) {
+      randomInsideUnitDisc(random, out);
+      expect(out.x * out.x + out.y * out.y).toBeLessThanOrEqual(1 + 1e-9);
+    }
+  });
+  it('is alias-safe when out is the same object as input', () => {
+    const random = rng();
+    const out = { x: 0, y: 0 };
+    // Should not throw or produce garbage when aliased
+    randomInsideUnitDisc(random, out);
+    expect(Number.isFinite(out.x)).toBe(true);
+    expect(Number.isFinite(out.y)).toBe(true);
+  });
+  it('is deterministic for the same seed', () => {
+    const a = rng();
+    const b = rng();
+    const outA = { x: 0, y: 0 };
+    const outB = { x: 0, y: 0 };
+    for (let i = 0; i < 20; i++) {
+      randomInsideUnitDisc(a, outA);
+      randomInsideUnitDisc(b, outB);
+      expect(outA.x).toBe(outB.x);
+      expect(outA.y).toBe(outB.y);
+    }
+  });
+});
+
+describe('randomInsideUnitSphere', () => {
+  it('produces points with radius <= 1', () => {
+    const random = rng();
+    const out = { x: 0, y: 0, z: 0 };
+    for (let i = 0; i < 200; i++) {
+      randomInsideUnitSphere(random, out);
+      expect(out.x * out.x + out.y * out.y + out.z * out.z).toBeLessThanOrEqual(1 + 1e-9);
+    }
+  });
+  it('is alias-safe when out is the same object as input', () => {
+    const random = rng();
+    const out = { x: 0, y: 0, z: 0 };
+    randomInsideUnitSphere(random, out);
+    expect(Number.isFinite(out.x)).toBe(true);
+    expect(Number.isFinite(out.y)).toBe(true);
+    expect(Number.isFinite(out.z)).toBe(true);
+  });
+  it('is deterministic for the same seed', () => {
+    const a = rng();
+    const b = rng();
+    const outA = { x: 0, y: 0, z: 0 };
+    const outB = { x: 0, y: 0, z: 0 };
+    for (let i = 0; i < 20; i++) {
+      randomInsideUnitSphere(a, outA);
+      randomInsideUnitSphere(b, outB);
+      expect(outA.x).toBe(outB.x);
+      expect(outA.y).toBe(outB.y);
+      expect(outA.z).toBe(outB.z);
+    }
+  });
+});
+
+describe('randomOnUnitCircle', () => {
+  it('produces points on the unit circle', () => {
+    const random = rng();
+    const out = { x: 0, y: 0 };
+    for (let i = 0; i < 100; i++) {
+      randomOnUnitCircle(random, out);
+      expect(out.x * out.x + out.y * out.y).toBeCloseTo(1, 8);
+    }
+  });
+  it('is alias-safe when out is the same object as input', () => {
+    const random = rng();
+    const out = { x: 0, y: 0 };
+    randomOnUnitCircle(random, out);
+    expect(Number.isFinite(out.x)).toBe(true);
+    expect(Number.isFinite(out.y)).toBe(true);
+  });
+  it('is deterministic for the same seed', () => {
+    const a = rng();
+    const b = rng();
+    const outA = { x: 0, y: 0 };
+    const outB = { x: 0, y: 0 };
+    for (let i = 0; i < 20; i++) {
+      randomOnUnitCircle(a, outA);
+      randomOnUnitCircle(b, outB);
+      expect(outA.x).toBe(outB.x);
+      expect(outA.y).toBe(outB.y);
+    }
+  });
+});
+
+describe('randomOnUnitSphere', () => {
+  it('produces points on the unit sphere', () => {
+    const random = rng();
+    const out = { x: 0, y: 0, z: 0 };
+    for (let i = 0; i < 100; i++) {
+      randomOnUnitSphere(random, out);
+      const len2 = out.x * out.x + out.y * out.y + out.z * out.z;
+      expect(len2).toBeCloseTo(1, 8);
+    }
+  });
+  it('is alias-safe when out is the same object as input', () => {
+    const random = rng();
+    const out = { x: 0, y: 0, z: 0 };
+    randomOnUnitSphere(random, out);
+    expect(Number.isFinite(out.x)).toBe(true);
+    expect(Number.isFinite(out.y)).toBe(true);
+    expect(Number.isFinite(out.z)).toBe(true);
+  });
+  it('is deterministic for the same seed', () => {
+    const a = rng();
+    const b = rng();
+    const outA = { x: 0, y: 0, z: 0 };
+    const outB = { x: 0, y: 0, z: 0 };
+    for (let i = 0; i < 20; i++) {
+      randomOnUnitSphere(a, outA);
+      randomOnUnitSphere(b, outB);
+      expect(outA.x).toBe(outB.x);
+      expect(outA.y).toBe(outB.y);
+      expect(outA.z).toBe(outB.z);
+    }
+  });
+});
+
+describe('randomPoisson', () => {
+  it('returns a non-negative integer', () => {
+    const random = rng();
+    for (let i = 0; i < 200; i++) {
+      const k = randomPoisson(random, 3);
+      expect(Number.isInteger(k)).toBe(true);
+      expect(k).toBeGreaterThanOrEqual(0);
+    }
+  });
+  it('mean approximates lambda=1', () => {
+    const random = rng();
+    let sum = 0;
+    const n = 5000;
+    for (let i = 0; i < n; i++) sum += randomPoisson(random, 1);
+    expect(sum / n).toBeCloseTo(1, 0);
+  });
+  it('mean approximates lambda=5', () => {
+    const random = rng();
+    let sum = 0;
+    const n = 5000;
+    for (let i = 0; i < n; i++) sum += randomPoisson(random, 5);
+    expect(sum / n).toBeCloseTo(5, 0);
+  });
+  it('throws for lambda <= 0', () => {
+    expect(() => randomPoisson(rng(), 0)).toThrow(RangeError);
+    expect(() => randomPoisson(rng(), -1)).toThrow(RangeError);
+  });
+  it('is deterministic for the same seed', () => {
+    const a = rng();
+    const b = rng();
+    for (let i = 0; i < 20; i++) expect(randomPoisson(a, 3)).toBe(randomPoisson(b, 3));
+  });
+});
+
+describe('randomWeighted', () => {
+  it('returns indices within the weights array', () => {
+    const random = rng();
+    const weights = [1, 2, 3];
+    for (let i = 0; i < 100; i++) {
+      const idx = randomWeighted(random, weights);
+      expect(idx).toBeGreaterThanOrEqual(0);
+      expect(idx).toBeLessThan(weights.length);
+    }
+  });
+  it('returns -1 for an empty array', () => {
+    expect(randomWeighted(rng(), [])).toBe(-1);
+  });
+  it('returns -1 for an all-zero weight array', () => {
+    expect(randomWeighted(rng(), [0, 0, 0])).toBe(-1);
+  });
+  it('always returns the only non-zero index when all others are zero', () => {
+    const random = rng();
+    for (let i = 0; i < 20; i++) {
+      expect(randomWeighted(random, [0, 10, 0])).toBe(1);
+    }
+  });
+  it('is deterministic for the same seed', () => {
+    const a = rng();
+    const b = rng();
+    const weights = [1, 2, 3, 4];
+    for (let i = 0; i < 20; i++) {
+      expect(randomWeighted(a, weights)).toBe(randomWeighted(b, weights));
+    }
+  });
+});
+
+describe('shuffle', () => {
+  it('returns an array of the same length', () => {
+    const items = [1, 2, 3, 4, 5];
+    expect(shuffle(rng(), items)).toHaveLength(items.length);
+  });
+  it('contains all original elements', () => {
+    const items = [1, 2, 3, 4, 5];
+    const result = shuffle(rng(), items);
+    expect(result.sort()).toEqual(items.slice().sort());
+  });
+  it('does not mutate the original array', () => {
+    const items = [1, 2, 3, 4, 5];
+    const original = items.slice();
+    shuffle(rng(), items);
+    expect(items).toEqual(original);
+  });
+  it('is deterministic for the same seed', () => {
+    const items = [1, 2, 3, 4, 5, 6, 7, 8];
+    expect(shuffle(rng(), items)).toEqual(shuffle(rng(), items));
+  });
+});
+
+describe('shuffleInPlace', () => {
+  it('retains all original elements', () => {
+    const items = [1, 2, 3, 4, 5];
+    const original = items.slice().sort();
+    shuffleInPlace(rng(), items);
+    expect(items.sort()).toEqual(original);
+  });
+  it('mutates the original array', () => {
+    const items = [1, 2, 3, 4, 5, 6, 7, 8];
+    const copy = items.slice();
+    shuffleInPlace(rng(), items);
+    // After sufficient elements it should have changed (very unlikely to match)
+    // — use a large array to make accidental match astronomically unlikely.
+    expect(items).toHaveLength(copy.length);
+  });
+  it('is deterministic for the same seed', () => {
+    const a = [1, 2, 3, 4, 5, 6, 7, 8];
+    const b = [1, 2, 3, 4, 5, 6, 7, 8];
+    shuffleInPlace(rng(), a);
+    shuffleInPlace(rng(), b);
+    expect(a).toEqual(b);
+  });
+});