@holoscript/std 7.0.0 → 7.0.1

package/src/__tests__/standard-library-fundamentals.test.ts

@@ -1,1318 +0,0 @@
-/**
- * @holoscript/std acceptance tests
- * Covers: types, collections, math, string, time
- */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-
-// ─────────────────────────────────────────────
-// types.ts
-// ─────────────────────────────────────────────
-import {
-  vec2,
-  vec3,
-  vec4,
-  quat,
-  transform,
-  rgb,
-  rgba,
-  hsl,
-  aabb,
-  ray,
-  vec3ToArray,
-  arrayToVec3,
-  quatToArray,
-  arrayToQuat,
-  parseColor,
-  colorToHex,
-} from '../types.js';
-
-// ─────────────────────────────────────────────
-// collections.ts
-// ─────────────────────────────────────────────
-import { List, HoloMap, HoloSet, SpatialGrid, PriorityQueue } from '../collections.js';
-
-// ─────────────────────────────────────────────
-// math.ts
-// ─────────────────────────────────────────────
-import {
-  PI,
-  TAU,
-  HALF_PI,
-  DEG_TO_RAD,
-  RAD_TO_DEG,
-  EPSILON,
-  clamp,
-  lerp,
-  inverseLerp,
-  remap,
-  smoothstep,
-  degToRad,
-  radToDeg,
-  mod,
-  fract,
-  sign,
-  step,
-  vec2Math,
-  vec3Math,
-  quatMath,
-  aabbMath,
-  noise,
-  random,
-} from '../math.js';
-
-// ─────────────────────────────────────────────
-// string.ts
-// ─────────────────────────────────────────────
-import {
-  capitalize,
-  titleCase,
-  camelCase,
-  pascalCase,
-  snakeCase,
-  kebabCase,
-  constantCase,
-  padLeft,
-  padRight,
-  center,
-  truncate,
-  truncateMiddle,
-  isBlank,
-  isNotBlank,
-  containsIgnoreCase,
-  startsWithIgnoreCase,
-  endsWithIgnoreCase,
-  isValidIdentifier,
-  isNumeric,
-  isAlphanumeric,
-  isAlpha,
-  repeat,
-  reverse,
-  count,
-  removeWhitespace,
-  collapseWhitespace,
-  removePrefix,
-  removeSuffix,
-  wrap,
-  unwrap,
-  lines,
-  words,
-  chars,
-  format,
-  formatBytes,
-  formatDuration,
-  escapeHtml,
-  unescapeHtml,
-  escapeRegex,
-  slugify,
-  levenshtein,
-  similarity,
-  indent,
-  dedent,
-  wordWrap,
-  randomString,
-  uuid,
-} from '../string.js';
-
-// ─────────────────────────────────────────────
-// time.ts
-// ─────────────────────────────────────────────
-import {
-  now,
-  sleep,
-  measure,
-  debounce,
-  throttle,
-  Stopwatch,
-  FrameTimer,
-  DateTime,
-} from '../time.js';
-
-// ═══════════════════════════════════════════════
-// types.ts
-// ═══════════════════════════════════════════════
-describe('types — factory functions', () => {
-  it('vec2 defaults to (0,0)', () => {
-    const v = vec2();
-    expect(v.x).toBe(0);
-    expect(v.y).toBe(0);
-  });
-
-  it('vec2 with values', () => {
-    const v = vec2(3, 4);
-    expect(v.x).toBe(3);
-    expect(v.y).toBe(4);
-  });
-
-  it('vec3 defaults to (0,0,0)', () => {
-    const v = vec3();
-    expect(v.x).toBe(0);
-    expect(v.y).toBe(0);
-    expect(v.z).toBe(0);
-  });
-
-  it('vec3 with values', () => {
-    const v = vec3(1, 2, 3);
-    expect(v.x).toBe(1);
-    expect(v.y).toBe(2);
-    expect(v.z).toBe(3);
-  });
-
-  it('vec4 with values', () => {
-    const v = vec4(1, 2, 3, 4);
-    expect(v.x).toBe(1);
-    expect(v.w).toBe(4);
-  });
-
-  it('quat defaults to identity', () => {
-    const q = quat();
-    expect(q.w).toBe(1);
-    expect(q.x).toBe(0);
-    expect(q.y).toBe(0);
-    expect(q.z).toBe(0);
-  });
-
-  it('transform has position, rotation, scale', () => {
-    const t = transform();
-    expect(t.position).toBeDefined();
-    expect(t.rotation).toBeDefined();
-    expect(t.scale).toBeDefined();
-  });
-
-  it('rgb creates color', () => {
-    const c = rgb(255, 0, 0);
-    expect(c.r).toBe(255);
-    expect(c.g).toBe(0);
-    expect(c.b).toBe(0);
-  });
-
-  it('rgba creates color with alpha', () => {
-    const c = rgba(0, 255, 0, 0.5);
-    expect(c.a).toBe(0.5);
-  });
-
-  it('aabb creates bounding box', () => {
-    const box = aabb(vec3(0, 0, 0), vec3(1, 1, 1));
-    expect(box.min).toBeDefined();
-    expect(box.max).toBeDefined();
-  });
-
-  it('ray creates ray with origin and direction', () => {
-    const r = ray(vec3(0, 0, 0), vec3(0, 1, 0));
-    expect(r.origin).toBeDefined();
-    expect(r.direction).toBeDefined();
-  });
-});
-
-describe('types — conversion utilities', () => {
-  it('vec3ToArray / arrayToVec3 round-trip', () => {
-    const v = vec3(1, 2, 3);
-    const arr = vec3ToArray(v);
-    expect(arr).toEqual([1, 2, 3]);
-    const v2 = arrayToVec3(arr);
-    // vec3() returns an Array-backed Vec3 with non-enumerable x/y/z accessors
-    // (types.ts:195). toEqual on {x,y,z} therefore fails on structure
-    // mismatch — assert each accessor instead to test the behavioral contract.
-    expect(v2.x).toBe(1);
-    expect(v2.y).toBe(2);
-    expect(v2.z).toBe(3);
-  });
-
-  it('quatToArray / arrayToQuat round-trip', () => {
-    const q = quat(0, 0, 0, 1);
-    const arr = quatToArray(q);
-    expect(arr.length).toBe(4);
-    const q2 = arrayToQuat(arr);
-    expect(q2.w).toBeCloseTo(1);
-  });
-
-  it('parseColor handles hex #RRGGBB', () => {
-    const c = parseColor('#ff0000');
-    expect(c).not.toBeNull();
-  });
-
-  it('parseColor handles named color', () => {
-    const c = parseColor('red');
-    expect(c).not.toBeNull();
-  });
-
-  it('colorToHex produces # string', () => {
-    const hex = colorToHex(rgb(255, 0, 0));
-    expect(hex).toMatch(/^#/);
-  });
-});
-
-// ═══════════════════════════════════════════════
-// collections — List
-// ═══════════════════════════════════════════════
-describe('List', () => {
-  it('creates empty list', () => {
-    const l = new List<number>();
-    expect(l.length).toBe(0);
-    expect(l.isEmpty).toBe(true);
-  });
-
-  it('creates from array', () => {
-    const l = new List([1, 2, 3]);
-    expect(l.length).toBe(3);
-  });
-
-  it('List.of()', () => {
-    const l = List.of(10, 20, 30);
-    expect(l.length).toBe(3);
-    expect(l.get(0)).toBe(10);
-  });
-
-  it('List.from()', () => {
-    const l = List.from([5, 6, 7]);
-    expect(l.get(2)).toBe(7);
-  });
-
-  it('List.range()', () => {
-    const l = List.range(0, 5, 1);
-    expect(l.length).toBe(5);
-    expect(l.get(4)).toBe(4);
-  });
-
-  it('map transforms elements', () => {
-    const l = List.of(1, 2, 3).map((x) => x * 2);
-    expect(l.toArray()).toEqual([2, 4, 6]);
-  });
-
-  it('filter keeps matching elements', () => {
-    const l = List.of(1, 2, 3, 4).filter((x) => x % 2 === 0);
-    expect(l.toArray()).toEqual([2, 4]);
-  });
-
-  it('reduce accumulates', () => {
-    const sum = List.of(1, 2, 3, 4).reduce((acc, x) => acc + x, 0);
-    expect(sum).toBe(10);
-  });
-
-  it('find returns matching element', () => {
-    const v = List.of(1, 2, 3).find((x) => x > 1);
-    expect(v).toBe(2);
-  });
-
-  it('some / every', () => {
-    const l = List.of(2, 4, 6);
-    expect(l.some((x) => x > 5)).toBe(true);
-    expect(l.every((x) => x % 2 === 0)).toBe(true);
-  });
-
-  it('concat combines lists', () => {
-    const a = List.of(1, 2);
-    const b = List.of(3, 4);
-    expect(a.concat(b).length).toBe(4);
-  });
-
-  it('append / prepend', () => {
-    const l = List.of(2, 3).prepend(1).append(4);
-    expect(l.toArray()).toEqual([1, 2, 3, 4]);
-  });
-
-  it('reverse', () => {
-    expect(List.of(1, 2, 3).reverse().toArray()).toEqual([3, 2, 1]);
-  });
-
-  it('sort', () => {
-    expect(
-      List.of(3, 1, 2)
-        .sort((a, b) => a - b)
-        .toArray()
-    ).toEqual([1, 2, 3]);
-  });
-
-  it('unique removes duplicates', () => {
-    expect(List.of(1, 2, 2, 3).unique().toArray()).toEqual([1, 2, 3]);
-  });
-
-  it('groupBy groups by key', () => {
-    const map = List.of('a', 'bb', 'c', 'dd').groupBy((s) => s.length);
-    expect(map.has(1)).toBe(true);
-    expect(map.has(2)).toBe(true);
-  });
-
-  it('partition splits into two', () => {
-    const [evens, odds] = List.of(1, 2, 3, 4).partition((x) => x % 2 === 0);
-    expect(evens.toArray()).toEqual([2, 4]);
-    expect(odds.toArray()).toEqual([1, 3]);
-  });
-
-  it('zip combines two lists', () => {
-    const z = List.of(1, 2, 3).zip(List.of('a', 'b', 'c'));
-    expect(z.get(0)).toEqual([1, 'a']);
-  });
-
-  it('flatten flattens one level', () => {
-    const l = List.of(List.of(1, 2), List.of(3, 4)).flatten();
-    expect(l.toArray()).toEqual([1, 2, 3, 4]);
-  });
-
-  it('sum / min / max / average', () => {
-    const nums = List.of(1, 2, 3, 4);
-    expect(nums.sum()).toBe(10);
-    expect(nums.min()).toBe(1);
-    expect(nums.max()).toBe(4);
-    expect(nums.average()).toBe(2.5);
-  });
-
-  it('take / drop', () => {
-    const l = List.of(1, 2, 3, 4, 5);
-    expect(l.take(3).toArray()).toEqual([1, 2, 3]);
-    expect(l.drop(3).toArray()).toEqual([4, 5]);
-  });
-
-  it('toSet converts to HoloSet', () => {
-    const s = List.of(1, 2, 3).toSet();
-    expect(s.has(2)).toBe(true);
-  });
-});
-
-// ═══════════════════════════════════════════════
-// collections — HoloMap
-// ═══════════════════════════════════════════════
-describe('HoloMap', () => {
-  it('creates empty map', () => {
-    const m = new HoloMap<string, number>();
-    expect(m.size).toBe(0);
-  });
-
-  it('HoloMap.of()', () => {
-    const m = HoloMap.of(['a', 1], ['b', 2]);
-    expect(m.size).toBe(2);
-    expect(m.get('a')).toBe(1);
-  });
-
-  it('HoloMap.from()', () => {
-    const m = HoloMap.from([
-      ['x', 10],
-      ['y', 20],
-    ]);
-    expect(m.get('y')).toBe(20);
-  });
-
-  it('HoloMap.fromObject()', () => {
-    const m = HoloMap.fromObject({ a: 1, b: 2 });
-    expect(m.get('a')).toBe(1);
-  });
-
-  it('set returns new map with entry', () => {
-    const m1 = HoloMap.of<string, number>(['a', 1]);
-    const m2 = m1.set('b', 2);
-    expect(m2.get('b')).toBe(2);
-    expect(m1.has('b')).toBe(false); // immutable
-  });
-
-  it('delete removes entry', () => {
-    const m = HoloMap.of(['a', 1], ['b', 2]).delete('a');
-    expect(m.has('a')).toBe(false);
-    expect(m.size).toBe(1);
-  });
-
-  it('merge combines maps', () => {
-    const a = HoloMap.of(['a', 1]);
-    const b = HoloMap.of(['b', 2]);
-    const c = a.merge(b);
-    expect(c.size).toBe(2);
-  });
-
-  it('keys / values / entries', () => {
-    const m = HoloMap.of(['a', 1], ['b', 2]);
-    expect(m.keys().toArray()).toContain('a');
-    expect(m.values().toArray()).toContain(1);
-    expect(m.entries().length).toBe(2);
-  });
-
-  it('map transforms values', () => {
-    const m = HoloMap.of(['a', 1], ['b', 2]).map((v) => v * 10);
-    expect(m.get('a')).toBe(10);
-  });
-
-  it('filter keeps matching entries', () => {
-    const m = HoloMap.of(['a', 1], ['b', 20]).filter((v) => v > 5);
-    expect(m.has('b')).toBe(true);
-    expect(m.has('a')).toBe(false);
-  });
-
-  it('toObject converts to plain object', () => {
-    const obj = HoloMap.of(['x', 1]).toObject();
-    expect(obj['x']).toBe(1);
-  });
-});
-
-// ═══════════════════════════════════════════════
-// collections — HoloSet
-// ═══════════════════════════════════════════════
-describe('HoloSet', () => {
-  it('creates empty set', () => {
-    const s = new HoloSet<number>();
-    expect(s.size).toBe(0);
-  });
-
-  it('HoloSet.of()', () => {
-    const s = HoloSet.of(1, 2, 3);
-    expect(s.size).toBe(3);
-    expect(s.has(2)).toBe(true);
-  });
-
-  it('HoloSet.from()', () => {
-    const s = HoloSet.from([4, 5, 6]);
-    expect(s.has(5)).toBe(true);
-  });
-
-  it('add returns new set', () => {
-    const s1 = HoloSet.of(1, 2);
-    const s2 = s1.add(3);
-    expect(s2.has(3)).toBe(true);
-    expect(s1.has(3)).toBe(false); // immutable
-  });
-
-  it('delete removes element', () => {
-    const s = HoloSet.of(1, 2, 3).delete(2);
-    expect(s.has(2)).toBe(false);
-  });
-
-  it('union', () => {
-    const a = HoloSet.of(1, 2);
-    const b = HoloSet.of(2, 3);
-    expect(a.union(b).size).toBe(3);
-  });
-
-  it('intersection', () => {
-    const a = HoloSet.of(1, 2, 3);
-    const b = HoloSet.of(2, 3, 4);
-    const i = a.intersection(b);
-    expect(i.toArray().sort()).toEqual([2, 3]);
-  });
-
-  it('difference', () => {
-    const a = HoloSet.of(1, 2, 3);
-    const b = HoloSet.of(2, 3);
-    expect(a.difference(b).toArray()).toEqual([1]);
-  });
-
-  it('symmetricDifference', () => {
-    const a = HoloSet.of(1, 2, 3);
-    const b = HoloSet.of(2, 3, 4);
-    const sd = a.symmetricDifference(b);
-    expect(sd.has(1)).toBe(true);
-    expect(sd.has(4)).toBe(true);
-    expect(sd.has(2)).toBe(false);
-  });
-
-  it('isSubsetOf / isSupersetOf', () => {
-    const small = HoloSet.of(1, 2);
-    const big = HoloSet.of(1, 2, 3);
-    expect(small.isSubsetOf(big)).toBe(true);
-    expect(big.isSupersetOf(small)).toBe(true);
-  });
-
-  it('isDisjointFrom', () => {
-    const a = HoloSet.of(1, 2);
-    const b = HoloSet.of(3, 4);
-    expect(a.isDisjointFrom(b)).toBe(true);
-  });
-
-  it('toArray / toList / toNativeSet', () => {
-    const s = HoloSet.of(1, 2, 3);
-    expect(s.toArray().length).toBe(3);
-    expect(s.toList().length).toBe(3);
-    expect(s.toNativeSet().size).toBe(3);
-  });
-});
-
-// ═══════════════════════════════════════════════
-// collections — PriorityQueue
-// ═══════════════════════════════════════════════
-describe('PriorityQueue', () => {
-  it('minHeap dequeues lowest priority first', () => {
-    const pq = PriorityQueue.minHeap<string>();
-    pq.enqueue('low', 10);
-    pq.enqueue('high', 1);
-    pq.enqueue('mid', 5);
-    expect(pq.dequeue()).toBe('high');
-    expect(pq.dequeue()).toBe('mid');
-    expect(pq.dequeue()).toBe('low');
-  });
-
-  it('maxHeap dequeues highest priority first', () => {
-    const pq = PriorityQueue.maxHeap<string>();
-    pq.enqueue('a', 1);
-    pq.enqueue('b', 10);
-    pq.enqueue('c', 5);
-    expect(pq.dequeue()).toBe('b');
-  });
-
-  it('peek returns top without removing', () => {
-    const pq = PriorityQueue.minHeap<number>();
-    pq.enqueue(42, 1);
-    expect(pq.peek()).toBe(42);
-    expect(pq.size).toBe(1);
-  });
-
-  it('isEmpty / size', () => {
-    const pq = PriorityQueue.minHeap<number>();
-    expect(pq.isEmpty).toBe(true);
-    pq.enqueue(1, 1);
-    expect(pq.size).toBe(1);
-    expect(pq.isEmpty).toBe(false);
-  });
-
-  it('clear empties queue', () => {
-    const pq = PriorityQueue.minHeap<number>();
-    pq.enqueue(1, 1);
-    pq.clear();
-    expect(pq.isEmpty).toBe(true);
-  });
-});
-
-// ═══════════════════════════════════════════════
-// collections — SpatialGrid
-// ═══════════════════════════════════════════════
-describe('SpatialGrid', () => {
-  it('insert and query by radius', () => {
-    const grid = new SpatialGrid<string>(1.0);
-    grid.insert({ x: 0, y: 0, z: 0 }, 'origin');
-    grid.insert({ x: 10, y: 0, z: 0 }, 'far');
-    const results = grid.query({ x: 0, y: 0, z: 0 }, 1.5);
-    expect(results).toContain('origin');
-    expect(results).not.toContain('far');
-  });
-
-  it('remove deletes item', () => {
-    const grid = new SpatialGrid<string>(1.0);
-    grid.insert({ x: 0, y: 0, z: 0 }, 'item');
-    grid.remove({ x: 0, y: 0, z: 0 }, 'item');
-    const results = grid.query({ x: 0, y: 0, z: 0 }, 1.5);
-    expect(results).not.toContain('item');
-  });
-
-  it('queryBox returns items in AABB', () => {
-    const grid = new SpatialGrid<string>(1.0);
-    grid.insert({ x: 0.5, y: 0.5, z: 0.5 }, 'inside');
-    grid.insert({ x: 5, y: 5, z: 5 }, 'outside');
-    const results = grid.queryBox({ x: 0, y: 0, z: 0 }, { x: 1, y: 1, z: 1 });
-    expect(results).toContain('inside');
-    expect(results).not.toContain('outside');
-  });
-});
-
-// ═══════════════════════════════════════════════
-// math — constants
-// ═══════════════════════════════════════════════
-describe('math constants', () => {
-  it('PI is ~3.14159', () => expect(PI).toBeCloseTo(3.14159, 4));
-  it('TAU is 2*PI', () => expect(TAU).toBeCloseTo(PI * 2, 10));
-  it('HALF_PI is PI/2', () => expect(HALF_PI).toBeCloseTo(PI / 2, 10));
-  it('DEG_TO_RAD * 180 = PI', () => expect(DEG_TO_RAD * 180).toBeCloseTo(PI, 10));
-  it('RAD_TO_DEG * PI = 180', () => expect(RAD_TO_DEG * PI).toBeCloseTo(180, 10));
-  it('EPSILON is small', () => expect(EPSILON).toBeGreaterThan(0));
-});
-
-// ═══════════════════════════════════════════════
-// math — basic functions
-// ═══════════════════════════════════════════════
-describe('math — basic functions', () => {
-  it('clamp', () => {
-    expect(clamp(5, 0, 10)).toBe(5);
-    expect(clamp(-5, 0, 10)).toBe(0);
-    expect(clamp(15, 0, 10)).toBe(10);
-  });
-
-  it('lerp', () => {
-    expect(lerp(0, 10, 0.5)).toBe(5);
-    expect(lerp(0, 10, 0)).toBe(0);
-    expect(lerp(0, 10, 1)).toBe(10);
-  });
-
-  it('inverseLerp', () => {
-    expect(inverseLerp(0, 10, 5)).toBeCloseTo(0.5);
-    expect(inverseLerp(0, 10, 0)).toBe(0);
-    expect(inverseLerp(0, 10, 10)).toBe(1);
-  });
-
-  it('remap', () => {
-    const result = remap(5, 0, 10, 0, 100);
-    expect(result).toBeCloseTo(50);
-  });
-
-  it('smoothstep', () => {
-    expect(smoothstep(0, 1, 0)).toBeCloseTo(0);
-    expect(smoothstep(0, 1, 1)).toBeCloseTo(1);
-    expect(smoothstep(0, 1, 0.5)).toBeCloseTo(0.5);
-  });
-
-  it('degToRad / radToDeg', () => {
-    expect(degToRad(180)).toBeCloseTo(PI);
-    expect(radToDeg(PI)).toBeCloseTo(180);
-  });
-
-  it('mod handles negative values correctly', () => {
-    expect(mod(7, 3)).toBe(1);
-    expect(mod(-1, 3)).toBeGreaterThanOrEqual(0);
-  });
-
-  it('fract returns fractional part', () => {
-    expect(fract(3.7)).toBeCloseTo(0.7);
-    expect(fract(3.0)).toBeCloseTo(0.0);
-  });
-
-  it('sign', () => {
-    expect(sign(5)).toBe(1);
-    expect(sign(-5)).toBe(-1);
-    expect(sign(0)).toBe(0);
-  });
-
-  it('step', () => {
-    expect(step(0.5, 0.3)).toBe(0);
-    expect(step(0.5, 0.7)).toBe(1);
-  });
-});
-
-// ═══════════════════════════════════════════════
-// math — vec2Math
-// ═══════════════════════════════════════════════
-describe('vec2Math', () => {
-  it('add', () => {
-    const r = vec2Math.add({ x: 1, y: 2 }, { x: 3, y: 4 });
-    expect(r).toEqual({ x: 4, y: 6 });
-  });
-
-  it('sub', () => {
-    const r = vec2Math.sub({ x: 5, y: 5 }, { x: 2, y: 3 });
-    expect(r).toEqual({ x: 3, y: 2 });
-  });
-
-  it('mul (scalar)', () => {
-    const r = vec2Math.mul({ x: 2, y: 3 }, 2);
-    expect(r).toEqual({ x: 4, y: 6 });
-  });
-
-  it('dot', () => {
-    expect(vec2Math.dot({ x: 1, y: 0 }, { x: 0, y: 1 })).toBe(0);
-    expect(vec2Math.dot({ x: 1, y: 0 }, { x: 1, y: 0 })).toBe(1);
-  });
-
-  it('length', () => {
-    expect(vec2Math.length({ x: 3, y: 4 })).toBeCloseTo(5);
-  });
-
-  it('normalize produces unit vector', () => {
-    const n = vec2Math.normalize({ x: 3, y: 4 });
-    expect(vec2Math.length(n)).toBeCloseTo(1);
-  });
-
-  it('distance', () => {
-    expect(vec2Math.distance({ x: 0, y: 0 }, { x: 3, y: 4 })).toBeCloseTo(5);
-  });
-
-  it('lerp', () => {
-    const r = vec2Math.lerp({ x: 0, y: 0 }, { x: 10, y: 10 }, 0.5);
-    expect(r).toEqual({ x: 5, y: 5 });
-  });
-
-  it('angle', () => {
-    const a = vec2Math.angle({ x: 1, y: 0 });
-    expect(a).toBeCloseTo(0);
-  });
-});
-
-// ═══════════════════════════════════════════════
-// math — vec3Math
-// ═══════════════════════════════════════════════
-describe('vec3Math', () => {
-  it('zero / one factory functions', () => {
-    // vec3() is Array-backed with non-enumerable x/y/z (types.ts:195); test
-    // accessor contract rather than object structure.
-    const z = vec3Math.zero();
-    expect(z.x).toBe(0);
-    expect(z.y).toBe(0);
-    expect(z.z).toBe(0);
-    const o = vec3Math.one();
-    expect(o.x).toBe(1);
-    expect(o.y).toBe(1);
-    expect(o.z).toBe(1);
-  });
-
-  it('up / down / forward / back factory functions', () => {
-    expect(vec3Math.up().y).toBe(1);
-    expect(vec3Math.down().y).toBe(-1);
-    expect(vec3Math.forward().z).not.toBeUndefined();
-    expect(vec3Math.back().z).not.toBeUndefined();
-  });
-
-  it('add', () => {
-    // vec3Math.add returns a vec3() (Array-backed with non-enumerable x/y/z).
-    // Assert accessor contract instead of object structure.
-    const r = vec3Math.add({ x: 1, y: 2, z: 3 }, { x: 4, y: 5, z: 6 });
-    expect(r.x).toBe(5);
-    expect(r.y).toBe(7);
-    expect(r.z).toBe(9);
-  });
-
-  it('sub', () => {
-    const r = vec3Math.sub({ x: 5, y: 5, z: 5 }, { x: 2, y: 3, z: 1 });
-    expect(r).toEqual({ x: 3, y: 2, z: 4 });
-  });
-
-  it('dot', () => {
-    expect(vec3Math.dot({ x: 1, y: 0, z: 0 }, { x: 0, y: 1, z: 0 })).toBe(0);
-  });
-
-  it('cross', () => {
-    const c = vec3Math.cross({ x: 1, y: 0, z: 0 }, { x: 0, y: 1, z: 0 });
-    expect(c).toEqual({ x: 0, y: 0, z: 1 });
-  });
-
-  it('length', () => {
-    expect(vec3Math.length({ x: 1, y: 2, z: 2 })).toBeCloseTo(3);
-  });
-
-  it('normalize', () => {
-    const n = vec3Math.normalize({ x: 0, y: 0, z: 5 });
-    expect(vec3Math.length(n)).toBeCloseTo(1);
-  });
-
-  it('distance', () => {
-    expect(vec3Math.distance({ x: 0, y: 0, z: 0 }, { x: 1, y: 2, z: 2 })).toBeCloseTo(3);
-  });
-
-  it('lerp', () => {
-    const r = vec3Math.lerp({ x: 0, y: 0, z: 0 }, { x: 2, y: 4, z: 6 }, 0.5);
-    expect(r).toEqual({ x: 1, y: 2, z: 3 });
-  });
-
-  it('negate', () => {
-    const n = vec3Math.negate({ x: 1, y: -2, z: 3 });
-    expect(n).toEqual({ x: -1, y: 2, z: -3 });
-  });
-
-  it('equals', () => {
-    expect(vec3Math.equals({ x: 1, y: 2, z: 3 }, { x: 1, y: 2, z: 3 })).toBe(true);
-    expect(vec3Math.equals({ x: 1, y: 2, z: 3 }, { x: 1, y: 2, z: 4 })).toBe(false);
-  });
-});
-
-// ═══════════════════════════════════════════════
-// math — quatMath
-// ═══════════════════════════════════════════════
-describe('quatMath', () => {
-  it('identity quaternion', () => {
-    const q = quatMath.identity();
-    expect(q.w).toBeCloseTo(1);
-    expect(q.x).toBeCloseTo(0);
-    expect(q.y).toBeCloseTo(0);
-    expect(q.z).toBeCloseTo(0);
-  });
-
-  it('fromAxisAngle', () => {
-    const q = quatMath.fromAxisAngle({ x: 0, y: 1, z: 0 }, 0);
-    expect(q.w).toBeCloseTo(1);
-  });
-
-  it('multiply identity stays identity', () => {
-    const id = quatMath.identity();
-    const q = quatMath.multiply(id, id);
-    expect(q.w).toBeCloseTo(1);
-  });
-
-  it('normalize', () => {
-    const q = { x: 0, y: 0, z: 0, w: 2 };
-    const n = quatMath.normalize(q);
-    expect(n.w).toBeCloseTo(1);
-  });
-
-  it('conjugate', () => {
-    const q = { x: 1, y: 0, z: 0, w: 0 };
-    const c = quatMath.conjugate(q);
-    expect(c.x).toBe(-1);
-  });
-
-  it('toEuler / fromEuler round-trip', () => {
-    const euler = { x: 0, y: 90, z: 0 };
-    const q = quatMath.fromEuler(euler);
-    const e2 = quatMath.toEuler(q);
-    expect(e2.y).toBeCloseTo(90, 0);
-  });
-
-  it('rotateVec3', () => {
-    const id = quatMath.identity();
-    const v = { x: 1, y: 0, z: 0 };
-    const r = quatMath.rotateVec3(id, v);
-    expect(r.x).toBeCloseTo(1);
-    expect(r.y).toBeCloseTo(0);
-  });
-});
-
-// ═══════════════════════════════════════════════
-// math — aabbMath
-// ═══════════════════════════════════════════════
-describe('aabbMath', () => {
-  const box = { min: { x: 0, y: 0, z: 0 }, max: { x: 2, y: 2, z: 2 } };
-
-  it('center', () => {
-    const c = aabbMath.center(box);
-    expect(c).toEqual({ x: 1, y: 1, z: 1 });
-  });
-
-  it('size', () => {
-    const s = aabbMath.size(box);
-    expect(s).toEqual({ x: 2, y: 2, z: 2 });
-  });
-
-  it('contains point inside', () => {
-    expect(aabbMath.contains(box, { x: 1, y: 1, z: 1 })).toBe(true);
-  });
-
-  it('contains point outside', () => {
-    expect(aabbMath.contains(box, { x: 5, y: 5, z: 5 })).toBe(false);
-  });
-
-  it('intersects overlapping boxes', () => {
-    const b2 = { min: { x: 1, y: 1, z: 1 }, max: { x: 3, y: 3, z: 3 } };
-    expect(aabbMath.intersects(box, b2)).toBe(true);
-  });
-
-  it('intersects non-overlapping boxes', () => {
-    const b3 = { min: { x: 5, y: 5, z: 5 }, max: { x: 8, y: 8, z: 8 } };
-    expect(aabbMath.intersects(box, b3)).toBe(false);
-  });
-
-  it('expand to include point', () => {
-    const expanded = aabbMath.expand(box, { x: 5, y: 5, z: 5 });
-    expect(expanded.max.x).toBe(5);
-    expect(expanded.min.x).toBe(0);
-  });
-
-  it('merge', () => {
-    const b2 = { min: { x: 1, y: 1, z: 1 }, max: { x: 5, y: 5, z: 5 } };
-    const merged = aabbMath.merge(box, b2);
-    expect(merged.max.x).toBe(5);
-    expect(merged.min.x).toBe(0);
-  });
-});
-
-// ═══════════════════════════════════════════════
-// math — noise
-// ═══════════════════════════════════════════════
-describe('noise', () => {
-  it('perlin2d returns value in range', () => {
-    const v = noise.perlin2d(0.5, 0.5);
-    expect(typeof v).toBe('number');
-    expect(v).toBeGreaterThanOrEqual(-1);
-    expect(v).toBeLessThanOrEqual(1);
-  });
-
-  it('perlin3d returns value in range', () => {
-    const v = noise.perlin3d(0.5, 0.5, 0.5);
-    expect(v).toBeGreaterThanOrEqual(-1);
-    expect(v).toBeLessThanOrEqual(1);
-  });
-
-  it('fbm returns numeric value', () => {
-    const v = noise.fbm(0.5, 0.5, 4);
-    expect(typeof v).toBe('number');
-  });
-
-  it('simplex returns value', () => {
-    const v = noise.simplex(0.3, 0.7);
-    expect(typeof v).toBe('number');
-  });
-
-  it('worley returns value in range', () => {
-    const v = noise.worley(1, 2, 3);
-    expect(v).toBeGreaterThanOrEqual(0);
-  });
-
-  it('same inputs produce same output (deterministic)', () => {
-    expect(noise.perlin2d(1.23, 4.56)).toBe(noise.perlin2d(1.23, 4.56));
-  });
-});
-
-// ═══════════════════════════════════════════════
-// math — random
-// ═══════════════════════════════════════════════
-describe('random', () => {
-  it('float returns [0,1)', () => {
-    for (let i = 0; i < 20; i++) {
-      const v = random.float();
-      expect(v).toBeGreaterThanOrEqual(0);
-      expect(v).toBeLessThan(1);
-    }
-  });
-
-  it('range returns value in [min,max)', () => {
-    for (let i = 0; i < 20; i++) {
-      const v = random.range(5, 10);
-      expect(v).toBeGreaterThanOrEqual(5);
-      expect(v).toBeLessThan(10);
-    }
-  });
-
-  it('int returns integer in [min,max]', () => {
-    for (let i = 0; i < 20; i++) {
-      const v = random.int(1, 6);
-      expect(Number.isInteger(v)).toBe(true);
-      expect(v).toBeGreaterThanOrEqual(1);
-      expect(v).toBeLessThanOrEqual(6);
-    }
-  });
-
-  it('bool returns boolean', () => {
-    expect(typeof random.bool()).toBe('boolean');
-  });
-
-  it('pick returns element from array', () => {
-    const arr = [10, 20, 30];
-    const v = random.pick(arr);
-    expect(arr).toContain(v);
-  });
-
-  it('shuffle returns array of same length', () => {
-    const arr = [1, 2, 3, 4, 5];
-    const s = random.shuffle([...arr]);
-    expect(s.length).toBe(arr.length);
-  });
-
-  it('seeded RNG is deterministic', () => {
-    const rng1 = random.seeded(42);
-    const rng2 = random.seeded(42);
-    expect(rng1()).toBe(rng2());
-  });
-
-  it('insideUnitSphere returns point within sphere', () => {
-    const p = random.insideUnitSphere();
-    const len = Math.sqrt(p.x * p.x + p.y * p.y + p.z * p.z);
-    expect(len).toBeLessThanOrEqual(1 + EPSILON);
-  });
-
-  it('insideUnitCircle returns 2D point within circle', () => {
-    const p = random.insideUnitCircle();
-    const len = Math.sqrt(p.x * p.x + p.y * p.y);
-    expect(len).toBeLessThanOrEqual(1 + EPSILON);
-  });
-});
-
-// ═══════════════════════════════════════════════
-// string utilities
-// ═══════════════════════════════════════════════
-describe('string — case conversion', () => {
-  it('capitalize', () => expect(capitalize('hello world')).toBe('Hello world'));
-  it('titleCase', () => expect(titleCase('hello world')).toBe('Hello World'));
-  it('camelCase', () => expect(camelCase('hello world')).toBe('helloWorld'));
-  it('pascalCase', () => expect(pascalCase('hello world')).toBe('HelloWorld'));
-  it('snakeCase', () => expect(snakeCase('helloWorld')).toBe('hello_world'));
-  it('kebabCase', () => expect(kebabCase('helloWorld')).toBe('hello-world'));
-  it('constantCase', () => expect(constantCase('helloWorld')).toBe('HELLO_WORLD'));
-});
-
-describe('string — padding and truncation', () => {
-  it('padLeft', () => expect(padLeft('hi', 5)).toBe('   hi'));
-  it('padRight', () => expect(padRight('hi', 5)).toBe('hi   '));
-  it('center', () => {
-    const s = center('hi', 6);
-    expect(s.length).toBe(6);
-    expect(s).toContain('hi');
-  });
-  it('truncate', () => {
-    const t = truncate('hello world', 8);
-    expect(t.length).toBeLessThanOrEqual(8);
-  });
-  it('truncateMiddle', () => {
-    const t = truncateMiddle('hello world', 7);
-    expect(t.length).toBeLessThanOrEqual(7);
-  });
-});
-
-describe('string — checks', () => {
-  it('isBlank / isNotBlank', () => {
-    expect(isBlank('')).toBe(true);
-    expect(isBlank('  ')).toBe(true);
-    expect(isNotBlank('a')).toBe(true);
-  });
-
-  it('containsIgnoreCase', () => {
-    expect(containsIgnoreCase('Hello World', 'world')).toBe(true);
-    expect(containsIgnoreCase('Hello World', 'xyz')).toBe(false);
-  });
-
-  it('startsWithIgnoreCase', () => {
-    expect(startsWithIgnoreCase('Hello', 'hello')).toBe(true);
-  });
-
-  it('endsWithIgnoreCase', () => {
-    expect(endsWithIgnoreCase('World', 'WORLD')).toBe(true);
-  });
-
-  it('isValidIdentifier', () => {
-    expect(isValidIdentifier('myVar')).toBe(true);
-    expect(isValidIdentifier('123bad')).toBe(false);
-  });
-
-  it('isNumeric', () => {
-    expect(isNumeric('123')).toBe(true);
-    expect(isNumeric('12.5')).toBe(true);
-    expect(isNumeric('abc')).toBe(false);
-  });
-
-  it('isAlpha', () => {
-    expect(isAlpha('abc')).toBe(true);
-    expect(isAlpha('abc123')).toBe(false);
-  });
-
-  it('isAlphanumeric', () => {
-    expect(isAlphanumeric('abc123')).toBe(true);
-    expect(isAlphanumeric('abc!')).toBe(false);
-  });
-});
-
-describe('string — manipulation', () => {
-  it('repeat', () => expect(repeat('ab', 3)).toBe('ababab'));
-  it('reverse', () => expect(reverse('hello')).toBe('olleh'));
-  it('count occurrences', () => expect(count('hello world hello', 'hello')).toBe(2));
-  it('removeWhitespace', () => expect(removeWhitespace('h e l l o')).toBe('hello'));
-  it('collapseWhitespace', () => expect(collapseWhitespace('a  b   c')).toBe('a b c'));
-  it('removePrefix', () => expect(removePrefix('foobar', 'foo')).toBe('bar'));
-  it('removeSuffix', () => expect(removeSuffix('foobar', 'bar')).toBe('foo'));
-  it('wrap', () => expect(wrap('hello', '"')).toBe('"hello"'));
-  it('unwrap', () => expect(unwrap('"hello"', '"')).toBe('hello'));
-});
-
-describe('string — splitting', () => {
-  it('lines splits by newline', () => {
-    const l = lines('a\nb\nc');
-    expect(l).toEqual(['a', 'b', 'c']);
-  });
-  it('words splits by whitespace', () => {
-    const w = words('hello world foo');
-    expect(w).toEqual(['hello', 'world', 'foo']);
-  });
-  it('chars splits to characters', () => {
-    expect(chars('abc')).toEqual(['a', 'b', 'c']);
-  });
-});
-
-describe('string — formatting', () => {
-  it('format substitutes named placeholders', () => {
-    const result = format('Hello {name}, you are {age}!', { name: 'World', age: 42 });
-    expect(result).toContain('World');
-    expect(result).toContain('42');
-  });
-
-  it('formatBytes', () => {
-    const s = formatBytes(1024);
-    expect(s).toMatch(/KB|KiB/i);
-  });
-
-  it('formatDuration', () => {
-    const s = formatDuration(3661000);
-    expect(s).toMatch(/\d/);
-  });
-});
-
-describe('string — escaping', () => {
-  it('escapeHtml / unescapeHtml', () => {
-    const escaped = escapeHtml('<b>hello</b>');
-    expect(escaped).toContain('&lt;');
-    expect(unescapeHtml(escaped)).toBe('<b>hello</b>');
-  });
-
-  it('escapeRegex', () => {
-    const s = escapeRegex('a.b*c');
-    expect(s).toContain('\\.');
-    expect(s).toContain('\\*');
-  });
-
-  it('slugify', () => {
-    expect(slugify('Hello World!')).toBe('hello-world');
-  });
-});
-
-describe('string — similarity', () => {
-  it('levenshtein', () => {
-    expect(levenshtein('kitten', 'sitting')).toBeGreaterThan(0);
-    expect(levenshtein('abc', 'abc')).toBe(0);
-  });
-
-  it('similarity returns 1 for identical strings', () => {
-    expect(similarity('hello', 'hello')).toBe(1);
-  });
-
-  it('similarity returns value in [0,1]', () => {
-    const s = similarity('hello', 'world');
-    expect(s).toBeGreaterThanOrEqual(0);
-    expect(s).toBeLessThanOrEqual(1);
-  });
-});
-
-describe('string — indentation', () => {
-  it('indent adds prefix', () => {
-    const s = indent('a\nb', 2);
-    expect(s).toContain('  a');
-    expect(s).toContain('  b');
-  });
-
-  it('dedent removes common indentation', () => {
-    const s = dedent('  a\n  b\n  c');
-    expect(s).not.toMatch(/^  /m);
-  });
-
-  it('wordWrap wraps long lines', () => {
-    const s = wordWrap('hello world foo bar baz', 10);
-    const lineArr = s.split('\n');
-    for (const line of lineArr) {
-      expect(line.length).toBeLessThanOrEqual(10);
-    }
-  });
-});
-
-describe('string — generation', () => {
-  it('randomString generates string of given length', () => {
-    const s = randomString(10);
-    expect(s.length).toBe(10);
-    expect(typeof s).toBe('string');
-  });
-
-  it('uuid returns valid UUID format', () => {
-    const id = uuid();
-    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
-  });
-});
-
-// ═══════════════════════════════════════════════
-// time utilities
-// ═══════════════════════════════════════════════
-describe('now', () => {
-  it('returns number', () => {
-    expect(typeof now()).toBe('number');
-  });
-
-  it('increases over time', async () => {
-    const t1 = now();
-    await sleep(10);
-    const t2 = now();
-    expect(t2).toBeGreaterThan(t1);
-  });
-});
-
-describe('measure', () => {
-  it('returns duration and result', async () => {
-    const result = await measure(async () => {
-      await sleep(5);
-      return 42;
-    });
-    expect(result.duration).toBeGreaterThanOrEqual(0);
-    expect(result.result).toBe(42);
-  });
-});
-
-describe('debounce', () => {
-  it('delays function call', async () => {
-    vi.useFakeTimers();
-    const fn = vi.fn();
-    const debounced = debounce(fn, 100);
-    debounced();
-    debounced();
-    debounced();
-    expect(fn).not.toHaveBeenCalled();
-    await vi.advanceTimersByTimeAsync(150);
-    expect(fn).toHaveBeenCalledTimes(1);
-    vi.useRealTimers();
-  });
-});
-
-describe('throttle', () => {
-  it('limits call frequency', async () => {
-    vi.useFakeTimers();
-    const fn = vi.fn();
-    const throttled = throttle(fn, 100);
-    throttled();
-    throttled();
-    throttled();
-    expect(fn).toHaveBeenCalledTimes(1);
-    vi.useRealTimers();
-  });
-});
-
-describe('Stopwatch', () => {
-  it('starts and stops', async () => {
-    const sw = new Stopwatch();
-    sw.start();
-    await sleep(20);
-    sw.stop();
-    expect(sw.elapsed).toBeGreaterThan(0);
-  });
-
-  it('reset clears elapsed', () => {
-    const sw = new Stopwatch();
-    sw.start();
-    sw.stop();
-    sw.reset();
-    expect(sw.elapsed).toBe(0);
-  });
-
-  it('lap returns elapsed and resets timer', async () => {
-    const sw = new Stopwatch();
-    sw.start();
-    await sleep(10);
-    const lapTime = sw.lap();
-    expect(lapTime).toBeGreaterThan(0);
-    // after lap(), stopwatch restarted
-    expect(sw.isRunning).toBe(true);
-  });
-
-  it('restart resets and starts again', async () => {
-    const sw = new Stopwatch();
-    sw.start();
-    await sleep(10);
-    sw.restart();
-    const e = sw.elapsed;
-    expect(e).toBeLessThan(50);
-  });
-});
-
-describe('FrameTimer', () => {
-  it('tracks delta via update()', async () => {
-    const ft = new FrameTimer();
-    ft.update();
-    await sleep(16);
-    ft.update();
-    expect(ft.delta).toBeGreaterThan(0);
-    expect(ft.frames).toBeGreaterThan(0);
-  });
-});
-
-describe('DateTime', () => {
-  it('toISO returns ISO string', () => {
-    const date = new Date(2024, 0, 15);
-    const iso = DateTime.toISO(date);
-    expect(iso).toMatch(/2024-01-15/);
-  });
-
-  it('format with pattern', () => {
-    const date = new Date(2024, 0, 15, 12, 30, 45);
-    const s = DateTime.format(date, 'YYYY-MM-DD');
-    expect(s).toMatch(/2024-\d{2}-\d{2}/);
-  });
-
-  it('diff returns millisecond difference', () => {
-    const d1 = new Date(2024, 0, 1);
-    const d2 = new Date(2024, 0, 2);
-    const diff = DateTime.diff(d1, d2);
-    expect(Math.abs(diff)).toBe(86400000);
-  });
-
-  it('add adds duration', () => {
-    const d = new Date(2024, 0, 1);
-    const next = DateTime.add(d, 1, 'd');
-    expect(next.getDate()).toBe(2);
-  });
-
-  it('startOfDay / endOfDay', () => {
-    const d = new Date(2024, 0, 15, 12, 30);
-    const start = DateTime.startOfDay(d);
-    const end = DateTime.endOfDay(d);
-    expect(start.getHours()).toBe(0);
-    expect(end.getHours()).toBe(23);
-  });
-});